TL;DR
Gemini 4 Hydrogen API ist über Googles Gemini API und unterstützte Drittanbieter-Gateways wie CometAPI verfügbar. Wählen Sie zuerst den Weg: Nutzen Sie Google für anbieterspezifische Funktionen und Kontosteuerung oder CometAPI, wenn Sie ein einheitliches Modell-Gateway oder einen OpenAI-kompatiblen Client möchten. Beginnen Sie mit einer kleinen Textanfrage und fügen Sie anschließend Streaming, Verlauf, Dateien und Tools hinzu.
Sie benötigen Python 3.10 oder neuer, einen Schlüssel für den gewählten Weg und Zugriff auf gemini-4-hydrogen. Das optionale JavaScript-Beispiel nutzt Node.js 22 oder neuer. Bewahren Sie die Zugangsdaten in der Serverumgebung während des gesamten Tutorials auf.
Key Takeaways
- Verwenden Sie
gemini-4-hydrogenals Modell-ID für die Gemini 4 Hydrogen API. - Google und CometAPI haben separate Zugangsdaten und Abrechnung. Stimmen Sie den Schlüssel mit dem gewählten Endpunkt ab.
- Beginnen Sie mit nativem GenerateContent; nutzen Sie CometAPIs OpenAI-kompatible Schnittstelle, wenn sie zu einem bestehenden Chat-Client passt.
- Bewahren Sie die vollständige Modellantwort im mehrstufigen Verlauf auf, inklusive Signaturen, bevor Sie eine Folgeantwort oder ein Tool-Ergebnis zurückgeben.
- Vergleichen Sie tatsächliche Token-Nutzung und abgeschlossene Aufgaben bei der Routenwahl; das Standardbeispiel mit Tokenpreisen steht im Preisabschnitt.
What Is the Gemini 4 Hydrogen API?
Google stellte Hydrogen am 12. November 2026 vor. Die API akzeptiert Prompts und unterstützte Dateien und gibt dann generierten Text oder strukturierte Funktionsaufrufe zurück, die Ihre Anwendung verarbeitet. Sie müssen das Modell nicht selbst hosten.
Beginnen Sie mit einer reinen Textanfrage und prüfen Sie den zurückgegebenen Text, den Beendigungsgrund und die Token-Nutzung, bevor Sie Tools oder Dateien hinzufügen. Sobald dies funktioniert, fügen Sie Konversationszustand oder ein read-only Business-Tool hinzu, statt den gesamten Workflow auf einmal zu bauen.
Gemini 4 Hydrogen API specifications
| Specification | Google-documented model capability |
|---|---|
| Model ID | gemini-4-hydrogen |
| Input | Text, Bilder, Audio, Video und unterstützte Dokumente |
| Output | Text mit strukturierten Function-Call-Teilen bei Tool-Nutzung |
| Unified context budget | 1.048.576 Tokens über Eingabe und Ausgabe hinweg |
| Single foreground output segment | Bis zu 65.536 Tokens inkl. Reasoning und Function Calls |
| Application features | Kontrolle der Denkebene, strukturierte Ausgaben und Function Calling |
Dies sind Modellfähigkeiten, keine Garantie, dass jedes Gateway jedes Anbieterfeature bereitstellt. Die folgenden Beispiele nutzen Standardfelder der Anfragen sowie kurze Vordergrund-Generationen.
Google Official API vs CometAPI
Beide Wege unterstützen Gemini-Anfragen, nutzen jedoch unterschiedliche Endpunkte, Zugangsdaten und Abrechnung. Verwenden Sie Google für anbieterspezifische Features; verwenden Sie CometAPI für ein einheitliches Gateway oder einen vorhandenen kompatiblen Client.
| Decision | Google Gemini Developer API | CometAPI Gemini integration |
|---|---|---|
| Native API host | generativelanguage.googleapis.com | api.cometapi.com |
| API key in this guide | GEMINI_API_KEY | COMETAPI_KEY |
| Account and billing | Über Google verwaltet | Über CometAPI verwaltet |
| Best starting point | Google-spezifische Features und Kontosteuerung | Einheitlicher Modellzugang oder bestehender OpenAI-kompatibler Client |
Behalten Sie beim Vergleich der beiden Wege denselben Prompt und dasselbe Output-Budget bei, damit die Ergebnisse aussagekräftig sind. Die JavaScript- und OpenAI-kompatiblen Alternativen sind ausdrücklich für CometAPI konfiguriert.
How to Use Gemini 4 Hydrogen API Step by Step?
Step 1: Create an API key
Erstellen Sie für CometAPI ein Konto und generieren Sie einen Schlüssel in der API-Token-Konsole. Für direkten Google-Zugriff erstellen Sie in Google AI Studio einen Gemini-API-Schlüssel. Bestätigen Sie den Modellzugriff sowie Abrechnung bzw. verfügbares Kontingent des ausgewählten Kontos.
Speichern Sie den Schlüssel sicher. Ein CometAPI-Schlüssel kann eine Anfrage an Googles Endpunkt nicht authentifizieren und umgekehrt kann ein Google-Schlüssel keine CometAPI-Anfrage authentifizieren.
Setzen Sie den Schlüssel für den gewählten Weg in Bash; Sie benötigen nur eine dieser Zuweisungen.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Setzen Sie den entsprechenden Schlüssel in PowerShell unter Windows.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
Step 2: Send a first request with cURL
Senden Sie eine native Textanfrage über CometAPI aus einem Bash-Terminal.
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"
}
}
}'
Alternativ senden Sie dieselbe native Anfrage direkt an Google mit einem Google-API-Schlüssel.
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"
}
}
}'
Nachdem die Anfrage erfolgreich war, prüfen Sie drei Felder: candidates[0].content.parts für sichtbaren Text, finishReason für den Abschlussstatus und usageMetadata für die Token-Nutzung. Beheben Sie Authentifizierungs- oder Anfragefehler, bevor Sie weitere Anwendungscode hinzufügen.
Step 3: Configure the Python Client and Send a Request
Installieren Sie die Pakete, die von den Python-Beispielen verwendet werden.
python -m pip install requests openai
Speichern Sie diesen Helfer als hydrogen_client.py. Lassen Sie PROVIDER für CometAPI auf cometapi oder setzen Sie ihn auf google für direkten Zugriff auf die Gemini Developer API. Spätere native Beispiele importieren diese Datei und behalten so den gewählten Weg bei.
Konfigurieren Sie den ausgewählten Endpunkt und definieren Sie wiederverwendbare Request- und Text-Helfer.
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
Speichern Sie Folgendes als hydrogen.py neben dem Helfer. Es druckt die Antwort, den Beendigungsgrund und die Nutzung, damit Sie eine vollständige Antwort von einer am Tokenlimit angehaltenen Ausgabe unterscheiden können.
Senden Sie eine Textanfrage über den konfigurierten Anbieter.
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", {}))
Führen Sie das Skript in dem Terminal aus, in dem Sie den ausgewählten API-Schlüssel gesetzt haben.
python hydrogen.py
Lesen Sie die Antwort und prüfen Sie dann finishReason, um zu sehen, warum die Generierung beendet wurde. Prüfen Sie in usageMetadata, wie viele Tokens die Anfrage genutzt hat. MAX_TOKENS bedeutet, dass die Antwort unvollständig sein kann, auch wenn die HTTP-Anfrage erfolgreich war.
Use JavaScript or an OpenAI-Compatible Client
Wählen Sie das zu Ihrer Anwendung passende Beispiel. Das Node.js-Beispiel sendet eine native Gemini-Anfrage. Wenn Sie bereits das OpenAI-SDK nutzen, springen Sie zum Python-Beispiel unten.
JavaScript with Node.js
Speichern Sie Folgendes als hydrogen.js und führen Sie node hydrogen.js aus. Es sendet dieselbe native Request-Struktur und extrahiert alle sichtbaren Textteile.
Senden Sie eine native GenerateContent-Anfrage aus 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 with the OpenAI SDK
Wenn Ihre Anwendung bereits das OpenAI-SDK nutzt, stellt CometAPI auch POST /v1/chat/completions bereit. Die einfachste Migration besteht darin, API-Schlüssel, Basis-URL und Modell-ID zu ändern. Verwenden Sie diesen Weg für gängige Chat-Workflows; nutzen Sie den nativen Gemini-Endpunkt, wenn Sie anbieterspezifische Gemini-Felder benötigen.
Erstellen Sie eine Chat Completions-Anfrage über 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)
Die nativen Beispiele verwenden contents und generationConfig; Chat Completions verwendet messages und eigene Request-Felder. Halten Sie jede Anfrage in einem Format, statt native Felder in einen SDK-Aufruf zu kopieren, der sie nicht akzeptiert.
Advanced Gemini 4 Hydrogen API Features
Die folgenden Beispiele verwenden hydrogen_client.py aus dem Setup-Abschnitt erneut und funktionieren daher mit dem in PROVIDER gewählten Anbieter. Das folgende Streaming-Beispiel nutzt den separaten CometAPI-Chat-Completions-Client, der zu einer bestehenden OpenAI-kompatiblen Anwendung passt.
Configure reasoning and structured output
Verwenden Sie generationConfig, um thinkingConfig.thinkingLevel auf LOW, MEDIUM, HIGH oder XHIGH zu setzen. Wählen Sie ein Output-Budget, das Raum für sowohl Reasoning als auch die sichtbare Antwort lässt. Wenn die Anwendung JSON erwartet, verwenden Sie responseMimeType und responseSchema statt sich nur auf eine natürlichsprachliche Formatierungsanweisung zu verlassen.
Setzen Sie Output-Budget und Denkebene für eine native Anfrage.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
Stream responses through CometAPI
Streaming liefert generierte Inhalte schrittweise, statt auf die vollständige Antwort zu warten. Das ist nützlich für Chat-Oberflächen, Coding-Assistenten und Anwendungen, bei denen die wahrgenommene Latenz wichtig ist.
CometAPI dokumentiert Streaming von Chat Completions mit stream=true. Das Python-Beispiel verarbeitet Chunks ohne choices, die in Streaming-Antworten auftreten können.
Geben Sie Text aus, sobald er über den OpenAI-kompatiblen Endpunkt eintrifft.
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()
Für einen nativen Client dokumentiert CometAPI streamGenerateContent with Server-Sent Events. Dieser Weg liefert GenerateContent-Antwortobjekte statt Chat-Completions-Deltas. Halten Sie den Parser an die Route angepasst; Streaming-Verhalten kann zwischen dem nativen Gemini-Endpunkt und einem OpenAI-kompatiblen Gateway variieren. Testen Sie die genaue Hydrogen-Route Ihrer Anwendung, bevor Sie einen bestehenden Streaming-Client migrieren.
Preserve multi-turn conversation history
Senden Sie die vorherigen Nutzer- und Modell-Turns mit der nächsten Anfrage. Bewahren Sie das vollständige Inhaltsobjekt des Modells statt es aus sichtbarem Text neu zu erstellen; so bleibt zurückgegebene Metadaten für den nächsten Turn erhalten. Speichern Sie das Beispiel als hydrogen_history.py neben dem gemeinsamen Helfer.
Stellen Sie zwei zusammenhängende Anfragen und bewahren Sie dabei die erste Modellantwort vollständig.
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"))
Führen Sie python hydrogen_history.py aus. Die zweite Antwort sollte sich auf das Design aus dem ersten Turn beziehen. Belassen Sie das frühere Konversationspräfix in diesem Beispiel unverändert; langlebige Anwendungen benötigen eine separate Strategie für Kompaktierung und Kontextlimits.
Send images and PDFs
Hydrogen unterstützt Bild- und Dokumentenverständnis. Fügen Sie im nativen Gemini-Anfrageformat neben der Textinstruktion einen inlineData-Teil hinzu. Das ist nützlich für Screenshot-Analysen, Architekturdiagramme, gescannte Formulare und Berichtsextraktion.
Speichern Sie dieses Beispiel als analyze_file.py neben hydrogen_client.py. Es sendet eine lokale Bild- oder PDF-Datei, sodass Sie denselben Code für beide Eingaben wiederverwenden können. Verwenden Sie für die erste Anfrage eine kleine Datei; Base64 vergrößert die Anfragegröße.
Analysieren Sie ein lokales PNG, JPEG oder PDF mit dem gemeinsamen nativen Client.
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))
Führen Sie das Datei-Beispiel mit Ihrem eigenen Dokument oder Bild aus.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
Die Dateibytes müssen dem deklarierten MIME-Typ entsprechen. Eine umbenannte Dateiendung konvertiert die Datei nicht. Wenn ein Upload abgelehnt wird, untersuchen Sie die Fehlermeldung auf Größen- oder Formatlimits, bevor Sie es erneut versuchen; gehen Sie nicht davon aus, dass eine von Google gehostete Datei-URI über ein Drittanbieter-Gateway zugänglich ist.
Connect application-controlled tools
Function Calling ermöglicht es dem Modell, eine Operation anzufordern, die Ihre Anwendung ausführt. Das Modell gibt einen strukturierten Funktionsaufruf zurück; Ihre Anwendung validiert die Argumente, führt die Funktion aus und sendet das Ergebnis zurück.
Dieses Beispiel verwendet eine kleine, fiktive Bestelldatenbank. Speichern Sie es als order_agent.py neben dem gemeinsamen Client. Es implementiert die Rundreise, begrenzt die Schleife auf vier Anfragen und bewahrt den vollständigen Modellinhalt — einschließlich zurückgegebener Signaturen — zwischen den Turns auf.
Führen Sie eine begrenzte Function-Calling-Schleife gegen eine lokale Demonstrationsdatenbank aus.
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.")
Führen Sie python order_agent.py aus. Die endgültige Antwort sollte den lokalen Datensatz für DEMO-1001 widerspiegeln. Autorisieren Sie in einem realen Dienst den Nutzer, bevor Sie auf eine Bestellung zugreifen; die Wahl einer Bestell-ID durch das Modell ist kein Berechtigungsnachweis.
How Much Does Gemini 4 Hydrogen API Cost?
Die folgenden Preise sind USD pro Million Tokens, geprüft am 17. November 2026. Sie vergleichen Standard-Input und -Output ohne Cache, nicht Batch, Priorität, gecachten Input oder separat abgerechnete Tool-Nutzung.
| Token type | Google Global Standard | Gemini 4 Hydrogen API in CometAPI |
|---|---|---|
| Input tokens / 1M | $1.50 | $1.20 |
| Output tokens / 1M | $7.50 | $6.00 |
Für 100.000 Input-Tokens und 10.000 abrechenbare Output-Tokens beträgt die CometAPI-Schätzung 0.1 × $1.20 + 0.01 × $6.00 = $0.18. Dieselben Mengen kosten zu Googles gelisteten Standardtarifen $0.225, also 20% Unterschied. Berücksichtigen Sie Reasoning-Tokens im Output-Verbrauch und prüfen Sie die abgerechnete Nutzung Ihres Kontos bei der Schätzung eines realen Workflows.
How Do You Migrate to Gemini 4 Hydrogen API?
What Changes When Migrating from Gemini 3.8 Flash?
Prüfen Sie vor der Änderung der Modell-ID die Reasoning-Einstellung, das Kontextbudget und den Gesprächsverlauf, den Ihr Client mit jeder Anfrage sendet.
| Integration detail | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| Default thinking level | MEDIUM | HIGH |
| Context accounting | Separate Eingabe- und Ausgabelimits | Ein gemeinsames Eingabe-/Ausgabebudget |
| Multi-turn state | Vorhandenes Verlaufshandling prüfen | Vollständige Modellteile und Signaturen bewahren; Präfix-Änderungen erfordern Sonderbehandlung |
Die dokumentierten Migrationsänderungen sind besonders wichtig, wenn sich Ihre Anwendung auf Defaults stützt, Verlauf komprimiert oder mehrere Tool-Turns ausführt. Setzen Sie Reasoning explizit und testen Sie einen kurzen bestehenden Workflow, bevor Sie das Produktionsmodell ändern.
Update an existing integration
Erstellen Sie eine Testkonfiguration mit der neuen Modell-ID, wobei Schlüssel und Endpunkt zusammengehören. Führen Sie denselben repräsentativen Workflow mit beiden Konfigurationen aus, damit Sie ihr Verhalten vergleichen können.
- Senden Sie eine neue Textanfrage und prüfen Sie deren Beendigungsgrund und Token-Nutzung.
- Spielen Sie eine mehrstufige Aufgabe und eine Tool-Rundreise mit vollständigen Modellantwortobjekten nach.
- Entfernen Sie inkompatible Steuerungen aus dem Abschnitt „Einschränkungen“, bevor Sie Request-Ergebnisse vergleichen.
- Testen Sie Ihren Rollback-Pfad in einer frischen Konversation; nehmen Sie nicht an, dass ein anderes Modell Hydrogens gespeicherte Reasoning-Metadaten akzeptiert.
Decide whether the migration helps your workload
Übernehmen Sie die neue Konfiguration, wenn sie die Qualitäts- und Latenzziele der Aufgabe zu einem vertretbaren Preis pro abgeschlossener Aufgabe erfüllt. Wenn der aktuelle Client diese Ziele bereits erfüllt, nutzen Sie einen begrenzten Pilotbetrieb, um einen Vorteil zu belegen, bevor Sie jede Anfrage umstellen. Halten Sie Prompts, Eingaben und Bewertungskriterien während der Evaluierung konsistent.
Gemini 4 Hydrogen API Limitations
Der Hydrogen-Entwicklerleitfaden beschreibt Einschränkungen, die bestehende Clients betreffen. Beheben Sie sie bei der Request-Konstruktion statt dieselbe abgelehnte Payload erneut zu senden.
- Nicht unterstützte Felder: entfernen Sie thinkingBudget, thinkingLevel auf MINIMAL, frequencyPenalty, presencePenalty sowie candidateCount größer als eins.
- Ignorierte Sampling-Einstellungen: benutzerdefinierte temperature, topP und topK steuern Hydrogens Ausgabe nicht.
- Caching: explizites cachedContent wird nicht unterstützt. Stabile Prompt-Präfixe können implizites Caching nutzen, aber das begründet keinen gateway-spezifischen Cache-Rabatt.
- Lange Ausgabe: der Beispielclient in diesem Leitfaden implementiert nur eine synchrone Anfrage. Hintergrund-Langdecode oder anbieterspezifische Fortsetzungs-Workflows sind nicht abgedeckt.
- Gesprächsänderungen: das Ändern früherer Prompts oder Tool-Definitionen kann den Reasoning-Zustand ungültig machen. Bewahren Sie das Präfix oder implementieren Sie das dokumentierte Verhalten bei Präfix-Mismatch für den gewählten Weg.
Common setup checks
| Symptom | First check |
|---|---|
| 401 or 403 | Bestätigen Sie, dass die Zugangsdaten zum Endpunkt gehören und Zugriff auf das gewählte Modell haben. |
| 400 | Lesen Sie den Fehlertext; prüfen Sie nicht unterstützte Felder, fehlerhaftes JSON und Gesprächsmetadaten. |
| No visible text | Untersuchen Sie promptFeedback, Teile der Kandidaten und finishReason; die Antwort könnte blockiert, unvollständig sein oder ein Tool anfordern. |
| MAX_TOKENS | Behandeln Sie den Text als potenziell unvollständig und prüfen Sie das Output-Budget, bevor Sie ihn akzeptieren. |
| File request rejected | Überprüfen Sie den tatsächlichen MIME-Typ und das Payload-Limit des gewählten Wegs. |
Bei unerwarteten Fehlern protokollieren Sie Modell, Route, Status, Zeitstempel und Request-ID, sofern verfügbar. Halten Sie API-Schlüssel und sensible Dateiinhalte aus Routine-Logs heraus.
FAQ
How should I retry Gemini 4 Hydrogen API rate-limit errors?
Bei HTTP 429 reduzieren Sie die Parallelität und versuchen Sie es mit exponentiellem Backoff und Jitter erneut, mit einer festen maximalen Anzahl von Versuchen. Bewahren Sie die Request-ID auf, wenn das Gateway eine bereitstellt. Wiederholen Sie ungültige Anfragen oder Authentifizierungsfehler nicht unverändert; CometAPIs Leitfaden zu Fehlern und Retries unterscheidet diese von temporären Fehlern. Ein Timeout kann nach Start der Verarbeitung auftreten, daher sollten Sie jede anwendungsseitige Aktion vor doppelter Ausführung schützen.
Can I call Gemini 4 Hydrogen API directly from a web app?
Leiten Sie Anfragen über Ihr eigenes Backend. Ein im Frontend-JavaScript eingebetteter Schlüssel kann von Besuchern extrahiert werden, selbst wenn der Code gebündelt oder minimiert ist. Lassen Sie das Backend Nutzer authentifizieren, Nutzungsgrenzen anwenden und die Modellanfrage senden. Beim Streaming leiten Sie die inkrementelle Antwort an den Browser weiter, ohne den Upstream-API-Schlüssel offenzulegen.
How should I handle an interrupted Gemini 4 Hydrogen stream?
Behandeln Sie den empfangenen Text als Teilergebnis, bis die Antwort abgeschlossen ist. Eine neue Anfrage startet eine neue Generierung; sie setzt den abgebrochenen Stream nicht automatisch am selben Token fort. Halten Sie Teilausgaben getrennt von einer erneut angeforderten Antwort und führen Sie keine Aktionen aus unvollständigem JSON oder unvollständigen Tool-Argumenten aus. Bieten Sie eine sichtbare Retry-Aktion an, statt zwei Generierungen stillschweigend zu verketten.
Conclusion
Nutzen Sie eine repräsentative Aufgabe als erste Abnahmeprüfung: Die Anfrage sollte erfolgreich sein, die Anwendung sollte das gewünschte Ergebnis extrahieren und die protokollierte Token-Nutzung sollte in Ihr Budget passen. Fügen Sie jeweils nur eine Funktion hinzu und behalten Sie diese Prüfung in Ihrer Integrationssuite. Ein kleiner, gut beobachtbarer Client lässt sich einfacher erweitern als ein großer Workflow, dessen Fehler schwer nachzuverfolgen sind.

