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 inicial de la capacidad de procesamiento aprovisionada.

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

Cuándo usar el pago por uso prioritario

El pago por uso prioritario es ideal para cargas de trabajo críticas para la empresa con patrones de tráfico fluctuantes o impredecibles. Los siguientes son casos de uso de ejemplo:

  • Asistentes virtuales orientados al cliente
  • Flujos de trabajo de agentes e interacciones entre agentes
  • Simulaciones de investigación

Modelos y ubicaciones compatibles

Los siguientes modelos admiten el pago por uso prioritario solo en el extremo global. El pago por uso prioritario no admite extremos regionales ni multirregionales.

Usa el pago por uso prioritario

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

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

  • Usa solo el pago por uso prioritario.

Usa el pago por uso 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 el pago por uso 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.

Configura las variables de entorno para usar el SDK de Gen AI 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 GenAI para usar el pago por uso 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 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: Es tu [ID del proyecto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar el pago por uso prioritario. Para obtener una lista de los modelos que admiten el pago por uso prioritario, consulta Versiones del modelo.
  • PROMPT_TEXT: Son 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-2.0-flash). Esta muestra también puede admitir otros modelos.

Usa solo el pago por uso prioritario

Para usar solo el pago por uso 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.

Configura las variables de entorno para usar el SDK de Gen AI 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 GenAI para usar el pago por uso 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 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: Es tu [ID del proyecto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: Es el ID del modelo para el que deseas inicializar el pago por uso prioritario. Para obtener una lista de los modelos que admiten el pago por uso prioritario, consulta Versiones del modelo.
  • PROMPT_TEXT: Son 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-2.0-flash). Esta muestra también puede admitir otros modelos.

Verifica el uso del pago por uso prioritario

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

Python

Puedes verificar si se utilizó el pago por uso prioritario para una solicitud desde el campo traffic_type en la respuesta. Si tu solicitud se procesó con el pago por uso 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 utilizó el pago por uso prioritario para una solicitud desde el campo trafficType en la respuesta. Si tu solicitud se procesó con el pago por uso 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 aumento

El pago por uso prioritario establece límites de aumento a nivel de la organización. Los límites de aumento ayudan a proporcionar un rendimiento predecible y coherente. El límite inicial depende del modelo, de la siguiente manera:

  • Modelos de 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 aumenta en un 50% por cada 10 minutos de uso continuo.

Si una solicitud excede el límite de aumento o el sistema está temporalmente sobrecargado debido a cargas de tráfico altas, es posible que la solicitud se cambie al pago por uso estándar y se cobre con las tarifas de este.

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

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

¿Qué sigue?