Gemini 4 Hydrogen API mit Google oder Ofox einrichten

Für einen direkten Aufruf bei Google verwenden Sie gemini-4-hydrogen mit einem Google-API-Schlüssel. Über Ofox Chat Completions verwenden Sie google/gemini-4-hydrogen mit einem Ofox-Schlüssel. Endpunkt, Zugangsdaten und Antwortparser müssen zur gewählten Schnittstelle passen. Beim Protokollwechsel genügt es nicht, nur den Modellnamen zu ändern.

Google veröffentlichte Hydrogen für Entwickler am 12. November 2026. Während der API-Zugriff auf Carbon einen kostenpflichtigen Tarif voraussetzt, unterstützt Hydrogen Googles kostenlose und kostenpflichtige Stufen. Kostenloser Zugriff hängt trotzdem von der Berechtigung, Verifizierung und den aktiven Limits des Projekts ab. Dieser Leitfaden basiert auf der Dokumentation und dem Ofox-Katalog vom 13. November 2026. Er führt von der Auswahl der Schnittstelle bis zu einer gespeicherten und geprüften Textantwort.

Ofox veröffentlicht diesen Leitfaden. Wir haben die Anfrageformate geprüft und die Antwortprüfung mit synthetischen Testdaten getestet. Wir haben keine kostenpflichtige Hydrogen-Inferenz ausgeführt und weder Geschwindigkeit noch Antwortqualität gemessen. Die Beispiele sind ausführbare Anfragen, kein Nachweis eines bereits erfolgreichen Live-Tests mit Ihrem Konto. Bei der Modellwahl hilft der Vergleich von Carbon, Hydrogen und Argon. Die verlinkten Originaldokumente von Google sind auf Englisch.

Schnittstelle wählen, bevor Sie einen Schlüssel anlegen

Die folgenden Beispiele greifen über verschiedene Dienste auf dieselbe Modellfamilie zu. Führen Sie das Beispiel für Ihr Konto aus. Sie müssen nicht beide Varianten durchlaufen.

Google empfiehlt Interactions für neue Integrationen; GenerateContent wird weiterhin unterstützt. Der aktuelle öffentliche Ofox-Katalog führt Hydrogen mit OpenAI- und Gemini-Protokoll auf und nennt ausdrücklich /v1/chat/completions für OpenAI. Diesen dokumentierten Weg verwendet der Artikel. Daraus folgt nicht, dass Googles Interactions-Beispiel nach einem Austausch der Basis-URL über Ofox funktioniert.

Ofox dokumentiert außerdem eine Gemini-native Schnittstelle. Dafür gilt ein anderes Anfrageformat. Eine allgemeine Protokolldokumentation bedeutet nicht, dass jedes Gemini-Modell alle genannten Funktionen, etwa explizites Caching, unterstützt. Wählen Sie das Protokoll, bevor Sie Tools, Streaming oder multimodale Eingaben ergänzen.

Offizielle Entwicklerankündigung, aufgenommen am 13. November 2026. Das Bild belegt die Veröffentlichung, keinen API-Test und keine Leistungsmessung. Englische Quelle.

Google-Projekt und Verifizierung für die kostenlose Stufe vorbereiten

Öffnen Sie für das Google-Beispiel die API-Schlüsselseite in AI Studio. Stellen Sie fest, welchem Projekt die Anfrage zugeordnet werden soll. Neue Nutzer können ein Standardprojekt erhalten; vorhandene Cloud-Projekte müssen gegebenenfalls in AI Studio importiert werden. Erstellen oder wählen Sie einen Schlüssel für das gewünschte Projekt und prüfen Sie dessen Stufe und verfügbares Kontingent. Ein Schlüssel eines anderen Projekts kann funktionieren, verbraucht aber dessen Kontingent.

Hydrogens Verfügbarkeit in der kostenlosen Stufe bedeutet nicht, dass jedes neue Projekt sofort einsatzbereit ist. Laut Googles Anleitung zur Projektverifizierung können zusätzliche und außerhalb von AI Studio angelegte Projekte eine Verifizierung benötigen. Betroffene Anfragen liefern 403 mit FREE_TIER_VERIFICATION_REQUIRED.

Wenn genau dieser Fehler auftritt:

1. Öffnen Sie den Verifizierungslink aus der Fehlermeldung oder wählen Sie auf der Projects-Seite in AI Studio Verify project. Die Projektnummer muss zu Ihrem Schlüssel gehören.
2. Folgen Sie Googles Geräteverifizierung mit einem unterstützten physischen Smartphone. Fehlen Ihnen Projektberechtigungen, muss der Projektadministrator die Verifizierung durchführen.
3. Warten Sie auf die Bestätigung und wiederholen Sie anschließend die kleine Anfrage unten einmal.

Ein neuer Schlüssel im selben Projekt hebt eine projektbezogene Verifizierungspflicht nicht auf. Eine kostenpflichtige Abrechnung einzurichten ist eine separate Alternative mit eigenen Kosten, kein obligatorischer erster Schritt für alle Hydrogen-Nutzer. Ändern Sie die Abrechnung nicht allein wegen eines allgemeinen 403, ohne dessen Ursache zu lesen.

Prüfen Sie die aktiven Ratenlimits in AI Studio. Google begrenzt pro Projekt, nicht pro Schlüssel. Anfrage- und Tokenlimits können unabhängig voneinander greifen. Zwei Schlüssel eines Projekts ergeben deshalb keine zwei unabhängigen Kontingente. Eine universelle Zahl kostenloser Anfragen pro Minute nennen wir nicht: Maßgeblich sind die Limits für Ihr Projekt und Modell.

Speichern Sie den Schlüssel serverseitig in GEMINI_API_KEY oder laden Sie ihn über die Geheimnisverwaltung Ihrer Deployment-Umgebung. Er gehört weder in Browsercode noch ins Repository. Googles aktuelle Schlüsseldokumentation unterscheidet Autorisierungsschlüssel und Standardschlüssel: AI Studio erzeugt standardmäßig Autorisierungsschlüssel. Uneingeschränkte Standardschlüssel werden abgelehnt; ausdrücklich eingeschränkte Standardschlüssel können weiterhin funktionieren.

Das folgende Programm liest GEMINI_API_KEY ausdrücklich. So umgehen Sie die automatische SDK-Priorität, bei der ein gleichzeitig vorhandenes GOOGLE_API_KEY bevorzugt würde. Unter macOS/Linux setzen Sie export GEMINI_API_KEY="YOUR_GOOGLE_KEY", in PowerShell $env:GEMINI_API_KEY="YOUR_GOOGLE_KEY". Ersetzen Sie den Platzhalter lokal und vermeiden Sie Schlüssel in gemeinsam genutzten Shell-Verläufen. Variable und Programm müssen in derselben Terminalsitzung verwendet werden.

Google-Anfrage mit Python senden

Verwenden Sie für das aktuelle SDK Python 3.11 oder neuer und erstellen Sie eine isolierte Umgebung. Unsere lokalen Prüfungen liefen mit google-genai 3.3.0 unter Python 3.11; das Paket verlangt mindestens Python 3.11. Verwendet wird google-genai, nicht das ältere Paket google-generativeai.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

In Windows PowerShell aktivieren Sie die Umgebung mit .venv\Scripts\Activate.ps1. Die Versionsuntergrenze umfasst die Python-Unterstützung für Fortsetzungen im Vordergrund. Dieser kurze Test bleibt allerdings innerhalb des Budgets einer einzelnen Hydrogen-Antwort. Speichern Sie Folgendes als hydrogen_google.py:

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended Google project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give exactly three short bullet points about avoiding duplicate API retries.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 65536,
    },
)
Path("hydrogen-google.json").write_text(
    json.dumps(interaction.model_dump(mode="json"), indent=2),
    encoding="utf-8",
)
print("Saved hydrogen-google.json")
print("Interaction:", interaction.id)
print("Status:", interaction.status)

Führen Sie python hydrogen_google.py aus. Der Befehl sendet eine echte Anfrage an das Projekt Ihres Schlüssels; Nutzung in der kostenpflichtigen Stufe wird berechnet. Das Programm speichert die Antwort auch dann, wenn keine brauchbare Textantwort vorliegt. Führen Sie deshalb anschließend den untenstehenden Prüfer aus.

Der Prompt ist bewusst kurz und verwendet low. Der Wert 65.536 ist eine Obergrenze für Denken und sichtbare Ausgabe zusammen, keine Aufforderung, so viele Tokens zu erzeugen, und keine garantierte Abrechnungsmenge. Bei einer zu kleinen Grenze kann nach dem Denken kein Platz für Text verbleiben. Halten Sie die Eingabe klein und prüfen Sie den tatsächlichen Verbrauch, statt Obergrenze und Verbrauch gleichzusetzen.

store=False macht daraus eine einmalige Interaktion ohne gespeicherten Interaktionszustand. Übernehmen Sie diese Einstellung nicht unverändert für Hintergrundaufträge oder Gespräche mit previous_interaction_id. Sie ist auch keine pauschale Zusage über sämtliche Formen der Protokollierung beim Anbieter. Die Interactions-Übersicht erläutert die Speicherung.

Ofox-Anfrage mit Chat Completions senden

Erstellen oder wählen Sie nach der Anleitung zur Einrichtung von API-Schlüsseln einen Ofox-Schlüssel und speichern Sie ihn serverseitig oder im lokalen Terminal als OFOX_API_KEY. Unter macOS/Linux: export OFOX_API_KEY="YOUR_OFOX_KEY"; in PowerShell: $env:OFOX_API_KEY="YOUR_OFOX_KEY". Ersetzen Sie den Platzhalter lokal. Prüfen Sie vor dem Aufruf das verfügbare Guthaben und die aktuelle Hydrogen-Modellseite auf Englisch. Googles kostenloses Kontingent bezahlt keine Ofox-Anfragen; Ofox-Guthaben bezahlt keine Aufrufe des Google-Endpunkts.

Unser vollständiger öffentlicher Katalogstand enthielt 133 Modelle, darunter google/gemini-4-hydrogen. Das bestätigt den datierten Eintrag und die angegebenen Protokolle, keinen erfolgreichen Inferenztest und keine Garantie für jedes Konto, jeden Anbieter oder spätere Konfigurationen.

Speichern Sie die Anfrage als hydrogen-ofox-request.json:

{
  "model": "google/gemini-4-hydrogen",
  "messages": [
    {
      "role": "user",
      "content": "Give exactly three short bullet points about avoiding duplicate API retries."
    }
  ],
  "max_tokens": 65536,
  "stream": false
}

Senden Sie sie im Terminal mit curl:

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://api.ofox.io/v1/chat/completions' \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-ofox-request.json \
  --output hydrogen-ofox.json

Das Beispiel folgt der Ofox-Dokumentation zu Chat Completions und Parametern. Bei einer späteren SDK-Einrichtung darf /v1 nur einmal vorkommen: Die Basis-URL lautet https://api.ofox.io/v1, der vollständige REST-Endpunkt enthält zusätzlich /chat/completions.

temperature, top_p und anbieterspezifische Thinking-Erweiterungen fehlen absichtlich. Googles natives generation_config ist kein OpenAI-Chat-Completions-Parameter. Kopieren Sie es nicht mit der Annahme, das Gateway leite es weiter. Prüfen Sie für die jeweilige Ofox-Schnittstelle zunächst die dokumentierte Parameterzuordnung. Die native Tabelle mit vier Thinking-Stufen unten belegt nicht, dass ein beliebiges kompatibles Zusatzfeld funktioniert.

Ein curl-Exitcode ungleich null zeigt einen HTTP- oder Transportfehler an. Prüfen Sie den gespeicherten Fehlertext und entfernen Sie Schlüssel aus geteilten Logs. Das Timeout ist eine Wartegrenze des Clients, keine Latenzprognose. Nach einem Timeout sollten Sie nicht sofort mehrere kostenpflichtige Anfragen erneut senden: Der Clientabbruch beweist nicht, dass die Verarbeitung beim Anbieter beendet ist.

Antwort passend zum Protokoll prüfen

HTTP 200 kann eine unfertige Interaktion, einen Tool-Aufruf oder keinen nutzbaren Text enthalten. Umgekehrt erscheint eine korrekte Antwort leer, wenn der Parser die Felder der anderen API liest. Das Google-SDK bietet interaction.output_text als Hilfseigenschaft; die gespeicherte Interaktionsressource verwendet steps. Chat Completions verwendet choices.

Speichern Sie diesen vollständigen Prüfer als check_hydrogen.py. Er liest lokale Dateien, stellt keine Netzwerkanfrage und wiederholt keine Inferenz.

import json
import sys
from pathlib import Path

def validate(payload, route):
    if "error" in payload:
        raise ValueError("API error: " + json.dumps(payload["error"]))
    if route == "google":
        if payload.get("status") != "completed":
            raise ValueError("Interaction is not completed: " + str(payload.get("status")))
        text = "".join(
            part.get("text", "")
            for step in payload.get("steps", [])
            if step.get("type") == "model_output"
            for part in step.get("content", [])
            if part.get("type") == "text"
        )
    elif route == "ofox":
        choices = payload.get("choices") or []
        if not choices:
            raise ValueError("No Chat Completions choices in response")
        choice = choices[0]
        if choice.get("finish_reason") != "stop":
            raise ValueError("Text did not finish normally: " + str(choice.get("finish_reason")))
        text = (choice.get("message") or {}).get("content") or ""
    else:
        raise ValueError("Route must be google or ofox")
    if not isinstance(text, str) or not text.strip():
        raise ValueError("No usable text; inspect the saved JSON")
    return text

def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python check_hydrogen.py google|ofox response.json")
    payload = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
    try:
        text = validate(payload, sys.argv[1])
    except ValueError as exc:
        raise SystemExit(str(exc))
    print("Response ID:", payload.get("id"))
    print("Usage:", json.dumps(payload.get("usage")))
    print(text)

if __name__ == "__main__":
    main()

Für Google führen Sie python check_hydrogen.py google hydrogen-google.json aus, für Ofox python check_hydrogen.py ofox hydrogen-ofox.json. Bei Erfolg erscheinen Antwort-ID, usage und sichtbarer Text. Lesen Sie den Text: Er muss drei kurze, relevante Stichpunkte enthalten. Der Prüfer kontrolliert Protokollabschluss und nichtleeren Text, nicht die sachliche Richtigkeit der Modellantwort.

Wir haben die Logik lokal mit synthetischen abgeschlossenen, leeren, fehlerhaften, unvollständigen und Tool-Antworten geprüft, einschließlich Text über mehrere Google-Ausgabeschritte. Das belegt das Verhalten des Prüfers, keine Live-Authentifizierung, Kontingente, Latenz oder Antwortqualität. tool_calls kann in einer Tool-Anwendung ein korrekter Abschlussgrund sein. Dieser reine Texttest lehnt ihn ab, weil noch keine endgültige Antwort vorliegt.

Denkaufwand und Ausgabelänge getrennt einstellen

Hydrogens native API unterstützt vier Thinking-Stufen. Standard ist high, bei Carbon und Argon dagegen medium. Googles Thinking-Dokumentation beschreibt den Denkaufwand, keine feste Wortzahl.

Das sind Ausgangspunkte für Tests, keine Ofox-Benchmarkergebnisse. Vergleichen Sie mit identischen Eingaben und Abnahmekriterien. Dokumentieren Sie Modell, Stufe, Antwortstatus, Dauer, Verbrauch und den Grund für Erfolg oder Misserfolg. Ändern Sie jeweils nur eine Einstellung. Eine kürzere sichtbare Antwort beweist keinen geringeren Thinking-Token-Verbrauch.

Hydrogen teilt 1.048.576 Tokens zwischen Eingabe, Denken und Ausgabe. Es gibt nicht eine Million Eingabetokens plus eine separate Million Antworttokens. Das synchrone Standardbudget für Denken und Ausgabe beträgt 65.536 Tokens; diese Grenze gilt für eine einzelne Streaming- oder Nicht-Streaming-Antwort. Größere Ausgaben benötigen die unter Long Decode beschriebenen Fortsetzungs- oder Hintergrundmechanismen.

Setzen Sie beim ersten Test nicht eine Million Ausgabetokens. Bei späterer Hintergrundausführung müssen Sie die Auftrags-ID speichern und wartende sowie endgültige Zustände ausdrücklich behandeln. background=true allein erhöht die Standardgrenze nicht. Dieser Leitfaden prüft eine kurze Vordergrundanfrage, keinen Controller für lang laufende Aufträge.

Hydrogen erzeugt Text. Die Modellkarte nennt Bild-, Video-, Audio- und PDF-Eingaben, aber keine native Bildgenerierung, Audiogenerierung oder Live-API-Unterstützung. Ein Bild zu analysieren und ein neues Bild zu erzeugen sind unterschiedliche Fähigkeiten. Ergänzen Sie einen unterstützten Eingabetyp erst nach einem erfolgreichen Texttest.

Fehler auf der betroffenen Ebene beheben

Dokumentieren Sie Endpunkt, Modellkennung, Projekt oder Konto, SDK-Version und genaue Fehlermeldung gemeinsam. Entfernen Sie Zugangsdaten vor dem Teilen. Wegen eines falschen Felds müssen Sie nicht die gesamte Umgebung neu aufbauen.

Für Ofox-Antworten nutzen Sie die Ofox-Anleitung zur Fehlerbehandlung, für Google die offizielle Fehlerreferenz. Die Anleitung zu Argon-API-Fehlern zeigt ebenfalls, wie sich Schnittstellen-, Kontingent- und Parserfehler trennen lassen. Ihre modellspezifischen Einstellungen sind keine Hydrogen-Standardwerte.

Wenn Sie Tools ergänzen, deklarieren Sie sie über die nativen Tool-Felder der gewählten API. Eine Aufforderung im Prompt, ein selbst erfundenes Aufrufformat auszugeben, reicht nicht, damit ein Executor dieses erkennt. Bewahren Sie erforderlichen Gesprächsverlauf und Signaturen. Bei einem entsprechenden Fehler hilft die Diagnose fehlender Thought Signatures auf Englisch.

Eine reproduzierbare Ausgangskonfiguration sichern

Die erste Integration ist bereit für Erweiterungen, wenn eine Antwort gespeichert wurde, der richtige Abschlussstatus vorliegt, der Text die drei geforderten Stichpunkte enthält und der Verbrauch dem richtigen Projekt oder Konto zugeordnet ist. Speichern Sie dazu Modell, Schnittstelle, SDK-Version und Konfiguration, aber keine Schlüssel.

Ergänzen Sie danach genau eine Änderung: einen echten Aufgabenprompt, eine unterstützte Datei, Streaming oder ein deklariertes Tool. Scheitert die neue Version, führen Sie den Ausgangstest erneut aus. So unterscheiden Sie einen Zugriffsfehler von einem Problem der neuen Funktion.

Soll die nächste schwierigere Aufgabe an Carbon gehen, hilft der Gemini-4-Auswahlleitfaden. Andere Zugangsvoraussetzungen und Einstellungen für den ersten Carbon-Aufruf beschreibt die Carbon-API-Anleitung. Ein erfolgreicher Hydrogen-Aufruf belegt Ihre konkrete Integration, nicht die unveränderte Übertragbarkeit von Konto, Parametern und Parser auf jeden Dienst.