PayGo prioritaire

Le paiement à l'usage prioritaire est une option de consommation qui offre des performances plus cohérentes que le paiement à l'usage standard, sans l'engagement initial du débit provisionné.

Lorsque vous utilisez le paiement à l'usage prioritaire, vous êtes facturé par utilisation de jeton à un tarif plus élevé que le paiement à l'usage standard. Pour en savoir plus sur les tarifs, consultez la page Tarifs de la plate-forme d'agents Gemini Enterprise.

Quand utiliser le paiement à l'usage prioritaire ?

Le paiement à l'usage prioritaire est idéal pour les charges de travail critiques avec des schémas de trafic fluctuants ou imprévisibles. Voici des exemples de cas d'utilisation :

  • Assistants virtuels destinés aux clients
  • Workflows agentifs et interactions entre agents
  • Simulations de recherche

Modèles et emplacements compatibles

Les modèles suivants sont compatibles avec le paiement à l'usage prioritaire uniquement dans le point de terminaison global. Le paiement à l'usage prioritaire n'est pas compatible avec les points de terminaison régionaux ni multirégionaux.

Utiliser le paiement à l'usage prioritaire

Pour envoyer des requêtes à l'API Gemini dans la plate-forme d'agents Gemini Enterprise à l'aide du paiement à l'usage prioritaire, vous devez inclure l'en-tête X-Vertex-AI-LLM-Shared-Request-Type dans votre requête. Vous pouvez utiliser le paiement à l'usage prioritaire de deux manières :

  • Utiliser le quota de débit provisionné (si disponible) et passer au paiement à l'usage prioritaire.

  • Utiliser uniquement le paiement à l'usage prioritaire.

Utiliser le paiement à l'usage prioritaire tout en utilisant le débit provisionné par défaut

Pour utiliser tout quota de débit provisionné disponible avant d'utiliser le paiement à l'usage prioritaire, incluez l'en-tête X-Vertex-AI-LLM-Shared-Request-Type: priority dans vos requêtes, comme illustré dans les exemples suivants.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec 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

Initialisez votre client GenAI pour utiliser le paiement à l'usage prioritaire. Une fois cette étape effectuée, vous n'aurez plus besoin d'apporter d'autres modifications à votre code pour interagir avec l'API Gemini à l'aide du paiement à l'usage prioritaire sur le même client.

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

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : l'ID de votre projet.
  • MODEL_ID : ID du modèle pour lequel vous souhaitez initialiser le paiement à l'usage prioritaire. Pour obtenir la liste des modèles compatibles avec le paiement à l'usage prioritaire, consultez la section Versions de modèle.
  • PROMPT_TEXT : instructions textuelles à inclure dans le prompt. 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" }
    }
  }'

Vous devriez recevoir une réponse JSON semblable à la suivante.

{
  "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
  }
}
  • Utilisez la generateContent méthode pour demander que la réponse soit renvoyée une fois qu'elle a été entièrement générée. Pour réduire la perception de la latence auprès d'un public humain, affichez la réponse progressivement à mesure qu'elle est générée à l'aide de la méthode streamGenerateContent.
  • L'ID du modèle multimodal se trouve à la fin de l'URL avant la méthode (par exemple, gemini-2.0-flash). Cet exemple peut également s'appliquer à d'autres modèles.

Utiliser uniquement le paiement à l'usage prioritaire

Pour utiliser uniquement le paiement à l'usage prioritaire, incluez les en-têtes X-Vertex-AI-LLM-Request-Type: shared et X-Vertex-AI-LLM-Shared-Request-Type: priority dans vos requêtes, comme illustré dans les exemples suivants.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec 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

Initialisez votre client GenAI pour utiliser le paiement à l'usage prioritaire. Une fois cette étape effectuée, vous n'aurez plus besoin d'apporter d'autres modifications à votre code pour interagir avec l'API Gemini à l'aide du paiement à l'usage prioritaire sur le même client.

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

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : l'ID de votre projet.
  • MODEL_ID : ID du modèle pour lequel vous souhaitez initialiser le paiement à l'usage prioritaire. Pour obtenir la liste des modèles compatibles avec le paiement à l'usage prioritaire, consultez la section Versions de modèle.
  • PROMPT_TEXT : instructions textuelles à inclure dans le prompt. 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" }
    }
  }'

Vous devriez recevoir une réponse JSON semblable à la suivante.

{
  "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
  }
}
  • Utilisez la generateContent méthode pour demander que la réponse soit renvoyée une fois qu'elle a été entièrement générée. Pour réduire la perception de la latence auprès d'un public humain, affichez la réponse progressivement à mesure qu'elle est générée à l'aide de la méthode streamGenerateContent.
  • L'ID du modèle multimodal se trouve à la fin de l'URL avant la méthode (par exemple, gemini-2.0-flash). Cet exemple peut également s'appliquer à d'autres modèles.

Vérifier l'utilisation du paiement à l'usage prioritaire

Vous pouvez vérifier si une requête a utilisé le paiement à l'usage prioritaire à partir du type de trafic dans la réponse, comme illustré dans les exemples suivants.

Python

Vous pouvez vérifier si le paiement à l'usage prioritaire a été utilisé pour une requête à partir du champ traffic_type dans la réponse. Si votre requête a été traitée à l'aide du paiement à l'usage prioritaire, le champ traffic_type est défini sur 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

Vous pouvez vérifier si le paiement à l'usage prioritaire a été utilisé pour une requête à partir du champ trafficType dans la réponse. Si votre requête a été traitée à l'aide du paiement à l'usage prioritaire, le champ trafficType est défini sur 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
  }
}

Limites de montée en charge

Le paiement à l'usage prioritaire définit des limites de montée en charge au niveau de l'organisation. Les limites de montée en charge contribuent à fournir des performances prévisibles et cohérentes. La limite de départ dépend du modèle, comme suit :

  • Modèles Gemini Flash et Flash-Lite : 4 millions de jetons/min
  • Modèles Gemini Pro : 1 million de jetons/min

La limite de montée en charge augmente de 50 % toutes les 10 minutes d'utilisation continue.

Si une requête dépasse la limite de montée en charge et que le système est surchargé en raison de charges de trafic élevées, la requête est rétrogradée au paiement à l'usage standard et est facturée aux tarifs du paiement à l'usage standard.

Pour minimiser les rétrogradations, faites évoluer l'utilisation de manière incrémentale afin de ne pas dépasser la limite. Si vous avez toujours besoin de meilleures performances, envisagez d'acheter un quota de débit provisionné supplémentaire.

Vous pouvez vérifier si une requête a été rétrogradée à partir de la réponse. Pour les requêtes rétrogradées au paiement à l'usage standard, le type de trafic est défini sur ON_DEMAND. Pour en savoir plus, consultez la section Vérifier l'utilisation du paiement à l'usage prioritaire.

Étape suivante