PayGo prioritario

El pago por uso prioritario (PayGo prioritario) es una opción de consumo que proporciona un rendimiento más coherente que el PayGo estándar sin el compromiso inicial de la capacidad de procesamiento aprovisionada.

Cuando usas el PayGo prioritario, se te cobra por el uso de tokens a una tarifa más alta que la del PayGo estándar. Para obtener información sobre los precios, consulta la página de precios de Gemini Enterprise Agent Platform.

Cuándo usar Priority PayGo

Priority PayGo es ideal para cargas de trabajo fundamentales para la empresa con patrones de tráfico fluctuantes o impredecibles. A continuación, se incluyen ejemplos de casos de uso:

  • Asistentes virtuales orientados al cliente
  • Flujos de trabajo de agentes y sus interacciones
  • Simulaciones de investigación

Modelos y ubicaciones compatibles

En general, Priority PayGo se admite en los extremos global, us y eu. Sin embargo, es posible que algunos modelos (como los modelos de Gemini 2.5) no admitan los tres extremos. Consulta las páginas de los modelos individuales vinculadas desde Modelos de Google para ver qué extremos se admiten cuando se usa la opción de pago por uso prioritario.

Los siguientes modelos admiten la modalidad de pago por uso prioritario:

Cómo usar Priority PayGo

Para enviar solicitudes a la API de Gemini con Priority PayGo, debes incluir el encabezado X-Vertex-AI-LLM-Shared-Request-Type en tu solicitud. Puedes usar Priority PayGo de dos maneras:

  • Usar la cuota de capacidad de procesamiento aprovisionada (si está disponible) y transferir el exceso al PayGo prioritario

  • Solo se puede usar Priority PayGo.

En los siguientes ejemplos, se usa el extremo global. Para enviar tus solicitudes a un extremo multirregional, reemplaza global por us o eu. Para las solicitudes de REST, también debes reemplazar el nombre de host aiplatform.googleapis.com por aiplatform.us.rep.googleapis.com o aiplatform.eu.rep.googleapis.com. Para obtener más información, consulta Extremos multirregionales.

Usa el PayGo prioritario mientras usas la capacidad de procesamiento aprovisionada como opción predeterminada

Para utilizar cualquier cuota de capacidad de procesamiento aprovisionada disponible antes de usar Priority PayGo, incluye el encabezado X-Vertex-AI-LLM-Shared-Request-Type: priority en tus solicitudes, como se muestra en los siguientes ejemplos.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa de Google con Vertex AI: 

# 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_ENTERPRISE=True

Inicializa tu cliente de IA generativa para usar Priority PayGo. Después de realizar este paso, no necesitarás hacer más ajustes en tu código para interactuar con la API de Gemini usando la opción de pago por uso prioritario en el mismo cliente.

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": "priority"
      },
  )
)

REST

Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Tu ID del proyecto. .
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar Priority PayGo. Para obtener una lista de los modelos que admiten el pago por uso prioritario, consulta Versiones del modelo.
  • PROMPT_TEXT: Las instrucciones de texto que se incluirán en el mensaje. JSON.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • Usa el método generateContent para solicitar que la respuesta se muestre después de que se haya generado por completo. Para reducir la percepción de latencia a un público humano, transmite la respuesta a medida que se genera; para ello, usa el método streamGenerateContent.
  • El ID del modelo multimodal se encuentra al final de la URL antes del método (por ejemplo, gemini-3.5-flash). Esta muestra también puede admitir otros modelos.

Usar solo Priority PayGo

Para usar solo Priority PayGo, incluye los encabezados X-Vertex-AI-LLM-Request-Type: shared y X-Vertex-AI-LLM-Shared-Request-Type: priority en tus solicitudes, como se muestra en los siguientes ejemplos.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa de Google con Vertex AI: 

# 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_ENTERPRISE=True

Inicializa tu cliente de IA generativa para usar Priority PayGo. Después de realizar este paso, no necesitarás hacer más ajustes en tu código para interactuar con la API de Gemini usando la opción de pago por uso prioritario en el mismo cliente.

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": "priority"
      },
  )
)

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Tu ID del proyecto. .
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar Priority PayGo. Para obtener una lista de los modelos que admiten el pago por uso prioritario, consulta Versiones del modelo.
  • PROMPT_TEXT: Las instrucciones de texto que se incluirán en el mensaje. JSON.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • Usa el método generateContent para solicitar que la respuesta se muestre después de que se haya generado por completo. Para reducir la percepción de latencia a un público humano, transmite la respuesta a medida que se genera; para ello, usa el método streamGenerateContent.
  • El ID del modelo multimodal se encuentra al final de la URL antes del método (por ejemplo, gemini-3.5-flash). Esta muestra también puede admitir otros modelos.

Verifica el uso de Priority PayGo

Puedes verificar si una solicitud utilizó Priority PayGo a partir del tipo de tráfico en la respuesta, como se muestra en los siguientes ejemplos.

Python

Puedes verificar si se utilizó Priority PayGo para una solicitud desde el campo traffic_type en la respuesta. Si tu solicitud se procesó con Priority PayGo, el campo traffic_type se establece en ON_DEMAND_PRIORITY.

sdk_http_response=HttpResponse(
  headers=<dict len=9>
) 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_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

Puedes verificar si se utilizó Priority PayGo para una solicitud desde el campo trafficType en la respuesta. Si tu solicitud se procesó con Priority PayGo, el campo trafficType se establece en ON_DEMAND_PRIORITY.

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

Límites de capacidad de procesamiento

Priority PayGo proporciona un límite de capacidad de procesamiento de referencia a nivel de la organización para cada modelo:

  • Modelos de Gemini Pro: 10,000,000 de tokens por minuto
  • Modelos Gemini Flash y Flash-Lite: 50,000,000 tokens por minuto

Estos límites estarán disponibles para tu organización de inmediato. No hay período de adaptación y no es necesario generar un uso sostenido antes de poder comunicarte con ellos. Al igual que con Standard PayGo, el límite de capacidad de procesamiento que se muestra para una familia de modelos se aplica de forma independiente a cada modelo dentro de esa familia.

El tráfico que supere tu límite no se degradará automáticamente. Cuando hay capacidad disponible, Agent Platform sigue entregando ese tráfico con prioridad y se factura según las tarifas de Priority PayGo. Las solicitudes se degradan a PayGo estándar solo cuando no hay capacidad de reserva para atenderlas con prioridad, y esas solicitudes se facturan a las tarifas de PayGo estándar.

Puedes verificar si una solicitud se degradó a partir de la respuesta. En el caso de las solicitudes que se degradan a pago por uso estándar, el tipo de tráfico se establece en ON_DEMAND. Para obtener más información, consulta Cómo verificar el uso de Priority PayGo.

Para reducir las posibilidades de que se produzca una degradación, suaviza el tráfico en cada minuto en lugar de enviar picos pronunciados a nivel de segundos. Si tu carga de trabajo requiere un límite más alto, comunícate con tu equipo de ventas. Para las cargas de trabajo que necesitan capacidad dedicada y garantizada, consulta Capacidad de procesamiento aprovisionada.

¿Qué sigue?