So rufst du gpt-5.6-terra@azure über die HiAPI API auf: curl- und Python-Leitfaden

Was gpt-5.6-terra@azure in einer HiAPI-Anfrage bedeutet

In einer HiAPI-Anfrage ist gpt-5.6-terra@azure ein Modellbezeichner – du musst ihn in das Feld model des Chat-Anfrage-Bodys setzen. Das ist die gesamte Konvention auf deiner Seite. Du musst keine anbieterspezifische URL konstruieren, kein SDK wechseln und die Struktur des Anfrage-Bodys nicht ändern.

Das Suffix @azure ist Routing-Metadaten und teilt HiAPI mit, welches Backend diese Variante des Modells für die Anfrage verwenden soll. Alles andere im Anfrage-Body – messages, temperature, max_tokens, stream, tools – bleibt die vertraute Standardstruktur für Chat-Completions. Das ist in der Praxis wichtig: Wenn du bereits eine funktionierende Anfrage für ein anderes Modell über HiAPI hast, erfordert die Umstellung auf gpt-5.6-terra@azure meist nur eine Zeile.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Zwei Gewohnheiten sorgen dafür, dass Bugs im Zusammenhang mit Modell-IDs selten auftreten:

• Behandle die ID als opaken String. Kopiere sie unverändert, einschließlich @ und kleingeschriebenem Suffix. Keine Leerzeichen, keine Änderung der Groß-/Kleinschreibung.
• Lege sie in der Konfiguration ab statt sie über den Code zu verteilen. Eine Konstante oder Umgebungsvariable macht A/B-Tests zwischen verschiedenen Modell-IDs zu einer Konfigurationsänderung statt zu einem Refactoring.

Da das Suffix das Routing übernimmt, solltest du allein aus der ID keine Rückschlüsse auf den zugrunde liegenden Technologie-Stack ziehen. Latenz, Limits und unterstützte Parameter sind Eigenschaften dessen, wie HiAPI das Modell bereitstellt. Verifiziere das Verhalten daher zuerst mit einer kleinen Anfrage, bevor du Annahmen in deine Anwendung schreibst.

Voraussetzungen und Bereitstellung des Schlüssels

Bevor du den ersten Aufruf machst, stelle drei Dinge sicher:

1. Ein HiAPI-Konto. Du musst dich anmelden, um Anmeldedaten zu erstellen und die aktuellen Modell- und Preisinformationen in der Konsole einzusehen.
2. Einen API-Schlüssel. Erzeuge ihn in der Konsole und bewahre ihn sicher auf – behandle ihn wie ein Passwort. Dieser Leitfaden geht nicht von einem bestimmten Schlüsselformat aus; jeder String, den dir die Konsole gibt, ist der Wert, den du in den Authorization-Header einfügst.
3. Einen HTTP-Client. Verwende curl für schnelle Verifikationen und Python 3 mit requests oder dem OpenAI-kompatiblen SDK für Anwendungscode.

Halte den Schlüssel von Quelldateien fern

Verwende Umgebungsvariablen. Das Muster ist auf jeder Plattform gleich:

export HIAPI_API_KEY="your-key-here"

Referenziere ihn dann zur Laufzeit. In der Shell: "$HIAPI_API_KEY". In Python: os.environ["HIAPI_API_KEY"]. In CI verwende den Secret-Speicher deines Anbieters statt eine .env-Datei einzuchecken.

Wenn du den Schlüssel zum Debuggen in das Terminal einfügst, denke daran, dass er in der Shell-Historie verbleiben kann – rotiere ihn später, falls es sich um echte Anmeldedaten handelt. Für die lokale Entwicklung ist ein einmaliger Testschlüssel, der nur für Tests verwendet wird, einfacher zu handhaben als die Wiederverwendung von Produktions-Anmeldedaten.

Bestätige deine Base-URL und deinen Endpunkt

HiAPI stellt einen OpenAI-kompatiblen Chat-Completions-Endpunkt bereit. Entnimm die Base-URL und den Pfad deiner Konsolendokumentation und halte sie in curl und Python konsistent – die meisten Berichte „curl funktioniert, aber Python nicht“ laufen letztlich auf einen abschließenden Schrägstrich oder ein fehlendes Pfadsegment hinaus.

Eine funktionierende curl-Anfrage

Hier ist der minimale korrekte Aufruf. Ersetze die Base-URL durch die in deiner Konsole angezeigte und stelle sicher, dass HIAPI_API_KEY exportiert ist.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Feld für Feld erklärt:

• -sS unterdrückt die Fortschrittsanzeige, zeigt aber weiterhin Fehler an. Wenn du Antwort-Header zusammen mit dem Antwort-Body sehen möchtest, füge -i hinzu.
• Authorization: Bearer $HIAPI_API_KEY authentifiziert die Anfrage. Das Präfix Bearer und das Leerzeichen sind erforderlich.
• Content-Type: application/json – wenn dies fehlt, lehnen viele Server den Body ab, bevor sie ihn überhaupt parsen.
• model – die exakte ID gpt-5.6-terra@azure.
• messages – ein geordnetes Array. system legt das Verhalten fest; user trägt den Prompt. Bei mehrstufigen Dialogen fügst du assistant- und user-Runden der Reihe nach hinzu.
• max_tokens – die Obergrenze für die Antwortlänge. Halte sie bei schnellen Verifikationen klein, damit Fehler kostengünstig und schnell sind.

Eine erfolgreiche Antwort ist JSON mit einem choices-Array; der benötigte Text befindet sich in choices[0].message.content. Formatiere die Ausgabe in den ersten Durchläufen mit einem JSON-Formatierer, damit du die Struktur siehst, statt dich mit einer langen Zeile abzumühen.

Sobald diese Anfrage funktioniert, speichere sie als Shell-Skript, das den Schlüssel aus einer Umgebungsvariable liest. Damit hast du einen wiederholbaren Health-Check, den du bei jeder Änderung der Modell-ID oder der Parameter ausführen kannst.

Die äquivalente Python-Anfrage

Der Anfrage-Body ist identisch – nur der Transportweg ändert sich. Verwende requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Drei Details, die es wert sind, beibehalten zu werden: Verwende json=payload statt manueller Serialisierung (es setzt Header und Kodierung für dich), setze immer ein timeout und rufe raise_for_status() auf, damit 4xx oder 5xx als Exception auftauchen, statt einen IndexError auszulösen, wenn du im Fehler-Antwort-Body indexierst.

SDK-Stil des Anbieters

Da der Endpunkt OpenAI-kompatibel ist, erzeugt ein SDK mit konfigurierter benutzerdefinierter Base-URL dieselbe Anfrage:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

Der Sinn, beide Varianten zu zeigen, liegt darin: Die Modell-ID ist die einzige Variable, die festlegt, welches Modell dich bedient. Alles andere ist die gewöhnliche Chat-Completions-Pipeline, sodass du zwischen rohem HTTP und SDK wechseln kannst, ohne die Logik neu zu schreiben.

Streaming und Tool-Aufrufe hinzufügen

Beide Funktionen sind inkrementell. Du schreibst die Basis-Anfrage nicht neu – du fügst Felder hinzu und änderst die Art, wie du die Antwort konsumierst.

Streaming

Setze "stream": true im Anfrage-Body:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Die Antwort wird zu einer Reihe von Server-Sent Events statt zu einem einzelnen JSON-Objekt. Jeder Chunk trägt ein delta mit einem Inhaltsfragment; beim ersten und letzten Chunk kann delta.content None sein, prüfe daher vor dem Zusammenfügen. Bei rohem HTTP gilt dasselbe – lies den Antwort-Body zeilenweise, entferne das Präfix data: , überspringe [DONE] und parse jede JSON-Zeile.

Tool-Aufrufe

Beschreibe die Tools in der Anfrage, damit das Modell entscheidet, wann es sie aufruft:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Wenn das Modell ein Tool aufrufen möchte, enthält choices[0].message ein tool_calls-Array statt reinem Text. Jeder Eintrag hat eine id und eine function, die name und arguments enthält (ein JSON-String, den du parsen musst). Führe deine Funktion aus und schicke das Ergebnis als Nachricht mit role: "tool" zurück, mit passender tool_call_id und der serialisierten Ausgabe – starte dann eine weitere Anfrage, um die endgültige Antwort zu erhalten.

tool_choice akzeptiert "auto" (das Modell entscheidet), "none" (nur Text) oder eine bestimmte Funktion. Streaming und Tools lassen sich kombinieren, aber die Argumente des Tool-Aufrufs treffen fragmentiert über mehrere Chunks ein, die du erst ansammeln und dann parsen musst – bringe zuerst den nicht gestreamten Tool-Aufruf zum Laufen.

Häufige Anfragefehler beheben

Debugge in der folgenden Reihenfolge; jeder Schritt isoliert eine Ebene, damit du nicht zwei Probleme gleichzeitig verfolgst.

1. Authentifizierung (401 / 403)

Die wahrscheinlichste Ursache: fehlender Schlüssel, verlorenes Präfix Bearer oder eine Umgebungsvariable, die sich zu einem leeren String expandiert. Gib aus, wie der Header konstruiert wird, ohne den vollständigen Schlüssel auszugeben, und stelle sicher, dass die Variable in derselben Shell oder demselben Prozess gesetzt ist, der die Anfrage ausführt.

2. Endpunkt und Pfad (404)

Ein 404 bedeutet normalerweise einen falschen Pfad – Tippfehler, fehlendes /v1 oder ein überflüssiger abschließender Schrägstrich an einer Stelle, an der er nicht hingehört. Kopiere die exakte URL aus der Konsole, statt sie neu einzutippen.

3. Modell-ID (400 mit modellbezogener Meldung)

Die ID muss exakt übereinstimmen: gpt-5.6-terra@azure. Häufige Fehler sind Änderungen der Groß-/Kleinschreibung, ein fehlendes @azure oder zusätzliche Leerzeichen durch Copy-Paste. Wenn die Meldung besagt, das Modell sei unbekannt, vergleiche den konfigurierten String Zeichen für Zeichen mit der Konsolenliste, bevor du einen Dienstausfall vermutest.

4. Fehlerhaft formatierter Anfrage-Body (400 / 422)

Wenn der Fehler den Anfrage-Body betrifft, prüfe zuerst die JSON-Gültigkeit – nachgestellte Kommas oder nicht maskierte Anführungszeichen sind häufige Ursachen. Prüfe dann die Feldnamen (es heißt messages, nicht message) und die Rollen (system, user, assistant, tool). max_tokens muss eine Zahl sein, tools muss ein korrekt strukturiertes Array von Objekten sein.

5. Streamende Antworten wie gewöhnliches JSON behandeln

Wenn die Ausgabe leer, unlesbar oder von einem Parse-Fehler begleitet ist, hast du wahrscheinlich stream: true angefordert, aber die Antwort wie ein einzelnes JSON-Dokument geparst. Lies sie als Event-Stream, überspringe [DONE] und sichere dich gegen None-Deltas ab.

6. Client-Timeouts

Lang andauernde Generierungen können das standardmäßige HTTP-Timeout überschreiten. Erhöhe es im Client explizit oder wechsle zu Streaming, damit die Bytes sofort eintreffen.

Checkliste zur schnellen Reproduktion

• Führe den minimalen curl-Aufruf aus. Wenn er erfolgreich ist, liegt das Problem in deinem Code.
• Wenn er fehlschlägt, versuche es in einer frischen Shell mit deinem Schlüssel und der Modell-ID erneut.
• Protokolliere sowohl den HTTP-Statuscode als auch den Antwort-Body – der Fehler-Antwort-Body enthält diagnostische Details.
• Erst wenn all diese Prüfungen bestanden sind, solltest du ein serverseitiges Problem in Betracht ziehen, das eine Eskalation rechtfertigt.

Mit einer funktionierenden Anfrage, der Streaming-Schleife und dieser Checkliste verhält sich gpt-5.6-terra@azure in deinem Stack wie jedes andere Chat-Modell – und der Modellwechsel wird zu einer einzeiligen Konfigurationsänderung.