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 el PayGo estándar. Para obtener información sobre los precios, consulta la página de precios de Gemini Enterprise Agent Platform.

Cuándo usar el PayGo prioritario

El PayGo prioritario es ideal para cargas de trabajo críticas para la empresa con patrones de tráfico fluctuantes o impredecibles. A continuación, se incluyen casos de uso de ejemplo:

  • Asistentes virtuales orientados al cliente
  • Agentic Workflows e interacciones entre agentes
  • Simulaciones de investigación

Modelos y ubicaciones compatibles

En general, el PayGo prioritario es compatible con los extremos global, us y eu. Sin embargo, es posible que algunos modelos (como los modelos 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 el PayGo prioritario.

Los siguientes modelos admiten el PayGo prioritario:

Usa el PayGo prioritario

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

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

  • Usa solo el PayGo prioritario.

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 predeterminada

Para utilizar cualquier cuota de capacidad de procesamiento aprovisionada disponible antes de usar el PayGo prioritario, 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 GenAI para usar el PayGo prioritario. Después de realizar este paso, no necesitarás hacer más ajustes en tu código para interactuar con la API de Gemini con el PayGo 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: El ID del modelo para el que deseas inicializar el PayGo prioritario. Para obtener una lista de los modelos que admiten PayGo 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 generateContent método 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 streamGenerateContent método.
  • 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.

Usa solo el PayGo prioritario

Para usar solo el PayGo prioritario, 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 GenAI para usar el PayGo prioritario. Después de realizar este paso, no necesitarás hacer más ajustes en tu código para interactuar con la API de Gemini con el PayGo 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: El ID del modelo para el que deseas inicializar el PayGo prioritario. Para obtener una lista de los modelos que admiten PayGo 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 generateContent método 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 streamGenerateContent método.
  • 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 del PayGo prioritario

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

Python

Puedes verificar si se usó el PayGo prioritario para una solicitud desde el campo traffic_type en la respuesta. Si tu solicitud se procesó con el PayGo prioritario, 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ó el PayGo prioritario para una solicitud desde el campo trafficType en la respuesta. Si tu solicitud se procesó con el PayGo prioritario, 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

El PayGo prioritario 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 de 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 aumento gradual ni es necesario generar un uso sostenido antes de que puedas alcanzarlos. Al igual que el PayGo 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 dentro de esa familia.

El tráfico que supera tu límite no se degrada automáticamente. Cuando la capacidad está disponible, Agent Platform continúa entregando ese tráfico con prioridad y se factura según las tarifas del PayGo prioritario. Las solicitudes se degradan al PayGo estándar solo cuando no hay capacidad de reserva para entregarlas con prioridad, y esas solicitudes se facturan según las tarifas del PayGo estándar.

Puedes verificar si una solicitud se degradó de la respuesta. Para las solicitudes degradadas al PayGo estándar, el tipo de tráfico se establece en ON_DEMAND. Para obtener más información, consulta Verifica el uso del PayGo prioritario.

Para reducir la posibilidad de una degradación, suaviza el tráfico 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?