Blog

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

Nov 17, 2026
Flaches, tief indigofarbenes Cover-Artwork mit verschachtelten breiten Chevron-Pfeilen, deren vordere Kanten aprikosenfarben sind und die diagonal nach oben verlaufen, für einen HiAPI-Tutorial-Artikel.
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 @vertex ist 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

  1. 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.
  2. Die HiAPI-Basis-URL. Alle Modellaufrufe gehen an denselben Host; die Modellvariante wird über das Feld model gewählt, nicht über den Pfad.
  3. Zwei Header bei jeder Anfrage:
    • Authorization: Bearer $HIAPI_API_KEY
    • Content-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 auf gemini-4-argon oder gemini-4-carbon@vertex, um ohne sonstige Änderungen ein anderes Ziel zu treffen.
  • messages – ein geordnetes Array. Die Rollen sind system, user und assistant. 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=60 ein 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=True an requests. 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/except oben 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:

  1. Sende die Nutzernachricht zusammen mit den Werkzeugdeklarationen.
  2. Prüfe den Assistenten-Turn. Wenn er Tool-Calling-Argumente enthält, möchte das Modell, dass du etwas ausführst.
  3. Führe die lokale Funktion aus – HiAPI führt deinen Code nicht aus.
  4. 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.
  5. 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: false aus, 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

  1. Reine Text-Turns – bestätige, dass die ID erkannt wird und die Authentifizierung weiterhin funktioniert.
  2. Dein längster echter Prompt – verschiedene Varianten können lange oder strukturierte Eingaben unterschiedlich behandeln; überprüfe Abschneiden und Formatierung.
  3. Streaming – führe den Streaming-Pfad erneut aus, da sich Chunk-Takt und -Grenzen je nach Ziel unterscheiden können.
  4. 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-carbon und gemini-4-carbon@vertex – das Suffix @vertex wird am häufigsten übersehen.

Probleme mit dem Request-Body

  • 400 mit einer Schema-Meldung. Meist ist messages fehlerhaft formatiert: fehlende role, content sollte 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=True zu setzen, sodass requests den 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 →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen