TL;DR
L’API Gemini 4 Hydrogen est disponible via l’API Gemini de Google et des passerelles tierces prises en charge comme CometAPI. Choisissez d’abord la voie d’accès : utilisez Google pour les fonctionnalités spécifiques au fournisseur et la gestion du compte, ou CometAPI si vous souhaitez une passerelle de modèles unifiée ou un client compatible OpenAI. Commencez par une petite requête texte, puis ajoutez le streaming, l’historique de conversation, les fichiers et les outils.
Vous avez besoin de Python 3.10 ou version ultérieure, d’une clé pour la voie sélectionnée et de l’accès à gemini-4-hydrogen. L’exemple JavaScript facultatif utilise Node.js 22 ou version ultérieure. Conservez les informations d’identification dans l’environnement serveur tout au long du tutoriel.
Points clés
- Utilisez
gemini-4-hydrogencomme ID de modèle pour l’API Gemini 4 Hydrogen. - Google et CometAPI utilisent des identifiants et une facturation distincts. Associez la clé à l’endpoint que vous sélectionnez.
- Commencez avec l’API native GenerateContent ; utilisez l’interface compatible OpenAI de CometAPI lorsqu’elle convient à un client de chat existant.
- Conservez la réponse complète du modèle dans l’historique multi‑tours, y compris les signatures, avant de renvoyer une réponse de suivi ou le résultat d’un outil.
- Comparez l’usage réel des jetons et les tâches terminées pour choisir la voie d’accès ; l’exemple standard de calcul de coût par jeton figure dans la section Tarification.
Qu’est‑ce que l’API Gemini 4 Hydrogen ?
Google a présenté Hydrogen le 12 novembre 2026. L’API accepte des invites et des fichiers pris en charge, puis renvoie du texte généré ou des appels de fonction structurés à traiter par votre application. Vous n’avez pas besoin d’héberger le modèle vous‑même.
Commencez par une requête uniquement texte et vérifiez le texte renvoyé, la raison d’arrêt et l’usage des jetons avant d’ajouter des outils ou des fichiers. Une fois que cela fonctionne, ajoutez un état de conversation ou un outil métier en lecture seule, plutôt que de construire tout le flux de travail d’un coup.
Spécifications de l’API Gemini 4 Hydrogen
| Spécification | Capacité du modèle documentée par Google |
|---|---|
| ID du modèle | gemini-4-hydrogen |
| Entrée | Texte, images, audio, vidéo et documents pris en charge |
| Sortie | Texte, avec des segments d’appel de fonction structurés lorsque des outils sont utilisés |
| Budget de contexte unifié | 1,048,576 jetons pour l’ensemble entrée et sortie |
| Segment de sortie au premier plan unique | Jusqu’à 65,536 jetons, y compris le raisonnement et les appels de fonction |
| Fonctionnalités applicatives | Contrôle du niveau de raisonnement, sortie structurée et appels de fonction |
Il s’agit des capacités du modèle ; cela ne garantit pas que chaque passerelle expose toutes les fonctionnalités du fournisseur. Les exemples ci‑dessous utilisent des champs de requête standard et de courtes générations au premier plan.
API officielle Google vs CometAPI
Les deux voies d’accès prennent en charge les requêtes Gemini, mais elles utilisent des endpoints, des identifiants et des systèmes de facturation différents. Utilisez Google pour les fonctionnalités spécifiques au fournisseur ; utilisez CometAPI pour une passerelle unifiée ou un client compatible existant.
| Choix | API Google Gemini Developer | Intégration CometAPI de Gemini |
|---|---|---|
| Hôte API natif | generativelanguage.googleapis.com | api.cometapi.com |
| Clé API dans ce guide | GEMINI_API_KEY | COMETAPI_KEY |
| Compte et facturation | Gérés par Google | Gérés par CometAPI |
| Meilleur point de départ | Fonctionnalités spécifiques à Google et contrôles de compte | Accès unifié aux modèles ou client compatible OpenAI existant |
Gardez le même prompt et le même budget de sortie lors de la comparaison des deux voies d’accès afin que les résultats soient comparables. Les alternatives JavaScript et compatibles OpenAI restent explicitement configurées pour CometAPI.
Comment utiliser l’API Gemini 4 Hydrogen étape par étape ?
Étape 1 : Créer une clé API
Pour CometAPI, créez un compte et générez une clé dans la console des jetons API. Pour un accès direct à Google, créez une clé d’API Gemini dans Google AI Studio. Confirmez l’accès au modèle et la facturation ou le quota disponible du compte sélectionné.
Stockez la clé en toute sécurité. Une clé CometAPI ne peut pas authentifier une requête vers l’endpoint de Google, et une clé Google ne peut pas authentifier une requête CometAPI.
Définissez la clé pour la voie d’accès choisie dans Bash ; vous n’avez besoin que d’une seule de ces affectations.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Définissez la clé correspondante dans PowerShell sous Windows.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
Étape 2 : Envoyer une première requête avec cURL
Envoyez une requête texte native via CometAPI depuis un terminal Bash.
curl "https://api.cometapi.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Sinon, envoyez la même requête native directement à Google avec une clé d’API Google.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
Une fois la requête réussie, vérifiez trois champs : candidates[0].content.parts pour le texte visible, finishReason pour le statut de complétion et usageMetadata pour l’usage des jetons. Corrigez les erreurs d’authentification ou de requête avant d’ajouter davantage de code applicatif.
Étape 3 : Configurer le client Python et envoyer une requête
Installez les packages utilisés par les exemples Python.
python -m pip install requests openai
Enregistrez cet utilitaire sous hydrogen_client.py. Laissez PROVIDER à cometapi pour CometAPI, ou définissez‑le sur google pour un accès direct à l’API Gemini Developer. Les exemples natifs suivants importent ce fichier, ce qui permet de conserver la voie d’accès sélectionnée.
Configurez l’endpoint choisi et définissez des utilitaires réutilisables pour la requête et l’extraction du texte.
import os
import requests
MODEL = "gemini-4-hydrogen"
PROVIDER = "cometapi" # Change to "google" for direct access.
ROUTES = {
"cometapi": ("https://api.cometapi.com", "COMETAPI_KEY"),
"google": ("https://generativelanguage.googleapis.com", "GEMINI_API_KEY"),
}
BASE_URL, KEY_NAME = ROUTES[PROVIDER]
API_KEY = os.environ[KEY_NAME]
URL = f"{BASE_URL}/v1beta/models/{MODEL}:generateContent"
def generate(payload):
response = requests.post(
URL,
headers={"x-goog-api-key": API_KEY},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
def visible_text(data):
candidates = data.get("candidates") or []
if not candidates:
raise ValueError("No candidate returned; inspect promptFeedback.")
candidate = candidates[0]
parts = candidate.get("content", {}).get("parts", [])
text = "".join(
part.get("text", "") for part in parts
if not part.get("thought", False)
)
if not text:
raise ValueError(
f"No visible text; inspect parts and finishReason: "
f"{candidate.get('finishReason')}"
)
return text
Enregistrez ce qui suit sous hydrogen.py à côté de l’utilitaire. Il affiche la réponse, la raison d’arrêt et l’usage, afin de distinguer une réponse complète d’une sortie interrompue par une limite de jetons.
Envoyez une requête texte en utilisant le fournisseur configuré.
from hydrogen_client import generate, visible_text
data = generate({
"contents": [{"role": "user", "parts": [{
"text": "Explain API rate limiting in three sentences."
}]}],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
},
})
print(visible_text(data))
candidate = data["candidates"][0]
print("Finish reason:", candidate.get("finishReason"))
print("Usage:", data.get("usageMetadata", {}))
Exécutez le script dans le terminal où vous avez défini la clé API choisie.
python hydrogen.py
Lisez la réponse, puis vérifiez finishReason pour savoir pourquoi la génération s’est arrêtée. Dans usageMetadata, vérifiez le nombre de jetons utilisés par la requête. MAX_TOKENS signifie que la réponse peut être incomplète, même si la requête HTTP a abouti.
Utiliser JavaScript ou un client compatible OpenAI
Choisissez l’exemple qui correspond à votre application. L’exemple Node.js envoie une requête Gemini native. Si vous utilisez déjà le SDK OpenAI, passez à l’exemple Python ci‑dessous.
JavaScript avec Node.js
Enregistrez ce qui suit sous hydrogen.js et exécutez node hydrogen.js. Il envoie la même forme de requête native et extrait toutes les parties de texte visibles.
Envoyez une requête native GenerateContent depuis Node.js.
const apiKey = process.env.COMETAPI_KEY;
if (!apiKey) throw new Error("Set COMETAPI_KEY before running this script.");
const baseUrl = "https://api.cometapi.com";
const model = "gemini-4-hydrogen";
async function main() {
const response = await fetch(
`${baseUrl}/v1beta/models/${model}:generateContent`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-goog-api-key": apiKey
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [
{
text: "Explain how an AI coding agent works."
}
]
}
],
generationConfig: {
maxOutputTokens: 4096,
thinkingConfig: {
thinkingLevel: "MEDIUM"
}
}
})
}
);
if (!response.ok) {
throw new Error(
`API error: ${response.status} ${await response.text()}`
);
}
const data = await response.json();
const candidate = data.candidates?.[0];
const text = (candidate?.content?.parts || [])
.filter(part => !part.thought)
.map(part => part.text || "")
.join("");
if (!text) {
throw new Error(`No visible text; finishReason=${candidate?.finishReason}`);
}
console.log(text);
}
main().catch(console.error);
Python avec le SDK OpenAI
Si votre application utilise déjà le SDK OpenAI, CometAPI expose également POST /v1/chat/completions. La migration la plus simple consiste à modifier la clé API, l’URL de base et l’ID du modèle. Utilisez cette voie pour les workflows de chat courants ; utilisez l’endpoint natif Gemini lorsque vous avez besoin de champs spécifiques à Gemini.
Créez une requête Chat Completions via CometAPI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
response = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": "Explain how an AI coding agent works."
}
]
)
print(response.choices[0].message.content)
Les exemples natifs utilisent contents et generationConfig ; Chat Completions utilise messages et ses propres champs de requête. Conservez chaque requête dans un format unique plutôt que de copier des champs natifs dans un appel SDK qui ne les accepte pas.
Fonctionnalités avancées de l’API Gemini 4 Hydrogen
Les exemples suivants réutilisent hydrogen_client.py de la section de configuration, afin de fonctionner avec le fournisseur sélectionné dans PROVIDER. L’exemple de streaming ci‑dessous utilise le client CometAPI Chat Completions séparé, qui convient à une application compatible OpenAI existante.
Configurer le raisonnement et la sortie structurée
Utilisez generationConfig pour définir thinkingConfig.thinkingLevel sur LOW, MEDIUM, HIGH ou XHIGH. Choisissez un budget de sortie qui laisse de la place pour le raisonnement et la réponse visible. Lorsque l’application attend du JSON, utilisez responseMimeType et responseSchema plutôt que de vous fier uniquement à une demande de formatage en langage naturel.
Définissez le budget de sortie et le niveau de raisonnement pour une requête native.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Diffuser les réponses via CometAPI
Le streaming renvoie le contenu généré de manière incrémentale au lieu d’attendre la réponse complète. C’est utile pour les interfaces de chat, les assistants de code et les applications où la latence perçue est importante.
CometAPI documente la diffusion de Chat Completions avec stream=true. L’exemple Python gère les fragments sans choices, qui peuvent survenir dans les réponses en streaming.
Affichez le texte dès son arrivée via l’endpoint compatible OpenAI.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
stream = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": (
"Write a Python function that validates an email "
"address and explain the main checks."
)
}
],
stream=True
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta and delta.content:
print(delta.content, end="", flush=True)
print()
Pour un client natif, CometAPI documente streamGenerateContent avec Server-Sent Events. Cette voie renvoie des objets de réponse GenerateContent plutôt que des deltas Chat Completions. Faites correspondre l’analyseur à la voie ; le comportement de streaming peut varier entre l’endpoint Gemini natif et une passerelle compatible OpenAI. Testez la voie Hydrogen exacte utilisée par votre application avant de migrer un client de streaming existant.
Préserver l’historique de conversation multi‑tours
Envoyez les tours précédents de l’utilisateur et du modèle avec la requête suivante. Conservez l’objet de contenu complet du modèle au lieu de le reconstruire à partir du texte visible ; cela préserve les métadonnées renvoyées pour le tour suivant. Enregistrez l’exemple sous hydrogen_history.py à côté de l’utilitaire partagé.
Effectuez deux requêtes liées en préservant l’intégralité de la première réponse du modèle.
from hydrogen_client import generate, visible_text
history = [{"role": "user", "parts": [{
"text": "Suggest a simple queue-based background job architecture."
}]}]
config = {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
}
first = generate({"contents": history, "generationConfig": config})
print(visible_text(first))
candidate = first["candidates"][0]
if candidate.get("finishReason") != "STOP":
raise RuntimeError("The first turn did not finish normally.")
history.append(candidate["content"])
history.append({"role": "user", "parts": [{
"text": "Now identify three failure scenarios in that design."
}]})
second = generate({"contents": history, "generationConfig": config})
print(visible_text(second))
print("Finish reason:", second["candidates"][0].get("finishReason"))
Exécutez python hydrogen_history.py. La seconde réponse doit se rapporter à la conception du premier tour. Conservez le préfixe de conversation inchangé dans cet exemple ; les applications longues nécessitent une politique séparée pour la compaction et les limites de contexte.
Envoyer des images et des PDF
Hydrogen prend en charge la compréhension d’images et de documents. Dans le format de requête natif Gemini, ajoutez une partie inlineData en plus de l’instruction texte. C’est utile pour l’analyse de captures d’écran, de schémas d’architecture, de formulaires scannés et l’extraction de rapports.
Enregistrez cet exemple sous analyze_file.py à côté de hydrogen_client.py. Il envoie une image locale ou un PDF, afin de réutiliser le même code pour les deux entrées. Utilisez un petit fichier pour la première requête ; Base64 augmente la taille de la requête.
Analysez un PNG, JPEG ou PDF local à l’aide du client natif partagé.
import base64
import sys
from pathlib import Path
from hydrogen_client import generate, visible_text
path = Path(sys.argv[1])
mime_types = {
".png": "image/png", ".jpg": "image/jpeg",
".jpeg": "image/jpeg", ".pdf": "application/pdf",
}
mime_type = mime_types.get(path.suffix.lower())
if mime_type is None:
raise ValueError("Choose a PNG, JPEG, or PDF file.")
data = generate({
"contents": [{"role": "user", "parts": [
{"text": "Summarize this file and identify the key findings."},
{"inlineData": {
"mimeType": mime_type,
"data": base64.b64encode(path.read_bytes()).decode("ascii"),
}},
]}],
"generationConfig": {"maxOutputTokens": 4096},
})
print(visible_text(data))
Exécutez l’exemple de fichier avec votre propre document ou image.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
Les octets du fichier doivent correspondre au type MIME déclaré. Renommer l’extension ne convertit pas le fichier. Si un téléchargement est rejeté, examinez l’erreur pour une limite de taille ou de format avant de réessayer ; ne supposez pas qu’une URI de fichier hébergée par Google est accessible via une passerelle tierce.
Connecter des outils contrôlés par l’application
L’appel de fonction permet au modèle de demander une opération que votre application effectue. Le modèle renvoie un appel de fonction structuré ; votre application valide les arguments, exécute la fonction et renvoie le résultat.
Cet exemple utilise une petite base de données de commandes fictive. Enregistrez‑le sous order_agent.py à côté du client partagé. Il implémente l’aller‑retour, limite la boucle à quatre requêtes et préserve le contenu complet du modèle — y compris toute signature renvoyée — entre les tours.
Exécutez une boucle d’appels de fonctions bornée contre une base de démonstration locale.
from hydrogen_client import generate, visible_text
orders = {"DEMO-1001": {"status": "shipped", "carrier": "Example Carrier"}}
tools = [{"functionDeclarations": [{
"name": "lookup_order",
"description": "Retrieve a demonstration order by its order ID.",
"parameters": {
"type": "OBJECT",
"properties": {"order_id": {"type": "STRING"}},
"required": ["order_id"],
},
}]}]
history = [{"role": "user", "parts": [{
"text": "Use lookup_order to check the status of DEMO-1001."
}]}]
for _ in range(4):
data = generate({
"contents": history,
"tools": tools,
"generationConfig": {"maxOutputTokens": 4096},
})
candidates = data.get("candidates") or []
if not candidates or not candidates[0].get("content"):
raise RuntimeError("No model content returned.")
model_content = candidates[0]["content"]
calls = [
part["functionCall"] for part in model_content.get("parts", [])
if "functionCall" in part
]
if not calls:
print(visible_text(data))
break
history.append(model_content) # Preserve all parts and signatures.
results = []
for call in calls:
args = call.get("args", {})
order_id = args.get("order_id") if isinstance(args, dict) else None
if call.get("name") != "lookup_order":
raise ValueError("Unexpected function name.")
if not isinstance(order_id, str) or not order_id:
raise ValueError("order_id must be a non-empty string.")
result = orders.get(order_id, {"error": "Order not found"})
reply = {"name": call["name"], "response": result}
if "id" in call:
reply["id"] = call["id"]
results.append({"functionResponse": reply})
history.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool-call limit reached before a final answer.")
Exécutez python order_agent.py. La réponse finale doit refléter l’enregistrement local pour DEMO-1001. Dans un service réel, autorisez l’utilisateur avant d’accéder à une commande ; le choix d’un ID de commande par le modèle ne constitue pas une preuve d’autorisation.
Combien coûte l’API Gemini 4 Hydrogen ?
Les tarifs ci‑dessous sont en USD par million de jetons, vérifiés le 17 novembre 2026. Ils comparent l’entrée et la sortie standard non mises en cache, et non le batch, la priorité, l’entrée mise en cache ou l’usage des outils facturé séparément.
| Type de jeton | Tarif standard mondial Google | API Gemini 4 Hydrogen dans CometAPI |
|---|---|---|
| Jetons d’entrée / 1M | $1.50 | $1.20 |
| Jetons de sortie / 1M | $7.50 | $6.00 |
Pour 100,000 jetons d’entrée et 10,000 jetons de sortie facturables, l’estimation CometAPI est 0.1 × $1.20 + 0.01 × $6.00 = $0.18. Les mêmes volumes aux tarifs standards listés par Google coûtent $0.225, soit une différence de 20 %. Incluez les jetons de raisonnement dans l’usage de sortie et vérifiez l’usage facturé de votre compte lors de l’estimation d’un flux de travail réel.
Comment migrer vers l’API Gemini 4 Hydrogen ?
Qu’est‑ce qui change lors d’une migration depuis Gemini 3.8 Flash ?
Avant de changer l’ID du modèle, vérifiez le paramètre de raisonnement, le budget de contexte et l’historique de conversation que votre client envoie avec chaque requête.
| Détail d’intégration | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| Niveau de raisonnement par défaut | MEDIUM | HIGH |
| Comptabilisation du contexte | Limites d’entrée et de sortie séparées | Un budget d’entrée/sortie partagé |
| État multi‑tours | Examiner la gestion de l’historique du client existant | Préserver l’intégralité des parties et des signatures du modèle ; les modifications de préfixe nécessitent un traitement spécifique |
Les changements de migration documentés comptent surtout lorsque votre application s’appuie sur des valeurs par défaut, compacte l’historique ou exécute plusieurs tours d’outils. Définissez explicitement le raisonnement et testez un court flux de travail existant avant de changer le modèle en production.
Mettre à jour une intégration existante
Créez une configuration de test avec le nouvel ID de modèle en conservant sa clé et son endpoint ensemble. Exécutez le même flux de travail représentatif avec les deux configurations afin de comparer leur comportement.
- Envoyez une nouvelle requête texte et vérifiez sa raison d’arrêt et l’usage des jetons.
- Rejouez une tâche multi‑tours et un aller‑retour d’outil en utilisant des objets de réponse de modèle complets.
- Supprimez les contrôles incompatibles listés dans la section des limitations avant de comparer les résultats des requêtes.
- Testez votre chemin de retour arrière (rollback) dans une conversation neuve ; ne supposez pas qu’un autre modèle accepte l’état de raisonnement enregistré par Hydrogen.
Décider si la migration améliore votre charge de travail
Adoptez la nouvelle configuration lorsqu’elle satisfait les objectifs de qualité et de latence à un coût acceptable par tâche terminée. Si le client actuel répond déjà à ces objectifs, utilisez un pilote limité pour démontrer un bénéfice avant de migrer toutes les requêtes. Gardez les invites, les entrées et les critères d’évaluation cohérents pendant l’évaluation.
Limitations de l’API Gemini 4 Hydrogen
Le guide développeur Hydrogen décrit des restrictions qui affectent les clients existants. Traitez‑les lors de la construction de la requête plutôt que de relancer le même payload rejeté.
- Champs non pris en charge : retirer thinkingBudget, thinkingLevel défini sur MINIMAL, frequencyPenalty, presencePenalty, et candidateCount supérieur à un.
- Paramètres d’échantillonnage ignorés : des valeurs personnalisées de temperature, topP et topK ne contrôlent pas la sortie d’Hydrogen.
- Mise en cache : cachedContent explicite non pris en charge. Des préfixes d’invite stables peuvent utiliser une mise en cache implicite, mais cela n’établit pas de remise de cache spécifique à une passerelle.
- Longues sorties : le client d’exemple de ce guide n’implémente qu’une requête synchrone. Il ne couvre pas le décodage long en arrière‑plan ni les workflows de continuation spécifiques au fournisseur.
- Modifications de conversation : modifier des invites antérieures ou des définitions d’outils peut invalider l’état de raisonnement. Préservez le préfixe, ou implémentez le comportement de gestion des préfixes documenté pour la voie d’accès sélectionnée.
Vérifications courantes de configuration
| Symptôme | Première vérification |
|---|---|
| 401 ou 403 | Confirmez que l’identifiant appartient à l’endpoint et a accès au modèle sélectionné. |
| 400 | Lisez le corps d’erreur ; inspectez les champs non pris en charge, le JSON mal formé et les métadonnées de conversation. |
| Aucun texte visible | Inspectez promptFeedback, les parties de la réponse et finishReason ; la réponse peut être bloquée, incomplète ou demander un outil. |
| MAX_TOKENS | Considérez le texte comme potentiellement incomplet et revoyez le budget de sortie avant de l’accepter. |
| Requête de fichier rejetée | Vérifiez le type MIME réel et la limite de payload de la voie sélectionnée. |
En cas d’échecs inattendus, enregistrez le modèle, la voie, le statut, l’horodatage et l’ID de requête lorsque disponible. Ne placez pas les clés API et le contenu de fichiers sensibles dans les journaux de routine.
FAQ
Comment gérer les erreurs de limitation de débit (rate limit) de l’API Gemini 4 Hydrogen ?
Pour les HTTP 429, réduisez la concurrence et réessayez avec un backoff exponentiel et du jitter, avec un nombre maximal de tentatives fixe. Conservez l’ID de requête lorsque la passerelle en fournit un. Ne réessayez pas des requêtes invalides ou des échecs d’authentification sans modification ; le guide des erreurs et des stratégies de retry de CometAPI les distingue des échecs transitoires. Un timeout peut survenir après le début du traitement, donc protégez toute action côté application contre une exécution en double.
Puis‑je appeler l’API Gemini 4 Hydrogen directement depuis une application web ?
Faites transiter les requêtes par votre propre backend. Une clé intégrée dans du JavaScript frontend peut être extraite par des visiteurs, même si le code est empaqueté ou minifié. Laissez le backend authentifier les utilisateurs, appliquer des limites d’usage et envoyer la requête au modèle. Pour le streaming, transférez la réponse incrémentale vers le navigateur sans exposer la clé API en amont.
Comment gérer un flux Gemini 4 Hydrogen interrompu ?
Considérez le texte reçu comme un résultat partiel jusqu’à la complétion de la réponse. Une nouvelle requête démarre une nouvelle génération ; elle ne reprend pas automatiquement le flux interrompu au même jeton. Conservez la sortie partielle séparée d’une réponse relancée, et n’exécutez pas d’actions à partir d’un JSON incomplet ou d’arguments d’outil inachevés. Proposez une action de réessai visible plutôt que de concaténer silencieusement deux générations.
Conclusion
Utilisez une tâche représentative comme premier test d’acceptation : la requête doit réussir, l’application doit extraire le résultat attendu, et l’usage de jetons enregistré doit correspondre à votre budget. Ajoutez une fonctionnalité à la fois et conservez ce test dans votre suite d’intégration. Un petit client observable est plus facile à étendre qu’un grand workflow dont les échecs sont difficiles à diagnostiquer.

