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 PayGo prioritario, se te cobra por uso de token con una tarifa más alta que con 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. Los siguientes son ejemplos de casos de uso:

  • Asistentes virtuales orientados al cliente
  • Flujos de trabajo de agentes e interacciones entre agentes
  • 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 de Gemini 2.5) no admitan los tres extremos. Consulta las páginas de modelos individuales vinculadas desde Modelos de Google para ver qué extremos se admiten cuando se usa Priority PayGo.

Los siguientes modelos admiten Priority PayGo:

Usar PayGo prioritario

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:

  • Usa la cuota de capacidad de procesamiento aprovisionada (si está disponible) y desborda al PayGo prioritario.

  • Usa solo 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 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 PayGo prioritario mientras usas la capacidad de procesamiento aprovisionada como predeterminada

Para usar 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 Priority PayGo 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: Es el 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 Priority PayGo, consulta Versiones de modelos.
  • 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 PayGo prioritario

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 Priority PayGo 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: Es el 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 Priority PayGo, consulta Versiones de modelos.
  • 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 usó Priority PayGo a partir del tipo de tráfico en la respuesta, como se muestra en los siguientes ejemplos.

Python

Puedes verificar si se usó 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 usó 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 de tokens por minuto

Estos límites están disponibles para tu organización de inmediato. No hay un período de adaptación ni es necesario generar un uso continuo antes de poder alcanzarlos. Al igual que en el pago por uso estándar, el límite de capacidad de procesamiento que se muestra para una familia de modelos se aplica de forma independiente a cada modelo de esa familia.

El tráfico que supera tu límite no se degrada automáticamente. Cuando hay capacidad disponible, Agent Platform sigue entregando ese tráfico con prioridad y se factura con las tarifas de Priority PayGo. Las solicitudes se cambian a pago por uso estándar solo cuando no hay capacidad libre para atenderlas con prioridad, y esas solicitudes se facturan con las tarifas de pago por uso estándar.

Puedes verificar si una solicitud se cambió a una versión anterior a partir de la respuesta. Para las solicitudes que se cambian al nivel Estándar de pago por uso, el tipo de tráfico se establece en ON_DEMAND. Para obtener más información, consulta Verifica el uso de Priority PayGo.

Para reducir la probabilidad de que se produzca una reducción de nivel, suaviza el tráfico en cada minuto en lugar de enviar picos pronunciados de segundo nivel. 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?