Wie man die Gemini 4 Hydrogen API verwendet

Die Gemini 4 Hydrogen API verwendet die Modell-ID gemini-4-hydrogen. Sie rufen sie mit einem POST an https://generativelanguage.googleapis.com/v1beta/interactions auf, mit Ihrem Schlüssel im Header x-goog-api-key sowie model und input im JSON-Body. Sie läuft im Free Tier und im Paid Tier (1,50 $ für Input, 7,50 $ für Output pro 1M Token) und nutzt standardmäßig die Thinking-Stufe high.

Diese Anleitung führt Sie durch den gesamten Weg: Schlüssel, erste Anfrage, Thinking-Stufe, ein PDF, Function Calling, Streaming und Fehlerbehandlung. Jeder Feldname stammt aus der Google-Dokumentation.

Was benötigen Sie, bevor Sie Ihren ersten Gemini 4 Hydrogen API-Aufruf starten?

Sie benötigen einen Gemini-API-Schlüssel, die Modell-ID gemini-4-hydrogen und den Interactions-Endpunkt. Google hat Hydrogen am 12. November 2026 als schnelles Gemini-4-Modell neben Carbon und Argon veröffentlicht (was Gemini 4 Hydrogen ist).

Die Google-Dokumentation bezeichnet generateContent als Legacy, daher verwenden diese Beispiele Interactions.

Wie erhalten Sie einen Gemini-API-Schlüssel für Hydrogen?

Hydrogen ist im Free Tier verfügbar, Sie können also ohne Abrechnung starten:

1. Öffnen Sie die Seite API keys in Google AI Studio.
2. Klicken Sie auf Create API key. Neue Schlüssel, die in AI Studio erstellt werden, sind Autorisierungsschlüssel, die an ein Servicekonto gebunden sind.
3. Exportieren Sie ihn: export GEMINI_API_KEY="YOUR_API_KEY". Die SDKs lesen GEMINI_API_KEY oder GOOGLE_API_KEY; wenn beide gesetzt sind, hat GOOGLE_API_KEY Vorrang.
4. Ein außerhalb von AI Studio erstelltes Cloud-Projekt benötigt möglicherweise eine Projektverifizierung, bevor der Free Tier funktioniert.

Google veröffentlicht die Free-Tier-Werte auf seiner Seite zu Rate Limits, nicht im Launch-Guide. Unser Gemini 4 Hydrogen Free Guide zeigt, was Sie für 0 $ bekommen.

Wie senden Sie Ihre erste Gemini 4 Hydrogen API-Anfrage?

Senden Sie model und input an den Interactions-Endpunkt. Speichern Sie das Modell in einer Variablen, damit der Modellwechsel nur eine Zeile ändert.

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."
  }'

Derselbe Aufruf mit dem Python SDK (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)

Die Antwort enthält eine id, einen status und ein steps-Array. Der Text befindet sich in model_output-Steps, das Reasoning in thought-Steps, und output_text des SDKs verknüpft den Text für Sie. Das usage-Objekt enthält total_input_tokens, total_thought_tokens, total_output_tokens und total_tokens.

Diese Snippets folgen dem Google-Quickstart. Wir haben sie für diesen Beitrag nicht ausgeführt (kein Gemini-Schlüssel auf unserem Testsystem), also prüfen Sie die Struktur anhand Ihrer eigenen ersten Antwort.

Wie stellen Sie die Gemini 4 Hydrogen Thinking-Stufe ein?

Setzen Sie thinking_level innerhalb von generation_config. Hydrogen nutzt standardmäßig high, führt die neue Stufe xhigh ein und lehnt minimal mit einem Fehler ab.

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
    }
  }'

Zwei Regeln sind wichtig. max_output_tokens begrenzt Thinking und Output zusammen, daher kann ein altes niedriges Limit (etwa 8.192) Antworten abschneiden; Google empfiehlt, es auf 65.536 zu erhöhen und stattdessen die Thinking-Stufe zu senken. Und Thinking-Token werden mit dem Output-Satz von 7,50 $ abgerechnet, sodass xhigh teurer ist, selbst wenn die sichtbare Antwort gleich lang bleibt. Die Preisübersicht für Gemini 4 Hydrogen rechnet die Kosten pro Stufe durch.

Google sagt außerdem, dass der Server bei Hydrogen temperature, top_p und top_k ignoriert, also lassen Sie diese Parameter aus Ihren Anfragen weg.

Wie senden Sie ein PDF an Gemini 4 Hydrogen?

Fügen Sie dem input-Array ein document-Element hinzu, neben einem text-Element mit Ihrer Anweisung. Bei kleinen Dateien senden Sie das PDF inline als 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."}
    ]
  }'

Für größere Dateien oder die Wiederverwendung über mehrere Runden laden Sie die Datei einmal über die Files API hoch (kostenlos, 48 Stunden gespeichert) und übergeben stattdessen {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"}. Laut dem Leitfaden zur Dokumentenverarbeitung können PDFs bis zu 50 MB oder 1.000 Seiten umfassen, und das Modell liest die Diagramme, Tabellen und Bilder darin, nicht nur den Text.

Wie funktioniert Function Calling mit Gemini 4 Hydrogen?

Deklarieren Sie Ihre Funktion in tools. Das Modell führt nichts aus; es gibt einen function_call-Step zurück, Ihr Code führt die Funktion aus, und Sie senden ein function_result zurück. Hier ist Schritt eins, aus dem Function-Calling-Guide von 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"]
      }
    }]
  }'

Suchen Sie den Step, bei dem type gleich function_call ist, und lesen Sie dessen name, arguments und id. Führen Sie Ihre Funktion aus und senden Sie dann das Ergebnis in derselben Sitzung zurück:

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 hält den Konversations- und Thought-Zustand auf Googles Seite, sodass Sie den Verlauf nicht erneut senden müssen. Ein Hinweis aus Googles Migrationshinweisen: Wenn Sie das Modell auffordern, rohe JSON-„Tool Calls“ auszugeben, ohne dass Tools deklariert sind, kann dies MALFORMED_FUNCTION_CALL zurückgeben. Deklarieren Sie Tools nativ oder verwenden Sie strukturierte Outputs.

Wie streamen Sie Gemini 4 Hydrogen-Antworten?

Fügen Sie "stream": true zum Body hinzu. Die API antwortet mit 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
  }'

Laut Googles Streaming-Guide erhalten Sie interaction.created, dann step.start, step.delta und step.stop für jeden Step (thought, dann model_output), dann interaction.completed mit dem finalen usage. Hängen Sie delta.text aus model_output-Steps an, um die Antwort aufzubauen. Streaming erhöht das Limit nicht: Jeder Durchlauf stoppt weiterhin bei 65.536 Token. Für längeren Output setzen Sie "background": true mit einem max_output_tokens-Wert über 65.536 und pollen Sie GET /v1beta/interactions/{id}, bis status nicht mehr in_progress oder queued ist.

Wie behandeln Sie Fehler der Gemini 4 Hydrogen API?

Nicht-Streaming-Fehler kommen als HTTP-Status plus ein error-Objekt mit code und message zurück. In einem Stream erhalten Sie ein error-Event mit denselben Feldern. Die häufigsten Codes, aus Googles Seite zu API-Fehlern:

Googles Troubleshooting-Guide empfiehlt, nur 429, 408 und 5xx zu wiederholen – mit exponentiellem Backoff plus Jitter und einem Retry-Limit – und niemals 400, 402 oder 403. Das Python SDK wiederholt vorübergehende Fehler bereits bis zu viermal automatisch.

Lassen Sie Ihren Coding-Agenten die Hydrogen API mit Apidog CLI testen

Statt nach jedem Prompt oder jeder Änderung der Thinking-Stufe JSON zu lesen, lassen Sie Ihren Coding-Agenten (Claude Code, Codex, Cursor) einen wiederholbaren Test erstellen und mit Apidog CLI ausführen.

Richten Sie es einmalig ein:

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

Geben Sie Ihrem Agenten dann einen einzigen 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.

Der Agent prüft jede Payload gegen die Schemas der CLI, bevor er etwas schreibt:

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

Die beiden Läufe vergleichen die Thought-Token für denselben Prompt – die Zahl, die Ihre Rechnung bewegt. Ersetzen Sie -r cli,json durch -r junit, und derselbe Lauf läuft in die CI; der Apidog CLI CI/CD-Guide zeigt die Pipeline, und Apidog CLI in Claude Code behandelt die Einrichtung des Agenten. Apidogs Free Plan deckt bis zu 4 Nutzer ab.

FAQ

Was ist die Modell-ID von Gemini 4 Hydrogen? gemini-4-hydrogen. Sie funktioniert mit der Interactions API und generateContent.

Ist die Gemini 4 Hydrogen API kostenlos? Ja, innerhalb der Grenzen. Google listet Hydrogen im Free Tier der Gemini API und in AI Studio, mit Rate Limits. Die kostenpflichtige Nutzung kostet 1,50 $ pro 1M Input-Token und 7,50 $ pro 1M Output-Token.

Wie migriere ich von Gemini 3.8 Flash? Ändern Sie die Modell-Zeichenkette, erhöhen Sie niedrige max_output_tokens-Limits, entfernen Sie temperature, top_p, top_k und explizites Caching (cachedContents), und ersetzen Sie die Thinking-Stufe minimal durch low oder medium.

Unterstützt Hydrogen Context Caching? Nur implizites Caching. Es läuft standardmäßig bei Prompts mit mindestens 4.096 Token und gewährt 95 % Rabatt auf Cache-Treffer. Explizites Caching wird nicht unterstützt.

Wie unterscheidet sich Hydrogen in der API von Gemini 4 Argon? Gleiches Anfrage-Schema. Hydrogen nutzt standardmäßig high und führt xhigh ein, während Argon standardmäßig medium nutzt. Sehen Sie sich den Gemini 4 Argon API-Guide, den Gemini 4 Carbon API-Guide und Gemini 4 Hydrogen Orchestrator für Modell-Kombinationen an.