Comment utiliser l'API Gemini 4 Hydrogen ?

L'API Gemini 4 Hydrogen utilise l'identifiant de modèle gemini-4-hydrogen. Vous l'appelez avec une requête POST vers https://generativelanguage.googleapis.com/v1beta/interactions, votre clé dans l'en-tête x-goog-api-key, et model plus input dans le corps JSON. Elle fonctionne sur le forfait gratuit et le forfait payant (1,50 $ en entrée, 7,50 $ en sortie par million de tokens) et utilise par défaut le niveau de réflexion high.

Ce guide parcourt tout le chemin : clé, première requête, niveau de réflexion, un PDF, le function calling, le streaming et la gestion des erreurs. Chaque nom de champ provient de la documentation de Google.

De quoi avez-vous besoin avant votre premier appel à l'API Gemini 4 Hydrogen ?

Vous avez besoin d'une clé d'API Gemini, de l'identifiant de modèle gemini-4-hydrogen et du point de terminaison Interactions. Google a lancé Hydrogen le 12 novembre 2026 comme modèle Gemini 4 rapide aux côtés de Carbon et Argon (ce qu'est Gemini 4 Hydrogen).

La documentation de Google qualifie generateContent d'héritée, c'est pourquoi ces exemples utilisent Interactions.

Comment obtenir une clé d'API Gemini pour Hydrogen ?

Hydrogen est disponible sur le forfait gratuit, vous pouvez donc commencer sans facturation :

1. Ouvrez la page des clés d'API dans Google AI Studio.
2. Cliquez sur Create API key. Les nouvelles clés créées dans AI Studio sont des clés d'autorisation, liées à un compte de service.
3. Exportez-la : export GEMINI_API_KEY="YOUR_API_KEY". Les SDK lisent GEMINI_API_KEY ou GOOGLE_API_KEY ; si les deux sont définis, GOOGLE_API_KEY a la priorité.
4. Un projet Cloud créé en dehors d'AI Studio peut nécessiter une vérification du projet avant que le forfait gratuit ne fonctionne.

Google publie les chiffres du forfait gratuit sur sa page des limites de débit, et non dans le guide de lancement. Notre guide sur Gemini 4 Hydrogen gratuit détaille ce que vous obtenez à 0 $.

Comment envoyer votre première requête à l'API Gemini 4 Hydrogen ?

Envoyez model et input au point de terminaison Interactions. Conservez le modèle dans une variable pour que changer de modèle ne nécessite qu'une seule ligne de modification.

export GEMINI_MODEL="gemini-4-hydrogen"

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "'"$GEMINI_MODEL"'",
    "input": "Write a Python function that retries an HTTP call with exponential backoff."
  }'

Le même appel avec le SDK Python (pip install -U google-genai) :

import os
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model=os.environ.get("GEMINI_MODEL", "gemini-4-hydrogen"),
    input="Write a Python function that retries an HTTP call with exponential backoff.",
)

print(interaction.output_text)
print(interaction.usage)

La réponse contient un id, un status et un tableau steps. Le texte se trouve dans les étapes model_output, le raisonnement dans les étapes thought, et le output_text du SDK concatène le texte pour vous. L'objet usage contient total_input_tokens, total_thought_tokens, total_output_tokens et total_tokens.

Ces extraits de code suivent le guide de démarrage rapide de Google. Nous ne les avons pas exécutés pour cet article (pas de clé Gemini sur notre machine de test), vérifiez donc leur structure par rapport à votre propre première réponse.

Comment définir le niveau de réflexion de Gemini 4 Hydrogen ?

Définissez thinking_level dans generation_config. Hydrogen utilise par défaut high, ajoute un nouveau niveau xhigh et rejette minimal avec une erreur.

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Audit this payment retry queue for race conditions.",
    "generation_config": {
      "thinking_level": "medium",
      "max_output_tokens": 65536
    }
  }'

Deux règles sont importantes. max_output_tokens plafonne la réflexion et la sortie ensemble, donc un ancien plafond bas (disons 8 192) peut tronquer les réponses ; Google recommande de le porter à 65 536 et de baisser le niveau de réflexion à la place. Et les tokens de réflexion sont facturés au tarif de sortie de 7,50 $, donc xhigh coûte plus cher même lorsque la réponse visible a la même longueur. L'analyse des tarifs de Gemini 4 Hydrogen calcule les chiffres par niveau.

Google indique également que le serveur ignore temperature, top_p et top_k sur Hydrogen, supprimez-les donc de vos requêtes.

Comment envoyer un PDF à Gemini 4 Hydrogen ?

Ajoutez un élément document au tableau input, à côté d'un élément text contenant votre instruction. Pour les petits fichiers, envoyez le PDF en ligne en base64 :

PDF_PATH="invoice.pdf"
B64=$(base64 < "$PDF_PATH" | tr -d '\n')

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": [
      {"type": "document", "data": "'"$B64"'", "mime_type": "application/pdf"},
      {"type": "text", "text": "Extract the line items as a table."}
    ]
  }'

Pour les fichiers plus volumineux ou une réutilisation sur plusieurs tours, téléchargez une fois avec l'API Files (gratuit, conservé 48 heures) et transmettez {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"} à la place. Selon le guide de traitement des documents, les PDF peuvent atteindre 50 Mo ou 1 000 pages, et le modèle lit les graphiques, tableaux et images qu'ils contiennent, et pas seulement le texte.

Comment fonctionne le function calling avec Gemini 4 Hydrogen ?

Déclarez votre fonction dans tools. Le modèle n'exécute rien ; il renvoie une étape function_call, votre code exécute la fonction, et vous renvoyez un function_result. Voici la première étape, tirée du guide du function calling de Google :

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "What'\''s the temperature in London?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }'

Repérez l'étape où type vaut function_call et lisez son name, ses arguments et son id. Exécutez votre fonction, puis renvoyez le résultat sur la même session :

fc = next(s for s in interaction.steps if s.type == "function_call")
result = get_current_temperature(**fc.arguments)

final = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[{
        "type": "function_result",
        "name": fc.name,
        "call_id": fc.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
    tools=[weather_function],
    previous_interaction_id=interaction.id,
)
print(final.output_text)

previous_interaction_id conserve l'état de la conversation et de la réflexion côté Google, vous n'avez donc pas à renvoyer l'historique. Un avertissement tiré des notes de migration de Google : inciter le modèle à afficher des « appels d'outils » en JSON brut sans outils déclarés peut renvoyer MALFORMED_FUNCTION_CALL. Déclarez les outils nativement ou utilisez les sorties structurées.

Comment diffuser en streaming les réponses de Gemini 4 Hydrogen ?

Ajoutez "stream": true au corps. L'API répond avec des Server-Sent Events :

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Explain idempotency keys in three short paragraphs.",
    "stream": true
  }'

Selon le guide du streaming de Google, vous recevez interaction.created, puis step.start, step.delta et step.stop pour chaque étape (thought, puis model_output), puis interaction.completed avec l'usage final. Concaténez delta.text des étapes model_output pour construire la réponse. Le streaming ne relève pas le plafond : chaque cycle s'arrête toujours à 65 536 tokens. Pour des sorties plus longues, définissez "background": true avec max_output_tokens supérieur à 65 536 et interrogez GET /v1beta/interactions/{id} jusqu'à ce que status quitte in_progress ou queued.

Comment gérer les erreurs de l'API Gemini 4 Hydrogen ?

Les erreurs hors streaming reviennent sous forme de statut HTTP plus un objet error avec code et message. En streaming, vous recevez un événement error avec les mêmes champs. Les codes que vous rencontrerez le plus souvent, tirés de la page des erreurs d'API de Google :

Le guide de dépannage de Google recommande de ne réessayer que les erreurs 429, 408 et 5xx, avec un backoff exponentiel plus un jitter et une limite de tentatives, et jamais les codes 400, 402 ou 403. Le SDK Python réessaie déjà les erreurs transitoires jusqu'à quatre fois.

Laissez votre agent de codage tester l'API Hydrogen avec Apidog CLI

Au lieu de lire du JSON après chaque changement de prompt ou de niveau de réflexion, laissez votre agent de codage (Claude Code, Codex, Cursor) construire un test répétable et l'exécuter avec Apidog CLI.

Configurez-le une seule fois :

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Puis donnez à votre agent un seul prompt :

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY and
THINKING (default "low"). Add an endpoint for POST /v1beta/interactions with the
x-goog-api-key header from GEMINI_API_KEY. Create a test case that sends model
"gemini-4-hydrogen", a short prompt and generation_config.thinking_level
{{THINKING}}, and asserts: HTTP 200, status is "completed", steps contains a
non-empty model_output, and usage.total_tokens exists. Run it at low and at high,
then compare usage.total_thought_tokens.

L'agent vérifie chaque charge utile par rapport aux schémas de la CLI avant d'écrire quoi que ce soit :

apidog environment create gemini --project <projectId> --base-url https://generativelanguage.googleapis.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "THINKING=low" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "THINKING=high" -r cli,json

Les deux exécutions comparent les tokens de réflexion pour le même prompt, la valeur qui influence votre facture. Remplacez -r cli,json par -r junit et la même exécution s'intègre dans votre CI ; le guide CI/CD d'Apidog CLI présente le pipeline et Apidog CLI dans Claude Code couvre la configuration de l'agent. Le forfait gratuit d'Apidog couvre jusqu'à 4 utilisateurs.

FAQ

Quel est l'identifiant de modèle de Gemini 4 Hydrogen ? gemini-4-hydrogen. Il fonctionne avec l'API Interactions et generateContent.

L'API Gemini 4 Hydrogen est-elle gratuite ? Oui, dans les limites prévues. Google liste Hydrogen sur le forfait gratuit de l'API Gemini et d'AI Studio, avec des limites de débit. L'utilisation payante coûte 1,50 $ par million de tokens en entrée et 7,50 $ par million de tokens en sortie.

Comment migrer depuis Gemini 3.8 Flash ? Changez la chaîne du modèle, relevez les plafonds bas de max_output_tokens, supprimez temperature, top_p, top_k et le cache explicite (cachedContents), et remplacez la réflexion minimal par low ou medium.

Hydrogen prend-il en charge le cache de contexte ? Uniquement le cache implicite. Il s'active par défaut sur les prompts d'au moins 4 096 tokens et accorde une remise de 95 % sur les accès au cache. Le cache explicite n'est pas pris en charge.

En quoi Hydrogen diffère-t-il de Gemini 4 Argon au niveau de l'API ? Même schéma de requête. Hydrogen utilise par défaut high et ajoute xhigh, tandis qu'Argon utilise par défaut medium. Consultez le guide de l'API Gemini 4 Argon, le guide de l'API Gemini 4 Carbon et Gemini 4 Hydrogen Orchestrator pour combiner les modèles.