Flex PayGo

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

Flex PayGo를 사용해야 하는 경우

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

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

지원되는 모델 및 위치

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

Gemini 3 Flash 프리뷰
Gemini 3 Pro 프리뷰
Gemini 3 Pro Image 프리뷰

Flex PayGo 사용

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

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

유연한 종량제 요금을 사용하는 요청은 표준 종량제 요금보다 지연 시간이 더 깁니다. 기본 제한 시간은 20분이며 timeout 매개변수를 사용하여 밀리초 단위로 재정의할 수 있습니다. 허용되는 최댓값은 30분입니다.

프로비저닝된 처리량을 기본값으로 사용하는 동안 Flex PayGo 사용

Flex PayGo를 사용하기 전에 사용 가능한 프로비저닝된 처리량 할당량을 활용하려면 다음 샘플에 표시된 대로 요청에 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와 상호작용하기 위해 코드를 추가로 조정할 필요가 없습니다.

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입니다. Flex PayGo를 지원하는 모델 목록은 모델 버전을 참고하세요.
PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \  # Timeout in milliseconds
  -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.0-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.

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

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입니다. Flex PayGo를 지원하는 모델 목록은 모델 버전을 참고하세요.
PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \  # Timeout in milliseconds
  -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.0-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.

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의 추가 할당량

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

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

다음 단계

Vertex AI의 할당량 및 한도에 대한 자세한 내용은 Vertex AI 할당량 및 한도를 참조하세요.
Google Cloud 할당량 및 시스템 한도에 대해 자세히 알아보려면 Cloud 할당량 문서를 참조하세요.

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

Flex PayGo를 사용해야 하는 경우

지원되는 모델 및 위치

Flex PayGo 사용

프로비저닝된 처리량을 기본값으로 사용하는 동안 Flex PayGo 사용

Python

설치

REST

Flex PayGo만 사용

Python

설치

REST

Flex PayGo 사용량 확인

Python

REST

Flex PayGo의 추가 할당량

다음 단계

Flex PayGo