Flex PayGo

유연한 사용한 만큼만 지불 (Flex PayGo)은 응답 시간이 길어지고 제한이 더 많이 적용되어도 되는 비중요 워크로드에 Gemini 모델을 액세스하기 위한 비용 효율적인 옵션입니다. Flex 종량제는 Standard 종량제에 비해 50% 할인된 가격으로 제공됩니다.

Flex PayGo를 사용해야 하는 경우

Flex PayGo는 동기식, 지연 시간 허용, 시간에 민감하지 않은 비중요 작업에 적합합니다. 사용 사례 예시는 다음과 같습니다.

텍스트, 문서, 이미지, 오디오, 동영상 파일의 오프라인 분석
모델 품질 평가
데이터 주석 및 라벨 지정
문서 번역
제품 카탈로그 빌드

지원되는 모델 및 위치

다음 미리보기 Gemini 모델은 global 엔드포인트에서만 유연한 종량제를 지원합니다. Flex PayGo는 리전 또는 멀티 리전 엔드포인트를 지원하지 않습니다.

요청 페이로드 한도

Flex PayGo 요청의 총 페이로드 크기 제한은 20MB입니다. 페이로드가 20MB를 초과하는 경우 대신 Cloud Storage URI를 제공하세요.

Flex PayGo 사용

Flex PayGo를 사용하여 Gemini API에 요청을 보내려면 요청에 X-Vertex-AI-LLM-Shared-Request-Type 헤더를 포함해야 합니다. Flex PayGo는 다음 두 가지 방법으로 사용할 수 있습니다.

프로비저닝된 처리량 할당량 (사용 가능한 경우)을 사용한 다음 Flex PayGo를 사용합니다.
Flex PayGo만 사용합니다.

Flex PayGo를 사용하는 요청은 Standard PayGo보다 예상 지연 시간이 더 깁니다.

요청 제한 시간을 최대 30분으로 설정할 수 있습니다.

PT를 기본값으로 사용하는 동안 Flex PayGo 사용

유연한 종량제 요금을 사용하기 전에 사용 가능한 PT 할당량을 사용하려면 다음 샘플과 같이 요청에 X-Vertex-AI-LLM-Shared-Request-Type: flex 헤더를 포함하세요.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Gen AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

Flex PayGo를 사용하도록 생성형 AI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 Flex PayGo를 사용하여 Gemini API와 상호작용하기 위해 코드를 추가로 조정할 필요가 없습니다.

timeout 파라미터를 사용하여 기본 제한 시간을 재정의할 수 있습니다. 시간 제한은 밀리초 단위로 지정됩니다.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID
MODEL_ID: Flex PayGo를 초기화할 모델의 모델 ID입니다.
PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.

X-Server-Timeout 헤더를 설정하여 기본 제한 시간을 재정의할 수 있습니다. 시간 제한은 초 단위로 지정됩니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

다음과 비슷한 JSON 응답이 수신됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}

이 샘플의 URL에서 다음 사항을 참고하세요.

응답이 완전히 생성된 후 반환되도록 요청하려면 generateContent 메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면 streamGenerateContent 메서드를 사용하여 생성되는 응답을 스트리밍합니다.
멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다(예: gemini-2.5-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.
리전 API 엔드포인트 (예: us-central1)를 사용하면 엔드포인트 URL의 리전에 따라 요청이 처리되는 위치가 결정됩니다. 리소스 경로의 충돌하는 위치는 무시됩니다.

Flex PayGo만 사용

Flex PayGo만 사용하려면 다음 샘플과 같이 요청에 X-Vertex-AI-LLM-Request-Type: shared 및 X-Vertex-AI-LLM-Shared-Request-Type: flex 헤더를 포함하세요.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Gen AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

timeout 파라미터를 사용하여 기본 제한 시간을 재정의할 수 있습니다. 시간 제한은 밀리초 단위로 지정됩니다.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID
MODEL_ID: Flex PayGo를 초기화할 모델의 모델 ID입니다.
PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.

X-Server-Timeout 헤더를 설정하여 기본 제한 시간을 재정의할 수 있습니다. 시간 제한은 초 단위로 지정됩니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

다음과 비슷한 JSON 응답이 수신됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}

이 샘플의 URL에서 다음 사항을 참고하세요.

응답이 완전히 생성된 후 반환되도록 요청하려면 generateContent 메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면 streamGenerateContent 메서드를 사용하여 생성되는 응답을 스트리밍합니다.
멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다(예: gemini-2.5-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.
리전 API 엔드포인트 (예: us-central1)를 사용하면 엔드포인트 URL의 리전에 따라 요청이 처리되는 위치가 결정됩니다. 리소스 경로의 충돌하는 위치는 무시됩니다.

Flex PayGo 사용량 확인

다음 예와 같이 응답의 트래픽 유형에서 요청이 Flex PayGo를 사용했는지 확인할 수 있습니다.

Python

응답의 traffic_type 필드에서 요청에 Flex PayGo가 사용되었는지 확인할 수 있습니다. 요청이 Flex PayGo를 사용하여 처리된 경우 traffic_type 필드는 ON_DEMAND_FLEX로 설정됩니다.

sdk_http_response=HttpResponse(
  headers=
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=<FinishReason.STOP: 'STOP'>
)] create_time=datetime.datetime(2025, 12, 3, 20, 32, 55, 916498, tzinfo=TzInfo(0)) model_version='gemini-2.5-flash' prompt_feedback=None response_id='response_id' usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=1408,
  candidates_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=<TrafficType.ON_DEMAND_FLEX: 'ON_DEMAND_FLEX'>
) automatic_function_calling_history=[] parsed=None

REST

응답의 trafficType 필드에서 요청에 Flex PayGo가 사용되었는지 확인할 수 있습니다. 요청이 Flex PayGo를 사용하여 처리된 경우 trafficType 필드는 ON_DEMAND_FLEX로 설정됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}

Flex PayGo의 추가 할당량

콘텐츠 생성 요청에 사용할 수 있는 할당량 (오버플로 트래픽의 PT 할당량 포함) 외에도 Flex PayGo를 사용하는 요청에는 다음 할당량이 적용됩니다.

설명	프로젝트의 각 기본 모델에 대한 QPM
유연한 종량제 요금을 사용하는 프로젝트 요청의 각 기본 모델 할당량	3000

Flex PayGo 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Flex PayGo를 사용해야 하는 경우

지원되는 모델 및 위치

요청 페이로드 한도

Flex PayGo 사용

PT를 기본값으로 사용하는 동안 Flex PayGo 사용

Python

설치

REST

Flex PayGo만 사용

Python

설치

REST

Flex PayGo 사용량 확인

Python

REST

Flex PayGo의 추가 할당량

Flex PayGo