Tutorial
Gemini-4 Argon und Carbon auf HiAPI: curl, Python und ausführbare Anfragen
Ein praktischer Integrationsleitfaden für Entwickler, die zwischen gemini-4-argon, gemini-4-carbon und gemini-4-carbon@vertex wählen
Auf dieser Seite
Wähle die Gemini-4-Variante, bevor du Code schreibst
Die erste Entscheidung bei jeder Gemini-4-Integration ist nicht curl oder Python – sondern welche Modell-ID du sendest. Auf HiAPI sind gemini-4-argon, gemini-4-carbon und gemini-4-carbon@vertex drei verschiedene routbare Ziele, und der String, den du im Feld model übergibst, entscheidet, welches Backend deine Anfrage bedient. Wenn du das früh festlegst, ersparst du dir die Fehlersuche an einem Request-Body, der ohnehin nicht funktionieren kann.
Die drei Ziele in der Praxis
gemini-4-argon– eine eigenständige Gemini-4-Variante mit eigener Modell-ID. Behandle sie als eigenes Modell, nicht als Alias: Ihr Verhalten, ihre Latenzcharakteristik und ihre Ausgabeeigenschaften können sich von Carbon unterscheiden.gemini-4-carbon– das Standard-Carbon-Ziel unter dem Standard-Routing von HiAPI.gemini-4-carbon@vertex– dieselbe Carbon-Familie, aber über ein von Vertex unterstütztes Routing bereitgestellt. Das Suffix@vertexist Teil der Modell-ID selbst und kein separater Parameter.
So entscheidest du
Gehe von der Workload aus. Wenn du Gemini-4 breit evaluierst, führe denselben Prompt sowohl gegen gemini-4-argon als auch gegen gemini-4-carbon aus und vergleiche die Ausgaben, bevor du dich festlegst. Wenn du tatsächlich das Vertex-Routing brauchst – etwa weil es zu der Umgebung passt, die dein Team bereits betreibt –, ziele direkt auf gemini-4-carbon@vertex.
Der praktische Punkt: Alle drei verwenden dieselbe Request-Struktur. Die Variante zu wählen ist eine Änderung an einer Zeile, du kannst die endgültige Entscheidung also aufschieben, bis du eine lauffähige Anfrage hast. Wenn du zuerst die Modellkarte sehen möchtest, siehe gemini-4-argon und gemini-4-carbon.
Die Beispiele in diesem Leitfaden verwenden durchgängig gemini-4-carbon; um mit einer beliebigen Variante zu folgen, ersetze einfach diese ID.
Bereite Anmeldedaten und Basis-URL vor
Bevor ein Request-Body wichtig werden kann, müssen drei Dinge stimmen: die Basis-URL, der API-Schlüssel und das Format des Auth-Headers. Die meisten fehlgeschlagenen ersten Anfragen scheitern an einem dieser drei Punkte.
Was du brauchst
- Einen API-Schlüssel aus dem Dashboard deines HiAPI-Kontos. Behandle ihn als Geheimnis – lade ihn aus einer Umgebungsvariable, statt ihn in Quelldateien einzufügen.
- Die HiAPI-Basis-URL. Alle Modellaufrufe gehen an denselben Host; die Modellvariante wird über das Feld
modelgewählt, nicht über den Pfad. - Zwei Header bei jeder Anfrage:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
Richte deine Umgebung ein
export HIAPI_API_KEY="your-key-here"
Prüfe dann, bevor du Code schreibst, ob deine Shell ihn sieht:
echo "${HIAPI_API_KEY:0:4}..."
Wenn nichts ausgegeben wird, ist dein Schlüssel in der aktuellen Shell nicht exportiert, und jede Anfrage wird mit einem Authentifizierungsfehler scheitern. Behebe das hier, nicht in deinem Client.
Die Request-Struktur, die du immer wieder verwenden wirst
Jedes Beispiel unten sendet einen JSON-Request-Body mit einem model-String und einem messages-Array. Diese Struktur ändert sich nicht zwischen curl und Python, zwischen Nicht-Streaming und Streaming und zwischen den Modellvarianten. Halte sie stabil, dann kannst du Code durch Kopieren des Request-Bodys portieren.
Eine ausführbare curl-Anfrage
Hier ist ein vollständiger, direkt kopier- und einfügbarer Nicht-Streaming-Aufruf. Führe ihn aus, bevor du irgendetwas anderes hinzufügst – wenn er durchläuft, sind dein Schlüssel, deine Basis-URL und deine Header korrekt.
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "Du bist ein prägnanter technischer Assistent."},
{"role": "user", "content": "Erkläre in zwei Sätzen, was ein Idempotenzschlüssel ist."}
]
}'
Was jedes Feld bewirkt
model– der Varianten-Selektor. Ändere ihn aufgemini-4-argonodergemini-4-carbon@vertex, um ohne sonstige Änderungen ein anderes Ziel zu treffen.messages– ein geordnetes Array. Die Rollen sindsystem,userundassistant. Wenn du eine Systemnachricht verwendest, stelle sie an den Anfang.content– der Nachrichtentext. Bei einfachen Text-Turns ist er ein gewöhnlicher String.
Den Response-Body lesen
Die Antwort ist ein JSON-Objekt, das die Antwort des Modells sowie Metadaten wie den Token-Verbrauch enthält. Da dies Nicht-Streaming ist, kommt der gesamte Body auf einmal an, und curl beendet sich nach dem Ausgeben. Wenn du ein parsebares JSON-Objekt mit einer Nachrichtenantwort erhältst, funktioniert deine Anfrage – alles Weitere baut auf dieser Basis auf.
Ein schneller Plausibilitätscheck: Pipe die Ausgabe durch einen JSON-Formatter (| jq .), damit die Antwortstruktur lesbar ist statt einer langen Textzeile.
Sende dieselbe Anfrage mit Python
Die Python-Version behält den Request-Body exakt bei – nur der Transport ändert sich. Verwende requests:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "Du bist ein prägnanter technischer Assistent."},
{"role": "user", "content": "Erkläre in zwei Sätzen, was ein Idempotenzschlüssel ist."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
Warum das exakt dem curl-Aufruf entspricht
Beachte, dass payload bytegleich mit dem JSON-Request-Body aus dem vorherigen Abschnitt ist. Der Parameter json= serialisiert ihn und setzt Content-Type für dich; das Header-Dictionary liefert die Authentifizierung. Modell, Nachrichten und Rollen bleiben unverändert.
Zwei Angewohnheiten, die es sich zu behalten lohnt
- Setze ein Timeout. Ohne Timeout lässt eine stockende Verbindung deinen Prozess unbegrenzt hängen. Für Nicht-Streaming-Aufrufe ist
timeout=60ein vernünftiger Ausgangspunkt. - Rufe
raise_for_status()auf, bevor du den Response-Body liest. Fehlgeschlagene Anfragen liefern ein strukturiertes Fehlerobjekt statt einer Completion –json()bei einem 4xx zu prüfen, führt dich in die Irre. Lass zuerst die Exception auslösen und protokolliere dann den Antworttext.
Lege den Request-Body in einer Funktion oder einem kleinen Konfigurationsobjekt ab, damit die Streaming- und Tool-Calling-Abschnitte ihn erweitern können, statt ihn zu kopieren.
Füge Streaming-Unterstützung für Aufrufe hinzu
Bringe zuerst die Nicht-Streaming-Anfrage zum Laufen. Aktiviere Streaming erst danach – die Fehlermuster sind anders, und zwei gleichzeitige Änderungen machen Fehler schwer unterscheidbar.
Streaming aktivieren
Füge dem bestehenden Request-Body ein Feld hinzu:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "Nenne drei Anwendungsfälle für eine Message Queue."}
]
}
Das ist die gesamte Protokolländerung. Der Server gibt jetzt eine Folge von Events zurück statt eines einzelnen JSON-Dokuments.
Den Stream korrekt konsumieren
Die entscheidende Regel: Rufe bei einer Streaming-Antwort nicht .json() auf. Du bekommst einen Parse-Fehler, weil der Response-Body kein einzelnes JSON-Objekt ist. Mit requests iterierst du zeilenweise und parst jeden Chunk einzeln:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "Nenne drei Anwendungsfälle für eine Message Queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
Worauf du achten musst
- Übergib
stream=Trueanrequests. Andernfalls puffert der Client den gesamten Response-Body, bevor du eine einzige Zeile siehst, was dem Zweck widerspricht. - Überspringe Leerzeilen und Nicht-JSON-Keepalive-Nachrichten. Das
try/exceptoben ist Absicht – der Stream kann Zeilen enthalten, die sich nicht als Chunks parsen lassen. - Akkumuliere Text über mehrere Chunks. Jeder Chunk trägt ein Fragment, nicht die vollständige Antwort. Hänge die Text-Deltas an, während sie eintreffen.
Sobald Streaming funktioniert, setze stream in deinen Nicht-Streaming-Tests wieder auf false, damit Tool-Calling leicht lesbar bleibt. Für einen Überblick über das Carbon-Ziel ist die gemini-4-carbon-Modellseite ein guter Ausgangspunkt.
Füge Tool-Calling zum Request-Body hinzu
Tool-Calling ändert die Anfrage an zwei Stellen: Du deklarierst Werkzeuge, und du behandelst einen Antwort-Turn, der Tool-Calling-Anfragen statt Text enthalten kann. Füge diese Funktion erst hinzu, nachdem ein Nicht-Streaming-Textaufruf funktioniert.
Werkzeuge deklarieren
Füge neben model und messages ein tools-Array hinzu. Jedes Werkzeug hat einen Namen, eine Beschreibung und ein JSON-Schema für seine Parameter. Die Beschreibung ist wichtig – sie ist die Grundlage, anhand derer das Modell entscheidet, ob es das Werkzeug aufruft.
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "Wie ist das Wetter in Lissabon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gibt das aktuelle Wetter für eine Stadt zurück.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Stadtname"}
},
"required": ["city"]
}
}
}
]
}
Die Tool-Calling-Schleife
Eine Anfrage mit Werkzeugen ist eine Konversation, kein einzelner Aufruf:
- Sende die Nutzernachricht zusammen mit den Werkzeugdeklarationen.
- Prüfe den Assistenten-Turn. Wenn er Tool-Calling-Argumente enthält, möchte das Modell, dass du etwas ausführst.
- Führe die lokale Funktion aus – HiAPI führt deinen Code nicht aus.
- Hänge zwei Nachrichten an: den Tool-Calling-Turn des Assistenten und eine
tool-Rollen-Nachricht mit dem Funktionsergebnis, verknüpft über die passende Call-ID. - Sende die vollständige Nachrichtenhistorie erneut. Das Modell liefert jetzt die endgültige Antwort.
Werkzeug-spezifische Fehlerquellen
- Schema-Mismatch. Wenn dein
parameters-Schema ein Feld als erforderlich markiert, das Ergebnis es aber auslässt, können nachfolgende Turns abgelehnt werden. Halte das Schema präzise. - Verworfene Historie. Jeder erneute Versand muss die ursprüngliche Nutzernachricht und den Tool-Calling-Turn enthalten – nicht nur das Werkzeugergebnis.
- Streaming plus Werkzeuge. Tool-Calling-Argumente können über mehrere Stream-Chunks verteilt ankommen. Führe Werkzeuge während deiner Lernphase mit
stream: falseaus, damit jeder Turn als lesbares Objekt ankommt.
Modelle und Anbieter wechseln, ohne den Client neu zu schreiben
Da die Modellvariante nur ein String im Request-Body ist, ist ein Zielwechsel eine Konfigurationsänderung, kein Refactoring. Gestalte den Client so, dass er die Modell-ID aus einer Variablen liest – Umgebungsvariable, Konfigurationsdatei, CLI-Flag – und sie niemals an mehreren Stellen fest kodiert.
Der Wechsel selbst
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
Verweise im Code im Request-Body auf diese Variable:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
Das Suffix @vertex wird mit dem Modell-String übergeben. Zerlege es nicht in ein separates Feld und entferne es nicht – es ist Teil der routbaren ID, und wenn du es entfernst, wirst du stillschweigend zum Nicht-Vertex-Ziel geroutet.
Was du nach dem Wechsel erneut testen musst
- Reine Text-Turns – bestätige, dass die ID erkannt wird und die Authentifizierung weiterhin funktioniert.
- Dein längster echter Prompt – verschiedene Varianten können lange oder strukturierte Eingaben unterschiedlich behandeln; überprüfe Abschneiden und Formatierung.
- Streaming – führe den Streaming-Pfad erneut aus, da sich Chunk-Takt und -Grenzen je nach Ziel unterscheiden können.
- Tool-Calling – validiere erneut die vollständige Tool-Calling-Schleife; das Parameterformat ist der Ort, an dem Variantenunterschiede am häufigsten zutage treten.
Behalte ein kleines Smoke-Test-Skript, das diese vier Prüfungen gegen das aktuell gesetzte HIAPI_MODEL ausführt. So wird ein Anbieterwechsel zu einer Konfigurationsänderung plus einem Befehl statt zu einer Debugging-Sitzung.
Häufige Anfragefehler beheben
Nahezu jeder Integrationsfehler fällt in wenige Kategorien. Ordne das Symptom zu, wende die Lösung an und führe die Nicht-Streaming-Baseline erneut aus, bevor du irgendetwas anderes änderst.
Authentifizierung und Routing
- 401 oder 403. Schlüssel fehlt, ist abgelaufen oder hat ein falsches Präfix. Prüfe, ob der Header exakt
Authorization: Bearer <key>lautet, mit genau einem Leerzeichen dazwischen, und stelle sicher, dass die Variable tatsächlich in der Shell oder im Prozess exportiert wurde, der den Code ausführt. Gib die ersten Zeichen aus, um es zu bestätigen. - Endpunkt gibt 404 zurück. Deine Basis-URL ist falsch oder ein Pfadsegment ist doppelt. Das Modell gehört in den Request-Body, nicht in die URL.
- Modell nicht gefunden. Die Modell-ID hat einen Tippfehler. Vergleiche Zeichen für Zeichen mit
gemini-4-argon,gemini-4-carbonundgemini-4-carbon@vertex– das Suffix@vertexwird am häufigsten übersehen.
Probleme mit dem Request-Body
- 400 mit einer Schema-Meldung. Meist ist
messagesfehlerhaft formatiert: fehlenderole,contentsollte ein String sein ist es aber nicht, oder ein leeres Array. Beginne mit dem kleinsten zweizeiligen Request-Body aus diesem Leitfaden und füge Feld für Feld hinzu. - 400 nach dem Hinzufügen von Werkzeugen. Dein
parameters-Schema ist kein gültiges JSON Schema, oder der Tool-Ergebnis-Turn stimmt nicht mit der Call-ID in der Assistenten-Nachricht überein. Protokolliere den vollständigen Response-Body – der Fehlertext benennt das problematische Feld.
Streaming-Fehler
- JSON-Parse-Fehler bei der Antwort. Du rufst
.json()auf einem Stream auf. Iteriere stattdessen zeilenweise, parse jeden Chunk und überspringe Leerzeilen und den[DONE]-Marker. - Antwort kommt auf einmal an. Du hast vergessen, im Client-Aufruf
stream=Truezu setzen, sodassrequestsden gesamten Response-Body gepuffert hat. - Ausgabe wird abgeschnitten. Deine Schleife bricht zu früh ab – meist an einer Leerzeile oder Keepalive-Nachricht. Stoppe nur am expliziten Stream-Ende-Marker.
Debugging-Disziplin
Bisektiere in derselben Reihenfolge, in der du gebaut hast: Authentifizierung und Header, dann Nicht-Streaming-Text, dann Streaming, dann Werkzeuge. Jede Ebene hat unterschiedliche Fehlermuster, daher ist fast immer das, was du zuletzt geändert hast, die Ursache. Protokolliere bei jedem Fehler den HTTP-Status und den vollständigen Response-Body – die Meldung benennt oft das konkrete Feld.
Bringe zuerst die Baseline auf gemini-4-argon oder gemini-4-carbon zum Laufen und erweitere den Request-Body von dort aus. Wenn du noch entscheidest, welche Variante zu deiner Workload passt, ist die gemini-4-argon-Modellseite der Einstiegspunkt.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen
-
Tutorial
gemini-4-neon Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Integrationshinweise
-
Tutorial
seedance-2.5-flash 图生视频 API 教程:curl 与 Python Requests
Eine praktische Integrationsübung für Entwickler: Anfragestruktur, Start-/Endbild-Eingaben, asynchrones Polling und Fehlersuche