Blog

Tutorial

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

Nov 12, 2026
Architektonisches Cover-Artwork mit warmgrauen Betonflächen, durchschnitten von einer schieferblauen schrägen Schattierung und einer dünnen salbeigrünen Naht.
Auf dieser Seite

Was vor dem ersten Aufruf vorbereitet sein muss

Bevor Sie eine Zeile Code schreiben, bereiten Sie drei Dinge vor. Der Rest dieses Tutorials baut darauf auf.

Ein HiAPI-API-Schlüssel

Jede Anfrage an die HiAPI API muss mit einem API-Schlüssel authentifiziert werden. Erstellen Sie einen Schlüssel in Ihrem HiAPI-Konto-Dashboard und bewahren Sie ihn sicher auf, am besten in einer Umgebungsvariablen statt in einer Quellcodedatei. Behandeln Sie ihn wie ein Passwort: Sobald er kompromittiert ist, rotieren Sie ihn sofort.

export HIAPI_API_KEY="your-api-key-here"

Der Basis-Endpunkt

Alle Aufrufe in dieser Anleitung gehen an den Basis-Endpunkt der HiAPI API; jedes Modell wird über dasselbe Request-Pfadformat erreicht. Sie benötigen weder einen eigenen Host noch ein SDK pro Modell – gpt-6-sol wird im Request-Body ausgewählt, nicht durch Ändern der Client-Einstellungen.

Ein HTTP-Client

Sie benötigen eines der folgenden:

  • curl, standardmäßig verfügbar auf den meisten Linux- und macOS-Systemen sowie in Windows-Terminals.
  • Python mit der Bibliothek requests (pip install requests) oder, wenn Sie keine Abhängigkeiten einführen möchten, die Standardbibliothek urllib.

Weitere Tools sind nicht erforderlich. Sie brauchen kein anbieterspezifisches SDK und müssen nichts Modellbezogenes installieren. Solange Sie eine HTTPS-POST-Anfrage mit JSON-Body und Headern senden können, können Sie gpt-6-sol aufrufen.

Eine Gewohnheit, die sich jetzt lohnt: Führen Sie eine Entwurfsdatei, in der Sie die funktionierende Anfrage festhalten, sodass Sie bei einem Fehlschlag den fehlgeschlagenen Aufruf mit dem letzten bekanntermaßen funktionierenden vergleichen können.

Authentifizierung mit einem Bearer-Schlüssel

Die Authentifizierung ist der fehleranfälligste Teil des ersten Aufrufs, daher lohnt es sich, sie sorgfältig zu behandeln.

Der Authorization-Header

Die HiAPI API erwartet Ihren Schlüssel im standardmäßigen Bearer-Header:

Authorization: Bearer $HIAPI_API_KEY

Also das wörtliche Wort Bearer, ein Leerzeichen und dann der Schlüssel. Häufige Fehler: das Wort Bearer weglassen, beim Kopieren des Werts einen überflüssigen Zeilenumbruch einschleppen oder den Schlüssel in Anführungszeichen setzen, obwohl der Client bereits Anführungszeichen hinzufügt.

Der Inhaltstyp muss JSON sein

Die Anfrage trägt einen JSON-Body, daher muss der Content-Type-Header dazu passen:

Content-Type: application/json

Fehlt dieser Header, parsen manche Server den Body trotzdem, aber Sie sollten sich nicht darauf verlassen – setzen Sie ihn explizit. Eine Nichtübereinstimmung des Inhaltstyps ist eine häufige Ursache für Anfragevalidierungsfehler, die wie Body-Fehler aussehen.

Minimaler Header-Satz

Sie benötigen nur die beiden oben genannten Header:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Halten Sie den Header-Satz so klein wie möglich. Spekulative Header, die aus Beispielen anderer APIs übernommen wurden, stiften eher Verwirrung, als zu helfen. Sobald ein Aufruf mit diesen beiden Headern gelingt, haben Sie eine saubere Basislinie für spätere Vergleiche.

Vermeiden Sie es, den Schlüssel direkt in die Shell-Historie oder in committete Dateien einzufügen. Indem Sie wie oben auf Umgebungsvariablen verweisen, halten Sie den Schlüssel aus Ihrem Quellcode und Ihrer Terminal-Historie heraus.

Den Request-Body für gpt-6-sol aufbauen

Der Request-Body ist JSON, dessen Kern eine Nachrichtenliste ist. Beginnen Sie mit der minimalen Konfiguration; fügen Sie Felder erst hinzu, nachdem der Aufruf erfolgreich war.

Minimaler Request-Payload

Der kleinste nützliche Request-Body muss das Modell angeben und eine Nachricht liefern:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Erkläre in einem Satz, was ein API-Bearer-Token ist." }
  ]
}

Zwei Felder kommen hier zum Tragen:

  • model wählt gpt-6-sol, sodass derselbe Endpunkt später auch andere Modelle bedienen kann.
  • messages ist eine geordnete Liste von Gesprächsrunden. Jeder Eintrag hat eine role (system, user oder assistant) und einen content-String.

Sichere Standardwerte und optionale Ergänzungen

Betrachten Sie model und messages als erforderlich. Alles andere ist optional und sollte bewusst hinzugefügt werden:

  • Eine system-Nachricht an erster Stelle in messages legt das Verhalten oder den Ton des Gesprächs fest. Dies ist eine normale Nachricht, kein separates Top-Level-Feld.
  • Bei Bedarf wird die Länge der Ausgabe über Parameter im Request-Body gesteuert. Fügen Sie sie nur hinzu, wenn die Standardausgabe für Ihren Anwendungsfall zu kurz oder zu lang ist.
  • Sampling-Parameter verändern die Form der Ausgabe, nicht ihre Gültigkeit. Vermeiden Sie es, sie beim Debuggen fehlgeschlagener Aufrufe zu ändern, da sie Authentifizierungs- oder Body-Strukturfehler nicht beheben.

Eine praktische Regel

Im Fehlerfall sollte der Request-Payload so nah wie möglich am minimalen Beispiel bleiben. Entfernen Sie optionale Felder eines nach dem anderen, bis der Aufruf gelingt, und fügen Sie sie dann wieder hinzu. So lässt sich das Problem schnell isolieren: Ein fehlerhafter Parameter ist leichter zu finden als ein fehlerhafter Parameter, der zwischen fünf guten verborgen ist.

Eine funktionierende Anfrage mit curl senden

Der folgende Befehl ist vollständig und kann direkt ausgeführt werden, sofern Ihr Schlüssel exportiert ist. Er verwendet einen Platzhalter-Endpunktpfad, der den oben beschriebenen HiAPI-API-Konventionen entspricht.

curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Erkläre in einem Satz, was ein API-Bearer-Token ist." }
    ]
  }'

Setzen Sie HIAPI_BASE_URL auf den Basis-Endpunkt aus Ihrem HiAPI-Dashboard. Die Flags sind wichtig:

  • -X POST legt die Methode fest; diese Aufrufe sind alle POST.
  • -H fügt jeden Header hinzu, einen pro Zeile.
  • -d liefert den JSON-Body. Einfache Anführungszeichen verhindern, dass er von der Shell interpoliert wird.
  • -sS hält die Ausgabe ruhig, zeigt aber Fehler weiterhin an – genau das, was beim Skripten benötigt wird.

Die Antwort lesen

Eine erfolgreiche Antwort ist JSON. Sie sehen normalerweise ein Top-Level-Objekt mit dem Modellnamen und einer Liste von Choices, wobei jede Choice eine Nachricht hat, deren content den generierten Text enthält. Lesen Sie zuerst die Struktur und dann den Inhalt: Stellen Sie sicher, dass das Objekt parsebar ist, und lokalisieren Sie dann das content-Feld.

Für bessere Lesbarkeit können Sie die Ausgabe an einen JSON-Formatierer weiterleiten:

... | python -m json.tool

Wenn Ihr Terminal stattdessen ein Fehlerobjekt ausgibt, war der Aufruf nicht erfolgreich – springen Sie zum Fehlerabschnitt, anstatt den Prompt anzupassen. Wenn die Anfrage das Modell gar nicht erreicht hat, liegt das Problem nicht am Prompt.

Dieselbe Anfrage mit Python senden

Der Request-Payload, den Sie gerade mit curl verifiziert haben, lässt sich direkt übertragen. Halten Sie den Body identisch, damit die im Terminal verifizierten Korrekturen auch im Code greifen.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-6-sol",
    "messages": [
        {"role": "user", "content": "Erkläre in einem Satz, was ein API-Bearer-Token ist."}
    ],
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    timeout=60,
)

response.raise_for_status()
data = response.json()

for choice in data.get("choices", []):
    message = choice.get("message", {})
    print(message.get("content", ""))

Warum diese Version in Anwendungscode sicherer ist

  • Der Body ist ein Dictionary. Wenn Sie json=payload übergeben, serialisiert requests ihn und setzt den Inhaltstyp für Sie; das Beibehalten expliziter Header vermeidet jedoch Überraschungen beim Wechsel des Clients.
  • Der Schlüssel stammt aus einer Umgebungsvariablen. Kein Geheimnis ist hartkodiert, sodass die Datei committet werden kann.
  • raise_for_status() wird zuerst ausgeführt. Nicht-2xx-Antworten lösen sofort eine Exception aus, bevor Sie versuchen, Felder zu lesen, die im Fehler-Body nicht existieren.
  • Ein Timeout ist gesetzt. Ohne Timeout kann eine hängende Verbindung einen Worker-Prozess unbegrenzt blockieren.

Die Schleife über choices schützt zudem vor fehlenden Schlüsseln, sodass das Beispiel auch Antworten mit wenig oder gar keiner Ausgabe toleriert. Bauen Sie Ihren Produktions-Wrapper um dieses Gerüst: validieren, senden, Status prüfen, dann parsen.

Antworten streamen statt warten

Standardmäßig gibt die API die vollständige Antwort in einer einzigen JSON-Antwort zurück. Bei langen Ausgaben oder interaktiven Oberflächen können Sie stattdessen anfordern, die Antwort während der Generierung schrittweise zu liefern.

Der Streaming-Schalter

Streaming wird über ein Flag im Request-Body aktiviert, nicht über einen anderen Endpunkt:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Schreibe einen kurzen Text über HTTP-Statuscodes." }
  ],
  "stream": true
}

Fügen Sie dieses Flag erst hinzu, nachdem ein nicht-streamender Aufruf bereits funktioniert. Es ändert die Organisation der Antwort, nicht die Gültigkeit der Anfrage.

Inkrementelle Ausgabe konsumieren

Mit aktiviertem Streaming ist die Antwort kein einzelnes JSON-Dokument mehr. Sie kommt als Folge von Ereignissen an, üblicherweise zeilengetrennt, wobei jedes Ereignis ein kleines Stück Ausgabe trägt. Ihr Client muss sie beim Eintreffen lesen, statt .json() auf den gesamten Antwort-Body anzuwenden.

with requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

Im Terminal verhält sich derselbe Schalter anders als bei einem nicht-streamenden Aufruf: Die Ausgabe erscheint schrittweise, sodass eine abgeschnittene Pipe wie eine fehlgeschlagene Anfrage aussehen kann, obwohl tatsächlich nur der Stream unterbrochen wurde.

Welche Variante wählen

Für Batch-Aufgaben, Tests und alle Fälle, in denen Sie das vollständige Objekt auf einmal benötigen, verwenden Sie Nicht-Streaming. Wenn jemand auf Text wartet oder die Ausgabe so lang ist, dass die Latenz spürbar wird, verwenden Sie Streaming. Behalten Sie beide Pfade in Ihrer Codebasis, denn der nicht-streamende Pfad ist leichter zu debuggen.

Häufige Fehlercodes lesen und beheben

Diagnostizieren Sie zuerst anhand des Statuscodes, dann anhand des Antwort-Bodys. Ändern Sie weder das Modell noch schreiben Sie den Prompt neu, bevor Sie sicher sind, welche Ebene fehlschlägt.

401 Unauthorized

Ursache: Schlüssel fehlt, ist falsch formatiert oder wurde widerrufen. Behebung: Vergewissern Sie sich, dass der Header exakt Authorization: Bearer <key> lautet, prüfen Sie auf versteckte Leerzeichen oder veraltete Umgebungsvariablen und stellen Sie sicher, dass der Schlüssel in Ihrem Dashboard noch gültig ist. Geben Sie die Länge der Variablen statt ihres Werts aus, um Fehler durch leere Variablen zu erkennen.

400 Bad Request

Ursache: Der Request-Body ist nicht parsebar oder es fehlen erforderliche Felder. Behebung: Senden Sie erneut den minimalen Request-Payload, nur mit model und messages. Validieren Sie das JSON vor dem Senden mit python -m json.tool; nachfolgende Kommas oder ein Tippfehler in model sind häufige Ursachen. Stellen Sie sicher, dass Content-Type auf application/json steht.

403 Forbidden

Ursache: Der Schlüssel ist gültig, aber es fehlt die Berechtigung für die angeforderte Ressource. Behebung: Prüfen Sie, ob Ihr Konto Zugriff auf gpt-6-sol hat und ob der Modellname im Request-Body mit dem übereinstimmt, was für Ihr Konto konfiguriert ist.

404 Not Found

Ursache: Falscher URL-Pfad, meist ein Tippfehler im Endpunkt oder ein fehlender bzw. doppelter Basispfad. Behebung: Vergleichen Sie die vollständige URL Zeichen für Zeichen mit dem funktionierenden curl-Aufruf.

429 Too Many Requests

Ursache: Sie senden Anfragen schneller, als Ihr Konto es erlaubt. Behebung: Warten Sie ab (Backoff) und wiederholen Sie mit zunehmender Verzögerung. Befolgen Sie etwaige Retry-Hinweise in den Response-Headern und wiederholen Sie niemals in einer engen Schleife – das verschlimmert das Problem. Unterscheiden Sie dies von 5xx, das ein serverseitiges Problem statt Ihrer Anfrage-Rate anzeigt.

5xx Serverfehler

Ursache: Der Dienst kann eine an sich gültige Anfrage nicht verarbeiten. Behebung: Wiederholen Sie mit Backoff; besteht das Problem weiter, erfassen Sie den Antwort-Body und die Request-ID, und vermeiden Sie es, den Request-Payload zu ändern, da er bereits funktioniert.

Wiederholbare Debug-Reihenfolge

  1. Statuscode – handelt es sich um ein Authentifizierungs-, Pfad- oder Body-Problem?
  2. Antwort-Body – wird darin auf ein problematisches Feld hingewiesen?
  3. Struktur des Request-Payloads – zum minimalen Beispiel zurückkehren.
  4. Erst zuletzt Prompt oder Parameter in Betracht ziehen.

Diese Reihenfolge verkürzt die Zeit vom Fehler bis zur Behebung dauerhaft. Sobald Ihre Aufrufe stabil sind, halten Sie die funktionierende curl- und Python-Version nebeneinander, sodass jeder künftige Test von einem bekanntermaßen funktionierenden Zustand ausgeht.

Ä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