Flex PayGo

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

Flex PayGo를 사용하는 경우

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

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

지원되는 모델 및 위치

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

Gemini 3.1 Flash-Lite 미리보기
Gemini 3.1 Flash 이미지 미리보기
Gemini 3.1 Pro 미리보기
Gemini 3 Flash 미리보기
Gemini 3 Pro 미리보기
Gemini 3 Pro 이미지 미리보기

요청 페이로드 한도

Flex PayGo 요청은 페이로드가 요청 본문에 직접 포함된 요청의 경우 총 페이로드 크기 한도가 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를 사용하는 요청은 표준 PayGo보다 예상 지연 시간이 더 깁니다.

요청 시간 제한을 최대 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를 사용하도록 GenAI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 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입니다. Flex PayGo를 지원하는 모델 목록은 모델 버전을 참조하세요.
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입니다. Flex PayGo를 지원하는 모델 목록은 모델 버전을 참조하세요.
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의 추가 할당량

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

설명	프로젝트의 각 기본 모델에 대한 QPM
Flex PayGo를 활용하는 요청의 프로젝트에 있는 각 기본 모델의 할당량	3000

다음 단계

리소스

Flex PayGo

Flex PayGo를 사용하는 경우

지원되는 모델 및 위치

요청 페이로드 한도

Flex PayGo 사용

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

Python

설치

REST

Flex PayGo만 사용

Python

설치

REST

Flex PayGo 사용량 확인

Python

REST

Flex PayGo의 추가 할당량

다음 단계

생성형 AI 할당량 및 한도

Agent Platform 할당량 및 한도

Google Cloud 할당량

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

Flex PayGo를 사용하는 경우

지원되는 모델 및 위치

요청 페이로드 한도

Flex PayGo 사용

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

Python

설치

REST

Flex PayGo만 사용

Python

설치

REST

Flex PayGo 사용량 확인

Python

REST

Flex PayGo의 추가 할당량

다음 단계

생성형 AI 할당량 및 한도

Agent Platform 할당량 및 한도

Google Cloud 할당량

Flex PayGo