So verwenden Sie gpt-6.1-terra über die HiAPI-API: curl, Python und eine funktionierende Anfrage

Was ein gpt-6.1-terra-Aufruf wirklich benötigt

Jeder Aufruf von gpt-6.1-terra auf HiAPI reduziert sich auf vier Dinge: eine URL, einen Authentifizierungs-Header, den Modellbezeichner und den Anfragetext. Wenn diese korrekt sind, ist der Rest dieses Artikels nur noch die Art und Weise, wie die Pipeline angeschlossen wird.

Der Endpunkt

Alle Modellaufrufe werden über dieselbe Basis-URL auf HiAPI ausgelöst. Sie müssen nicht für jedes Modell den Host wechseln – der Modellname im Anfragetext bestimmt, wohin die Anfrage geroutet wird. Richten Sie Ihren Client auf die HiAPI-Basis-URL und speichern Sie sie in einer Variable, sodass Sie nur an einer Stelle ändern müssen.

Der Authentifizierungs-Header

Die Authentifizierung erfolgt über ein Bearer-Token im Authorization-Header. Dieses Token ist ein API-Schlüssel, der in Ihrem HiAPI-Konto ausgestellt wird. Hardcodieren Sie ihn niemals in Quelldateien; lesen Sie ihn aus einer Umgebungsvariable (z. B. HIAPI_API_KEY), sodass derselbe Code lokal, in CI und in der Produktion funktioniert.

Der Modellbezeichner

Der Anfragetext muss das Modell explizit angeben: "model": "gpt-6.1-terra". Die Zeichenfolge ist case-sensitiv und muss exakt übereinstimmen. Ein falscher oder abgeschnittener Modellname ist eine der häufigsten Ursachen für abgelehnte Anfragen, daher sollte er als Konstante im Code behandelt werden, nicht als nebenbei getippte Zeichenfolge.

Felder im Anfragetext

Eine Anfrage enthält mindestens das Modell und den Eingabeinhalt – also den Prompt oder die Nachrichten, die das Modell verarbeiten soll. Auf dieser Grundlage können Sie beliebige vom Modell unterstützte optionale Parameter hinzufügen (Hinweise zum Ausgabeformat, Längensteuerung usw.), aber beginnen Sie mit dem minimalen Anfragetext, der eine gültige Antwort erzeugt. Ein minimaler Anfragetext lässt sich leichter debuggen als ein voll ausgestatteter und hilft Ihnen festzustellen, ob der Fehler in Ihrem Anfragetext oder in der Art und Weise liegt, wie die Pipeline angeschlossen ist.

Ein struktureller Punkt, den es sich früh zu verinnerlichen lohnt: Manche Antworten werden inline zurückgegeben, andere als Aufgaben, die Sie pollen müssen. Wie man beide unterscheidet, wird weiter unten erläutert, aber entwerfen Sie Ihre Anforderungsschicht jetzt so, dass die Antwortverarbeitung zwischen beiden Modi wechseln kann, ohne neu geschrieben werden zu müssen.

Eine funktionierende curl-Anfrage, Zeile für Zeile erklärt

Das folgende ist ein vollständiges Aufrufbeispiel, das Sie nach dem Exportieren des Schlüssels direkt in ein Terminal einfügen und ausführen können. Es verwendet die HiAPI-Basis-URL und einen minimalen JSON-Anfragetext.

curl -sS -X POST "$HIAPI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-terra",
    "messages": [
      {"role": "user", "content": "Fasse den Wasserkreislauf in drei Sätzen zusammen."}
    ]
  }'

Was jedes Flag bewirkt

-X POST legt die HTTP-Methode fest. Modellaufrufe sind POST, weil sie einen Anfragetext mitbringen.

-sS lässt curl Fortschrittsinformationen ausblenden, zeigt aber echte Fehler an. Ohne -S könnte eine fehlgeschlagene Anfrage wie bloßes Schweigen aussehen.

-H "Authorization: Bearer $HIAPI_API_KEY" fügt Ihre Anmeldeinformationen hinzu. Das Präfix Bearer und das einzelne Leerzeichen danach sind Teil des Authentifizierungsschemas; fehlt eines von beiden, schlägt die Authentifizierung fehl, und es sieht so aus, als hätte es nichts mit dem Header zu tun.

-H "Content-Type: application/json" teilt dem Server mit, dass der Anfragetext JSON ist. Manche Gateways tolerieren einen fehlenden Content-Type, aber verlassen Sie sich nicht darauf.

-d '...' ist der Anfragetext. Einfache Anführungszeichen verhindern, dass die Shell das JSON interpoliert. Wenn Sie stattdessen eine Datei verwenden möchten, ersetzen Sie -d '...' durch -d @payload.json und legen Sie das JSON in einer Datei ab, die gelintet und gediffed werden kann.

Zwei Gewohnheiten, die Zeit sparen

Erstens: Fügen Sie bei Fehlern -i hinzu, um die Antwortstatuszeile und die Antwort-Header auszugeben. Eine Antwort mit dem Status 200, aber einem anomalen Antworttext, wird ganz anders gelesen als ein 401 oder 422, und Sie möchten diesen Unterschied sofort sehen. Zweitens: Leiten Sie die Ausgabe durch einen JSON-Formatierer (curl ... | python -m json.tool), damit verschachtelte Antwortfelder lesbar sind. Beide Flags sind nebenwirkungsfrei und Sie werden sie beim Anpassen von Aufrufen häufig brauchen.

Den Aufruf nach Python portieren

Die Python-Version sollte die exakte Semantik des curl-Aufrufs beibehalten: dieselbe URL, dieselben Header, derselbe Anfragetext, dieselbe Art der Verarbeitung. Die Verwendung der Standardbibliothek hält die Abhängigkeiten bei null und macht die Portierung offensichtlich.

import json
import os
import urllib.request

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]

def call_terra(prompt: str, model: str = "gpt-6.1-terra") -> dict:
    body = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
    }
    req = urllib.request.Request(
        f"{HIAPI_BASE_URL}/v1/chat/completions",
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.loads(resp.read().decode("utf-8"))

result = call_terra("Fasse den Wasserkreislauf in drei Sätzen zusammen.")
print(json.dumps(result, indent=2))

Hinweise zur Portierung

Die Header werden einmalig innerhalb des Request-Objekts aufgebaut und entsprechen den beiden -H-Flags. Der Anfragetext ist ein Python-dict, das mit json.dumps serialisiert wird; dies ist programmatisch äquivalent zum in einfache Anführungszeichen gesetzten curl-Anfragetext – und es beseitigt Anführungszeichenprobleme auf Windows-Shells.

Die Funktion nimmt das Modell als Parameter mit Standardwert an, statt das Literal überall zu wiederholen. Dadurch gibt es eine einzige Quelle der Wahrheit für den Modellnamen und Sie können ihn dennoch bewusst überschreiben.

Die Fehlerbehandlung ist hier bewusst weggelassen, um den normalen Pfad lesbar zu halten. In echtem Code sollten Sie den urlopen-Aufruf umschließen und HTTP-Fehlerausnahmen abfangen sowie .read() vom Fehlerobjekt lesen, um die Servermeldung zu sehen. Der Timeout wird explizit gesetzt; unendliches Blockieren hängt schließlich einen Worker auf.

Wenn Sie httpx oder requests bevorzugen, ist die Zuordnung eins zu eins: requests.post(url, headers=..., json=body, timeout=120). Der Parameter json= serialisiert das dict für Sie. Die Semantik ändert sich in keiner Weise, und genau das ist der Punkt – der curl-Aufruf ist der Vertrag, Python ist nur seine zweite Darstellungsform.

Zwischen Einzelaufruf und asynchroner Aufgabe entscheiden

Nicht jede Anfrage eignet sich zum Warten. Die Entscheidung hängt davon ab, wie lange die Arbeit dauert und ob der Aufrufer Blockieren verkraften kann.

Wann ein Einzelaufruf geeignet ist

Kurze interaktive Anfragen – Zusammenfassungen, Klassifizierungen, kleine Umschreibungen – sollten gewöhnliche synchrone Aufrufe sein. Die Antwort wird inline zurückgegeben, Sie parsen sie und geben zurück. Dies ist der einfachste Codepfad und am leichtesten in Tests nachzuvollziehen. Wenn ein Benutzer in einer UI wartet, ist synchron die erwartete Form.

Wann es als Aufgabe behandelt werden sollte

Wenn die Arbeit lange läuft oder große Artefakte erzeugt und eine unterbrochene Verbindung bedeutet, dass teure Arbeit wiederholt werden muss, sollten Sie den Aufruf als asynchron behandeln. In diesen Fällen senden Sie die Anfrage ab, erhalten einen Aufgabenbezeichner und pollen dann, bis sie einen Endzustand erreicht. Die Übermittlung selbst kehrt schnell zurück, sodass Ihr Worker oder HTTP-Handler nicht während des gesamten Prozesses belegt ist.

Eine praktische Regel: Wenn Sie sich dabei ertappen, einen außergewöhnlich langen Client-Timeout festzulegen, damit „der Aufruf erfolgreich ist“, ist das das Signal, zu Aufgaben zu wechseln. Ein Timeout ist kein Planungsmechanismus.

Den Wechsel kostengünstig gestalten

Spalten Sie Ihre Codebasis nicht in zwei unzusammenhängende Clients auf. Kapseln Sie beide Pfade hinter einer Funktion, die entweder ein sofortiges Ergebnis oder ein Aufgabenhandle zurückgibt, und lassen Sie den Aufrufer den gewünschten Modus anfordern. So bleibt die Anforderungskonstruktion – Modell, Authentifizierung, Anfragetext – gemeinsam genutzt und nur die Wartestrategie unterscheidet sich. Das bedeutet auch, dass das Debuggen konsistent ist: Bei einem kleinen Anfragetext können Sie einen asynchronen Fehler synchron reproduzieren.

Seien Sie ehrlich zu Ihrer eigenen Arbeitslast, statt das Plattformverhalten zu raten. Wenn Ihre Anfragen normalerweise in wenigen Sekunden abgeschlossen sind, bleiben Sie synchron und überspringen Sie die Komplexität. Der Wert des asynchronen Pfads zeigt sich bei wirklich langsamen Anfragen, nicht bei allen.

Den Abschlussstatus abfragen, ohne die API zu überlasten

Eine Polling-Schleife hat drei Aufgaben: lange genug warten, um höflich zu sein, schließlich aufhören und den Endzustand klar darstellen. Das Folgende ist eine kompakte Version.

import time

def poll_until_done(fetch_status, job_id, interval=3.0, timeout=600.0):
    deadline = time.monotonic() + timeout
    while True:
        status = fetch_status(job_id)
        state = status.get("status")
        if state in ("succeeded", "failed", "cancelled"):
            return status
        if time.monotonic() > deadline:
            raise TimeoutError(f"job {job_id} not finished after {timeout}s")
        time.sleep(interval)

Warum diese Struktur

fetch_status wird injiziert, sodass dieselbe Schleife funktioniert, egal ob Sie per HTTP oder gegen eine interne Warteschlange pollen. Das macht es auch trivial, mit einem Fake-Objekt zu testen, das zweimal running und dann succeeded zurückgibt.

Die Statusprüfung ist eine explizite Whitelist von Endzuständen statt der Prüfung auf eine einzelne Zeichenfolge „done“. Endzustände sind unterschiedlich – Erfolg, Fehlschlag, Abbruch – und Sie möchten bei jedem davon anhalten, statt bis zum Timeout zu drehen, weil Sie nur nach einem Status gesucht haben.

Die Deadline verwendet time.monotonic(), damit Änderungen der Wanduhr die Wartezeit nicht versehentlich verlängern oder verkürzen.

Das Polling-Intervall wählen

Beginnen Sie mit einigen Sekunden und widerstehen Sie dem Impuls zu straff zu pollen. Sub-Sekunden-Intervalle verbrauchen das Anfragebudget und erhöhen die Last, ohne die Aufgabe schneller abzuschließen. Wenn Sie lange Aufgaben erwarten, ziehen Sie ein sanftes Backoff in Betracht – z. B. das Intervall nach jeder Prüfung bis zu einer Obergrenze erhöhen. Halten Sie die Obergrenze moderat; das Ziel ist, Anfragen zu reduzieren, nicht minutenlange Blindflüge zu erzeugen.

Timeouts sind nicht optional

Legen Sie immer einen Timeout fest, im Verhältnis zur Arbeit großzügig, aber begrenzt. Wenn er ausgelöst wird, geben Sie nicht stillschweigend ein leeres Ergebnis zurück. Werfen Sie eine Ausnahme, protokollieren Sie den Aufgabenbezeichner und lassen Sie den Aufrufer entscheiden, ob er es erneut versucht – eine Aufgabe, bei der das Polling in einen Timeout läuft, kann noch laufen, und blindes erneutes Senden kann Arbeit duplizieren.

Ausgaben herunterladen und speichern

Wenn die Antwort Artefaktverweise enthält – URLs, Dateibezeichner oder Speicherschlüssel –, behandeln Sie diese als flüchtig. Sie können ablaufen, auf Ihr Konto beschränkt sein und nach einem erneuten Versuch möglicherweise nicht mehr gültig sein. Die dauerhafte Kopie ist die, die Sie selbst speichern.

Das Muster Abrufen und Persistieren

Wenn eine Aufgabe abgeschlossen ist, lesen Sie den Artefaktverweis aus dem Endzustand, rufen Sie ihn einmal ab und schreiben Sie ihn an ein Ziel, das Sie kontrollieren: einen lokalen Pfad für Skripte, einen Objektspeicher-Bucket für alles, was der Produktion nahekommt. Protokollieren Sie den Aufgabenbezeichner zusammen mit der gespeicherten Datei, sodass Sie das Artefakt bis zur Anfrage zurückverfolgen können, die es erzeugt hat.

def save_output(fetch_bytes, artifact_url, dest_path):
    data = fetch_bytes(artifact_url)
    with open(dest_path, "wb") as f:
        f.write(data)
    return dest_path

Praktiken gegen stillen Datenverlust

Schreiben Sie in einen temporären Pfad und benennen Sie nach Erfolg um, sodass ein fehlgeschlagener Download niemals eine gültig aussehende, aber nur halb geschriebene Datei hinterlässt. Wenn die Antwort eine Byteanzahl oder Prüfsumme bereitstellt, überprüfen Sie sie. Schreiben Sie bei großen Dateien auf die Festplatte, statt die gesamte Nutzlast in den Speicher zu laden.

Bewahren Sie außerdem die Rohantwort des letzten Statusaufrufs auf. Das Speichern von JSON ist kostengünstig, und wenn jemand fragt, warum eine Datei falsch aussieht, ist das Statusdokument mit Modellname, Zeitstempel und Aufgaben-ID der schnellste Weg, den Ablauf zu rekonstruieren.

Trennen Sie schließlich den Abruf von der Verarbeitung. Laden Sie zuerst herunter, speichern Sie, und wandeln Sie dann um. Wenn Sie während des Downloads parsen, sieht ein kurzer Netzwerkfehler wie ein Formatierungsfehler aus, und Sie verbringen einen Nachmittag damit, das falsche Problem zu lösen.

Häufige Fehler debuggen

Die meisten Fehler fallen in vier Kategorien. Für jede gibt es einen schnellen isolierten Test.

Authentifizierungsfehler

Symptom: 401 oder 403, bevor irgendetwas in Ihrem Anfragetext wichtig wird. Prüfen Sie, ob der Schlüssel tatsächlich geladen ist – geben Sie aus, ob die Umgebungsvariable gesetzt ist, nicht ihren Wert. Verifizieren Sie das Präfix Bearer und das Leerzeichen danach. Bestätigen Sie, dass der Header-Name korrekt geschrieben ist und dass kein Proxy ihn entfernt. Wenn derselbe Schlüssel in curl funktioniert, aber in Ihrer Anwendung nicht, konstruiert Ihre Anwendung den Header anders; vergleichen Sie das wörtliche Header-dict mit den curl-Flags.

Fehlerhaftes Anfragetextformat

Symptom: 400 oder 422 mit einer Meldung zum Anfragetext. Validieren Sie Ihr JSON vor dem Senden – json.dumps serialisiert fast alles, einschließlich dicts, die Sie nicht erstellen wollten. Prüfen Sie auf nachgestellte Kommas aus kopierten Konfigurationsdateien, Inhalte, die eine Liste sein sollten, aber als Zeichenfolge übergeben wurden, und fehlende Pflichtfelder. Reduzieren Sie auf den minimalen Anfragetext aus dem ersten Abschnitt und fügen Sie Felder einzeln hinzu, bis es fehlschlägt.

Falscher Modellname

Symptom: Ablehnung, die wie eine fehlerhafte Anfrage oder eine Meldung „Modell nicht gefunden“ aussieht. Die Modellzeichenfolge muss exakt gpt-6.1-terra sein. Häufige Ursachen: veraltete Standardwerte in Hilfsfunktionen, Umgebungsvariablen mit einem anderen Wert oder Tippfehler durch erneutes Tippen statt Kopieren und Einfügen. Halten Sie ihn als Modulkonstante und suchen Sie per grep nach Duplikaten.

Polling-Timeout

Symptom: Ihre Schleife endet mit einem Timeout, während die Aufgabe noch lebt. Bestätigen Sie zuerst, dass der Aufgabenbezeichner, den Sie pollen, derjenige ist, den Sie übermittelt haben – beide beim Übermitteln auszugeben ist die einfachste Prüfung. Prüfen Sie dann Ihre Liste der Endzustände: Ein Status, den Sie nicht erwartet haben, lässt die Schleife ewig laufen. Prüfen Sie schließlich, ob Ihr Intervall und Ihre Deadline zur tatsächlichen Aufgabendauer passen; eine Deadline, die für kurze Anfragen ausgelegt ist, wird bei langen Anfragen immer ausgelöst. Protokollieren Sie bei einem Timeout die letzte Statusnutzlast, damit Sie wissen, in welchem Zustand die Aufgabe war, als Sie aufgegeben haben.

Gehen Sie diese in der Reihenfolge Auth, Anfragetext, Modell, Polling durch – denn jede Schicht verdeckt die darunter. Ein kaputter Header lässt jeden Anfragetext falsch aussehen.