Gemini 4 Carbon API einrichten und die erste Antwort prüfen

Verwenden Sie die genaue Modell-ID gemini-4-carbon mit einem kostenpflichtigen Gemini-API-Projekt. Für neue Integrationen empfiehlt Google die Interactions API. Die Einrichtung ist erst geprüft, wenn eine abgeschlossene Interaktion einen brauchbaren Text liefert. HTTP 200 allein reicht nicht aus.

Carbon ist seit dem 10. November 2026 für zahlende API-Entwickler öffentlich verfügbar. Die frühere Ankündigung eines beschränkten Zugangs beschreibt die aktuellen Bedingungen daher nicht mehr vollständig. Dieser Leitfaden basiert auf der am 13. November 2026 geprüften Dokumentation und führt von Projekt und Schlüssel bis zu einer gespeicherten, überprüfbaren Antwort.

Die Beispiele verwenden Googles native API, keinen Ofox-Endpunkt. Wir haben das dokumentierte Anfrageformat geprüft und den Antwortparser mit synthetischen Daten getestet. Für diesen Artikel haben wir keine kostenpflichtige Carbon-Anfrage ausgeführt. Der Prompt ist somit eine Vorlage für Ihren Test und kein gemessenes Modellergebnis. Falls die Modellwahl noch offen ist, hilft der Vergleich von Carbon, Hydrogen und Argon.

1. Den Schlüssel dem richtigen bezahlten Projekt zuordnen

Sie benötigen ein für die Gemini API zugelassenes Google-Konto, ein in AI Studio zugängliches Google-Cloud-Projekt, einen Schlüssel dieses Projekts und eine aktive API-Abrechnung. Prüfen Sie diese vier Voraussetzungen getrennt. Ein Abo der Gemini-App oder von Google AI Ultra richtet nicht automatisch die API-Abrechnung für das Projekt Ihrer Anwendung ein.

1. Öffnen Sie Google AI Studio und wählen Sie das vorgesehene Projekt. Importieren Sie ein bereits vorhandenes Cloud-Projekt bei Bedarf, statt ein unverbundenes Projekt anzulegen, nur um die Schaltfläche zur Schlüsselerstellung zu sehen.
2. Erstellen oder wählen Sie den Schlüssel in der API-Schlüsselverwaltung dieses Projekts. Halten Sie in Ihren Deployment-Notizen Projektname oder Projekt-ID fest, nicht den geheimen Schlüssel. Terminal und Server müssen den Schlüssel desselben Projekts laden.
3. Schließen Sie in den Abrechnungseinstellungen von AI Studio die Einrichtung für dieses Projekt ab. Je nach Konto gibt es Prepay, eine Auswahl zwischen Prepay und Postpay oder eine übergangsweise Postpay-Regelung. Prepay kann eine Mindestzahlung von 5 US-Dollar beziehungsweise dem lokalen Gegenwert erfordern. Maßgeblich ist der angezeigte Kontostatus: Eine hinterlegte Karte allein beweist keine verfügbare Finanzierung für Anfragen.
4. Prüfen Sie die aktive Abrechnung und gegebenenfalls das verfügbare Prepay-Guthaben. Kontrollieren Sie vor der Anfrage Kontingente und regionale Voraussetzungen. Auch bezahlte Projekte haben Grenzen.

Quellen sind Googles Anleitung für API-Schlüssel und die Abrechnungsdokumentation, beide auf Englisch. Fehlen Projektimport oder Schlüsselerstellung, lassen Sie die dafür nötigen Berechtigungen vom Projektadministrator prüfen. Veröffentlichen Sie keinen Schlüssel und vergeben Sie nicht wahllos weitreichende Rechte, um eine fehlende Schaltfläche zu umgehen.

Offizielle englische Seite, aufgenommen am 13. November 2026. Sie belegt die öffentliche Entwicklerfreigabe, nicht den Abrechnungsstatus Ihres Kontos oder einen erfolgreichen API-Aufruf. Originalankündigung.

Alte Schlüssel scheitern nicht nur an Tippfehlern

Neue AI-Studio-Schlüssel sind derzeit standardmäßig Authorization Keys. Laut aktueller Dokumentation werden uneingeschränkte Standard Keys abgelehnt; ausdrücklich eingeschränkte Standard Keys funktionieren weiterhin. Prüfen Sie Typ und Einschränkungen, statt alle älteren Schlüssel pauschal als ungültig einzustufen.

Speichern Sie den Schlüssel in einer serverseitigen Umgebungsvariable oder einem Secret-Manager. Lokal setzen Sie GEMINI_API_KEY, ohne den Wert in das Repository einzuchecken. Er gehört auch nicht in Screenshots, Fehlerberichte oder Browser-JavaScript. Die Beispiele lesen GEMINI_API_KEY ausdrücklich aus: Bei automatischer Erkennung bevorzugt das SDK GOOGLE_API_KEY. Ein alter Wert dieser Variable könnte sonst unbemerkt ein anderes Projekt auswählen.

Prüfen Sie lediglich, ob die Variable gesetzt ist, ohne ihren Inhalt auszugeben:

python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'

True bestätigt nur einen vorhandenen Wert. Schlüsselgültigkeit, Projekt und Abrechnung sind damit nicht geprüft. Die folgende Anfrage liefert den nächsten Nachweis.

2. Eine erste Python-Anfrage mit festgelegtem Limit senden

Nutzen Sie eine eigene Umgebung, damit kein altes SDK einer anderen Anwendung das Verhalten bestimmt:

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

Unter Windows PowerShell aktivieren Sie die Umgebung mit .venv\Scripts\Activate.ps1. Das Paket heißt google-genai, der Import lautet from google import genai. Ersetzen Sie es nicht durch das ältere google-generativeai. Grundlegende Interactions-Unterstützung und automatische Fortsetzung im Vordergrund haben unterschiedliche Mindestversionen. Die angegebene Untergrenze schließt die aktuelle Python-Fortsetzung ein, obwohl die kurze Anfrage absichtlich innerhalb eines einzelnen Antwortschritts bleibt. Siehe Interactions und Long Decode, jeweils auf Englisch.

Speichern Sie Folgendes als carbon_first_call.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 paid project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Return exactly three checklist items for reviewing an API integration.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 32768,
    },
)

payload = interaction.model_dump(mode="json")
Path("carbon-response.json").write_text(
    json.dumps(payload, indent=2), encoding="utf-8"
)
text = interaction.output_text or ""
print("Interaction:", interaction.id)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
if interaction.status != "completed" or not text.strip():
    raise SystemExit("No completed text result; inspect carbon-response.json.")
print(text)

Starten Sie python carbon_first_call.py. Dabei wird eine kostenpflichtige Anfrage gesendet. Führen Sie zunächst nur eine Variante aus, statt Python und REST automatisch als doppelte Tests nacheinander aufzurufen. 32.768 Token sind eine gemeinsame Obergrenze für Denken und sichtbare Ausgabe, keine Kostenprognose und keine Aufforderung, so viel Text zu erzeugen. Der kurze Prompt mit low dient der Zugriffskontrolle statt einer komplexen Recherche.

Bei Erfolg sehen Sie eine Interaktions-ID, completed, Nutzungsdaten und drei sinnvolle Prüfpunkte. Lesen Sie auch die Antwort: Eine abgeschlossene Interaktion kann inhaltliche oder formale Vorgaben verfehlen. Bewahren Sie das JSON zur Diagnose auf. Ersetzen Sie den harmlosen Prompt später durch Kundendaten, behandeln Sie auch die Antwortdatei als möglicherweise vertraulich.

Wir setzen store=False, weil es um einen einzelnen Aufruf geht. Dies deaktiviert die Speicherung dieser Interaktion für späteren Abruf oder serverseitige Gesprächsfortsetzung. Es ist keine umfassende Zusage über sämtliche Protokollierungsregeln von Anbietern. Der Standard ist store=true. Übernehmen Sie diese Einstellung nicht unverändert in Hintergrundaufgaben oder Beispiele mit previous_interaction_id.

3. REST aufrufen und die richtigen Antwortfelder lesen

Mit REST sehen Sie genau, was der Client sendet. Sie brauchen curl und Python 3 für den Parser. Speichern Sie den Anfrageinhalt als carbon-request.json:

{
  "model": "gemini-4-carbon",
  "input": "Return exactly three checklist items for reviewing an API integration.",
  "store": false,
  "generation_config": {
    "thinking_level": "low",
    "max_output_tokens": 32768
  }
}

Senden Sie ihn an den Interactions-Endpunkt:

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @carbon-request.json \
  --output carbon-response.json

Auch ein vom Server gelieferter Fehlertext wird zur Prüfung gespeichert. Ein curl-Exitcode ungleich null weist auf ein Transport- oder HTTP-Problem hin. Arbeiten Sie dann nicht weiter, als wäre eine Antwort eingetroffen. Die 900 Sekunden sind ein ausdrückliches Client-Zeitlimit, keine Behauptung, dass Carbon immer 15 Minuten benötigt. Ein Client-Timeout beweist außerdem nicht, dass die Verarbeitung auf dem Server beendet wurde. Wiederholen Sie eine möglicherweise kostenpflichtige Aufgabe nicht sofort, ohne ihren Zustand zu prüfen.

output_text ist eine Komforteigenschaft des SDK und kein REST-Antwortfeld. Bei REST steht Text in steps, dort in model_output-Einträgen und deren Inhalten vom Typ text. Ein Parser für GenerateContents candidates oder das outputs eines älteren Beispiels kann eine gültige Antwort fälschlich als leer behandeln.

Speichern Sie neben der Antwort die Datei inspect_carbon.py:

import json
import sys
from pathlib import Path


def extract_text(payload):
    return "".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"
    )


def inspect(path):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if "error" in payload:
        raise SystemExit("API error: " + json.dumps(payload["error"]))
    text = extract_text(payload)
    print("Interaction:", payload.get("id"))
    print("Status:", payload.get("status"))
    print("Usage:", json.dumps(payload.get("usage")))
    if payload.get("status") != "completed" or not text.strip():
        raise SystemExit("No completed text result; inspect the saved response.")
    print(text)


if __name__ == "__main__":
    inspect(sys.argv[1] if len(sys.argv) > 1 else "carbon-response.json")

Führen Sie python3 inspect_carbon.py carbon-response.json aus. Der Parser verbindet alle Textteile, statt den ersten Schritt für die endgültige Antwort zu halten. Teilresultate und Interaktionen mit ausstehenden Aktionen werden bewusst nicht als Erfolg gewertet. Sie können den Parser für Monitoring verwenden, sollten einen Fehler aber nicht an eine unbegrenzte Wiederholungsschleife koppeln.

Wir haben abgeschlossene, leere, fehlerhafte und mehrteilige synthetische Antworten lokal getestet. Das prüft Extraktion und Fehlerbehandlung, belegt aber keine Authentifizierung, Verfügbarkeit, Latenz oder Qualität der echten Google-API.

4. Einstellungen vor dem echten Einsatz verstehen

Die erste Anfrage verzichtet bewusst auf Tools, große Dateien und einen langen Agentenzyklus. Ergänzen Sie diese einzeln, nachdem der Zugang funktioniert. Der Carbon-Entwicklerleitfaden auf Englisch beschreibt folgende Grenzen:

Für migrierte Anwendungen mit kleinen Ausgabelimits empfiehlt Google mindestens 32.768 Token für Denken und Ausgabe. Das ist eine Budgetentscheidung, kein Nachweis, dass jede Anfrage das Maximum verbraucht. Senken Sie gegebenenfalls die Denktiefe und prüfen Sie die Nutzung, statt Kosten aus der Antwortlänge abzuleiten. Preisbedingungen und nachvollziehbare Berechnungen enthält der Gemini-4-Modellvergleich.

Wenn aus dem ersten Aufruf eine lange Aufgabe wird

Erhöhen Sie nicht nur max_output_tokens, während der restliche Code unverändert bleibt. Die englische Long-Decode-Dokumentation unterscheidet Vordergrundfortsetzung, Streaming und Hintergrundausführung. Ein aktuelles SDK kann Vordergrundschritte zusammenführen. Ein eigener REST-Client muss dagegen requires_continuation behandeln und die nötigen Fortsetzungsdaten übergeben.

Für Hintergrundaufgaben aktivieren Sie Speicherung, sichern die ID und begrenzen die Wartezeit beim Polling. queued und in_progress bedeuten ausstehende Verarbeitung, completed ein prüfbares Ergebnis. incomplete, failed und cancelled sind verschiedene Ausgänge. requires_action verlangt eine Tool-Aktion; die finale Antwort liegt noch nicht vor. Ein größeres Budget oder background=true garantiert keine bestimmte Textlänge. Dieses Erstaufruf-Beispiel implementiert nicht den dafür separat erforderlichen Job-Controller.

Bei serverseitigem Gesprächsverlauf übernimmt previous_interaction_id die bisherige Unterhaltung, aber nicht tools, system_instruction oder generation_config. Senden Sie diese Einstellungen bei Bedarf in der nächsten Runde erneut. Interactions speichert Antworten standardmäßig. Googles bezahlter Zugang hat eine voreingestellte Aufbewahrung von 55 Tagen mit kürzeren konfigurierbaren Optionen. Entscheiden Sie das bewusst, statt eine kopierte Einstellung unbemerkt zu übernehmen.

5. Fehler in der Reihenfolge ihres Auftretens eingrenzen

Lesen Sie die strukturierte Fehlermeldung und notieren Sie Endpunkt, genaue Modell-ID, Projektkennung, SDK-Version und Zeitpunkt, ohne den Schlüssel. Reparieren Sie zuerst die früheste fehlerhafte Schicht, bevor Sie Prompts oder Tokenbudgets ändern.

Googles englische Fehlerreferenz erklärt die Kategorien. Unsere Argon-API-Fehleranalyse hilft ebenfalls bei der Trennung von Routing-, Kontingent- und Antwortproblemen. Argon-spezifische Details bleiben von Carbon zu unterscheiden. Tritt nach dem Hinzufügen von Tools ein Signaturfehler auf, nutzen Sie die Diagnose zu missing thought signature auf Englisch, statt den Verlauf blind zu löschen.

Einen vorhandenen Gemini-Client migrieren

Behalten Sie eine funktionierende Ausgangsversion und ändern Sie jeweils nur eine Schnittstellengrenze. Googles native GenerateContent API wird weiterhin unterstützt. Die Empfehlung von Interactions für neue Projekte verlangt keinen sofortigen Umbau jedes funktionierenden Clients.

Beim Wechsel müssen Anfrageformat und Antwortparser zusammen geändert werden. Nur das Modell auf gemini-4-carbon zu setzen und weiter candidates auszulesen, ist keine vollständige Migration. Prüfen Sie Denkstufen, entfernen Sie explizite Cache-Verweise und alte Sampling-Annahmen und überarbeiten Sie Timeout und Ausgabelimit. JavaScript-Interactions verwendet snake_case für generation_config, thinking_level und max_output_tokens. Übernehmen Sie nicht die Schreibweise der GenerateContent-Konfiguration.

Führen Sie den gleichen harmlosen Prüf-Prompt aus, bevor Sie Tools und Kundendateien wieder anschließen. Testen Sie anschließend eine repräsentative Aufgabe mit bekannten Abnahmekriterien. Ein erfolgreicher Erstaufruf bestätigt den Integrationspfad, nicht die Zuverlässigkeit eines mehrstufigen Produktionsagenten.

Funktioniert dieses Beispiel über Ofox?

Ofox veröffentlicht diesen Leitfaden, doch die Beispiele verwenden Googles native Zugangsdaten und Endpunkte. In unserem öffentlichen Catalog-Snapshot vom 13. November 2026 war Carbon nicht aufgeführt. Dies ist eine datierte Beobachtung, kein Beleg dafür, dass Carbon über kein Konto oder keine künftige Route unterstützt werden kann. Wir haben keinen Ofox-Carbon-Aufruf verifiziert und behaupten nicht, ein Austausch der Base URL genüge.

Prüfen Sie für Ofox zuerst die aktuelle Verfügbarkeit des genauen Modells und seine unterstützten Protokolle. Verwenden Sie dann die Ofox-Dokumentation zur Gemini API für Endpunkt, Authentifizierung und Anfrageformat dieser Route. Ofox- und Google-Schlüssel sind getrennt zu halten. Ein Gemini-kompatibler Pfad beweist keine Unterstützung des Google-Interactions-Endpunkts oder sämtlicher Carbon-Funktionen.

Fehler einer Ofox-Route prüfen Sie anhand der tatsächlichen Antwort und des Ofox-Leitfadens zur Fehlerbehandlung. Google-Abrechnung, Ofox-Guthaben und App-Abo sind unterschiedliche Systeme. Guthaben in einem bezahlt keine Anfragen an ein anderes.

Die erfolgreiche Erstprüfung dokumentieren

Speichern Sie vor Abschluss folgende Nachweise ohne Geheimnisse:

• Genaues Modell, Endpunkt, SDK-Version und Projektkennung.
• Eine Antwort mit Interaktions-ID, Status und Nutzungsdaten.
• Den extrahierten Text, der die drei geforderten Prüfpunkte enthält.
• Denkstufe, Ausgabebudget und Speicherentscheidung dieser Anfrage.
• Aufgetretene Fehler und die konkreten Korrekturen, die sie behoben haben.

Damit haben Sie eine Ausgangsprüfung für Zugang, Protokoll und Ausgabe. Funktioniert sie nach dem Ergänzen eines Tools oder großen Prompts weiterhin, während nur die neue Aufgabe scheitert, untersuchen Sie die Änderung. Sie müssen nicht erneut Schlüssel erstellen, Abrechnungsprojekte wechseln oder den ganzen Agenten immer wieder starten.