PayGo prioritario

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

Cuando usas la opción de pago por uso prioritario, se te cobra por el uso de tokens a una tarifa más alta que la de la opción de pago por uso estándar. Para obtener información sobre los precios, consulta la página de precios de Vertex AI.

Cuándo usar Priority PayGo

Priority PayGo es ideal para las cargas de trabajo críticas y sensibles a la latencia con patrones de tráfico fluctuantes o impredecibles. Estos son algunos ejemplos de casos de uso:

  • Asistentes virtuales para clientes

  • Procesamiento de datos y documentos sensible a la latencia

  • Flujos de trabajo de agentes e interacciones entre agentes

  • Simulaciones de investigación

Modelos y ubicaciones compatibles

Los siguientes modelos admiten Priority PayGo solo en el extremo global. Priority PayGo no admite extremos regionales ni multirregionales.

Usa Priority PayGo

Para enviar solicitudes a la API de Gemini en Vertex AI con la opción de pago por uso con prioridad, 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 a Priority PayGo.

  • Usar solo Priority PayGo

Usa Priority PayGo 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 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_VERTEXAI=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: El ID del proyecto.
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar el pago por prioridad. 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
  }
}
Ten en cuenta lo siguiente en la URL para esta muestra:
  • 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-2.0-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 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_VERTEXAI=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: El ID del proyecto.
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar el pago por prioridad. 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
  }
}
Ten en cuenta lo siguiente en la URL para esta muestra:
  • 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-2.0-flash). Esta muestra también puede admitir otros modelos.

Verifica el uso de Priority PayGo

Puedes verificar si una solicitud utilizó el modelo de pago por uso prioritario 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=
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=nishReason.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=ty.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=ty.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=fficType.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 aceleración

Priority PayGo establece límites de aumento a nivel de la organización. Los límites de aumento gradual ayudan a proporcionar un rendimiento predecible y coherente. El límite inicial depende del modelo, como se indica a continuación:

  • Modelos Gemini Flash y Flash-Lite: 4 millones de tokens por minuto
  • Modelos de Gemini Pro: 1 millón de tokens por minuto

El límite de aumento se incrementa en un 50% por cada 10 minutos de uso sostenido.

Si una solicitud supera el límite de aumento y el sistema está sobrecargado debido a cargas altas de tráfico, la solicitud se degrada a la opción de pago por uso estándar y se cobra a las tarifas de pago por uso estándar.

Para minimizar las degradaciones, aumenta el uso de forma incremental para mantenerte dentro del límite. Si aún necesitas un mejor rendimiento, considera comprar cuota de capacidad de procesamiento aprovisionada adicional.

Puedes verificar si una solicitud se degradó a partir de la respuesta. En el caso de las solicitudes que se degradan al plan Estándar de pago por uso, 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.

¿Qué sigue?