Blog

Tutorial

So rufen Sie claude-opus-5-5@aws über die HiAPI API auf: curl- und Python-Leitfaden

Nov 12, 2026
Cover-Artwork aus mintgrünen Halbtonpunkten, deren Dichte auf einem fast schwarzen Hintergrund mit tiefen Teal-Akzenten abnimmt.
Auf dieser Seite

So sieht die Nutzung von claude-opus-5-5@aws über HiAPI aus

HiAPI bietet eine einheitliche HTTP-Schnittstelle für viele Modelle. Sie müssen nicht für jeden Anbieter separat Konten, SDKs und Credential-Speicher konfigurieren, sondern richten sich mit demselben Anfragetyp an HiAPI und wählen das gewünschte Modell über einen Modellbezeichner aus. In diesem Tutorial lautet dieser Bezeichner claude-opus-5-5@aws – das Suffix @aws ist Teil des Modellnamens und kein eigenständiges Feld; es muss unverändert übergeben werden.

Der Lebenszyklus einer Anfrage sieht so aus:

  1. Authentifizierung – senden Sie Ihren HiAPI-API-Schlüssel als Bearer-Token im Header Authorization.
  2. Chat-ähnliche Nutzlast senden – ein JSON-Anfragetext mit dem Array model und messages, wobei jede Nachricht role (system, user oder assistant) und content enthält.
  3. JSON-Antwort empfangen – die Antwort des Assistenten erscheint im Array choices der Antwort, zusammen mit Nutzungsmetadaten.
  4. Unterhaltung fortsetzen – hängen Sie die Assistentennachricht und Ihre nächste Benutzernachricht an dasselbe Array messages an und senden Sie erneut. Die API ist zustandslos; die vollständige Unterhaltung liegt in Ihrer Anfragenutzlast.

Da die Anfragestruktur bei allen Modellen gleich ist, lässt sich Code, den Sie für claude-opus-5-5@aws schreiben, auf andere Modelle übertragen, indem Sie nur die Zeichenkette model ändern. Halten Sie dieses Feld an einer Stelle im Code zentral – etwa als Konfigurationswert oder Umgebungsvariable – und nicht in mehreren Dateien fest verdrahtet.

Ein Hinweis zur Benennung: Die Plattform dokumentiert das Modell als claude-opus-5-5@aws. Verwenden Sie genau diese Zeichenkette. Tippfehler, zusätzliche Leerzeichen oder ein fehlendes Suffix führen zu einem Fehler der Art „Modell nicht gefunden“ und nicht zu einer hilfreichen Warnung.

Zugangsdaten beschaffen und Authentifizierung einrichten

Bevor Sie die API aufrufen, benötigen Sie einen API-Schlüssel von Ihrem HiAPI-Konto. Behandeln Sie diesen Schlüssel als vertraulich: Speichern Sie ihn in einer Umgebungsvariable oder im Secret-Manager der Plattform und niemals in der Versionsverwaltung oder in Client-Code, der an den Browser ausgeliefert wird.

HiAPI authentifiziert Anfragen über einen Bearer-Token im Header Authorization:

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

Jede Anfrage muss enthalten:

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

Die folgenden praktischen Regeln vermeiden die meisten Authentifizierungsfehler:

  • Behalten Sie das Literal Bearer mit nachfolgendem Leerzeichen und dann den Schlüssel bei. Ein fehlendes Präfix oder Leerzeichen ist ein häufiger Copy-and-Paste-Fehler.
  • Setzen Sie den Schlüssel im Header-Wert nicht in Anführungszeichen.
  • Wenn Sie den Schlüssel rotieren, aktualisieren Sie die Umgebungsvariable und starten Sie den Prozess neu – lang laufende Worker speichern oft den alten Wert zwischen.
  • Prüfen Sie beim Einfügen des Schlüssels in eine .env-Datei auf nachgestellte Leerzeichen oder Zeilenumbrüche; einige Loader entfernen diese nicht automatisch.

Wenn der Schlüssel fehlt oder falsch formatiert ist, erhalten Sie einen Authentifizierungsfehler (Klasse 401) und keinen Modellfehler. Das macht ihn leicht von späteren Problemen unterscheidbar. Sobald eine Anfrage die Authentifizierung erfolgreich passiert hat, lässt sich derselbe Header für Streaming, Tool-Calling und alle anderen Muster in diesem Leitfaden verwenden – Sie benötigen für die einzelnen Funktionen keine unterschiedlichen Zugangsdaten.

Laden Sie für Servercode den Schlüssel einmal beim Start und übergeben Sie ihn an einen gemeinsamen Client oder eine kleine Wrapper-Funktion. So bleibt das Geheimnis an einer Stelle zentral und der Wechsel zwischen Entwicklungs- und Produktionszugangsdaten ist ein Leichtes.

Eine lauffähige Anfrage mit curl erstellen

Das Folgende ist eine vollständige, lauffähige Anfrage. Ersetzen Sie den Platzhalterschlüssel durch Ihren eigenen Schlüssel, oder führen Sie zuerst das export aus dem vorigen Abschnitt aus, damit die Shell die Ersetzung vornimmt.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5@aws",
    "messages": [
      {
        "role": "user",
        "content": "Erkläre in drei Sätzen, warum idempotente POST-Endpunkte für Zahlungs-APIs wichtig sind."
      }
    ]
  }'

Punkt für Punkt aufgeschlüsselt:

  • Endpunkt – POST https://api.hiapi.ai/v1/chat/completions.
  • Header – Bearer-Token und JSON-Inhaltstyp. Beide sind erforderlich.
  • model – der exakte Bezeichner claude-opus-5-5@aws.
  • messages – ein Array aus Role- und Content-Objekten. Die letzte Benutzernachricht ist das, worauf das Modell antworten soll.
  • Nutzlast – -d sendet rohes JSON, daher ist die Handhabung von Anführungszeichen wichtig. Schließen Sie den gesamten Anfragetext in der Shell in einfache Anführungszeichen ein und verwenden Sie doppelte Anführungszeichen für die JSON-Schlüssel.

Die Antwort ist ein JSON mit einem Array choices. Der generierte Text liegt in choices[0].message.content und enthält Nutzungsinformationen (Token-Zählungen), damit Sie den Verbrauch überwachen können. Die Antwortnutzung wird pro Token abgerechnet; die aktuellen Tarife finden Sie im Preispaneel der Website.

Häufige Anpassungen:

{
  "model": "claude-opus-5-5@aws",
  "max_tokens": 512,
  "temperature": 0.2,
  "messages": [
    {"role": "system", "content": "Du bist ein prägnanter technischer Redakteur."},
    {"role": "user", "content": "Fasse den obigen Anfragetext in einer Zeile zusammen."}
  ]
}

Mit max_tokens begrenzen Sie ausufernde Generierungen, mit temperature steuern Sie Ausführlichkeit und Varianz, und mit einer system-Nachricht legen Sie das Verhalten einmal pro Unterhaltung fest. Die system-Nachricht gehört in dasselbe Array messages, vor den Benutzerrunden.

Dieselbe Anfrage in Python

Die Python-Version nutzt urllib aus der Standardbibliothek, sodass das Snippet ohne Installation von irgendetwas lauffähig ist. Wenn Sie eine Client-Bibliothek bevorzugen, ist die Anfragestruktur völlig identisch – nur der Transportweg unterscheidet sich.

import json
import os
import urllib.request

API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"

def ask(user_message: str, system_message: str | None = None) -> str:
    messages = []
    if system_message:
        messages.append({"role": "system", "content": system_message})
    messages.append({"role": "user", "content": user_message})

    payload = json.dumps({
        "model": MODEL,
        "messages": messages,
    }).encode("utf-8")

    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        body = json.loads(response.read().decode("utf-8"))

    return body["choices"][0]["message"]["content"]

if __name__ == "__main__":
    print(ask("Begrüße mich mit genau fünf Wörtern."))

Warum es sich lohnt, diese Struktur beizubehalten:

  • MODEL und API_URL sind Konstanten auf Modulebene, sodass der Wechsel von Modell oder Endpunkt nur eine Zeile erfordert.
  • Der Schlüssel stammt aus der Umgebung; die Funktion akzeptiert niemals einen Parameter mit einem rohen Geheimnis.
  • Die Parsing-Logik ist am Ende isoliert, sodass Sie urllib durch httpx oder requests ersetzen können, ohne die Art des Aufbaus der Unterhaltung zu ändern.

Um eine mehrstufige Unterhaltung fortzusetzen, hängen Sie vor dem erneuten Senden die Antwort des Assistenten und die nächste Benutzernachricht an messages an. Lassen Sie das Array wachsen, bis Sie das Kontextlimit erreichen, und fassen Sie dann frühere Runden in einer system-Nachricht zusammen, um im Budget zu bleiben. Die Nutzung in der Antwort basiert auf Tokens; die aktuellen Tarife sind im Preispaneel der Website aufgeführt.

Streaming-Antworten für interaktive Szenarien

Für Chat-UIs und lang laufende Generierungen sendet Streaming Teilinhalte, sobald sie entstehen, anstatt auf die vollständige Antwort zu warten. Der Anfragetext bleibt bis auf ein Feld unverändert:

{
  "model": "claude-opus-5-5@aws",
  "messages": [{"role": "user", "content": "Schreibe einen kurzen Changelog-Eintrag für eine Bibliothek, die gerade Streaming eingeführt hat."}],
  "stream": true
}

Bei stream: true antwortet der Endpunkt mit Server-Sent Events: Jeder Block ist eine Zeile mit dem Präfix data: , und der Stream endet mit einer abschließenden Terminierungsmarkierung. Die meisten Blöcke enthalten im Array choices ein Delta mit einem Textfragment statt einer vollständigen Nachricht.

Entfernen Sie bei curl die Stille-Wirkung von -sS, um zu beobachten, wie die Ausgabe nach und nach eintrifft:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Zähle langsam bis fünf."}]}'

Das Flag -N deaktiviert die Pufferung, sodass Sie die Blöcke sehen, sobald sie eintreffen. Lesen Sie in Python die Antwort Zeile für Zeile:

with urllib.request.urlopen(request) as response:
    for raw_line in response:
        line = raw_line.decode("utf-8").strip()
        if not line.startswith("data: "):
            continue
        data = line[len("data: "):]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        delta = chunk["choices"][0].get("delta", {})
        text = delta.get("content")
        if text:
            print(text, end="", flush=True)

Praktische Hinweise:

  • Behandeln Sie stets die Terminierungsmarkierung [DONE] und leere Zeilen/Keepalive-Zeilen; gehen Sie nicht davon aus, dass jede Zeile JSON ist.
  • Blockieren Sie niemals den UI-Thread über den gesamten Stream hinweg – hängen Sie Deltas an einen Puffer an, sobald sie eintreffen.
  • Wenn der Client die Verbindung trennt, schließen Sie die Antwort, damit die vorgelagerte Generierung freigegeben wird.
  • Streaming ändert nichts an der Berechnung der Nutzung; der letzte Block trägt normalerweise die Nutzungsmetadaten. Abgerechnet werden Ausgabe-Tokens; die aktuellen Tarife finden Sie im Preispaneel der Website.

Tool-Calling zur Unterhaltung hinzufügen

Tool-Nutzung ermöglicht es dem Modell, strukturierte Aktionen aus Ihrem Code anzufordern, statt nur Text zu generieren. Die Anfrage erhält ein zusätzliches Array tools; die Unterhaltung erhält Assistentennachrichten mit tool_calls und role: "tool"-Nachrichten mit den Ergebnissen.

Definieren Sie die Parameter des Tools mit JSON Schema:

{
  "model": "claude-opus-5-5@aws",
  "messages": [
    {"role": "user", "content": "Wie ist das Wetter gerade 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, z. B. Lisbon"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Das Modell kann eine Nachricht mit tool_calls zurückgeben statt des endgültigen Textes. Jeder Eintrag gibt den Funktionsnamen an und enthält Parameter als JSON-String. Ihre Aufgabe ist es, diese Funktion gegen Ihr eigenes System auszuführen und dann das Ergebnis anzuhängen:

  1. Hängen Sie die Assistentennachricht mit tool_calls unverändert an messages an.
  2. Hängen Sie für jeden Aufruf eine Nachricht an, die role: "tool", die in der Assistentennachricht passende tool_call_id und ein auf das serialisierte Ergebnis gesetztes content enthält.
  3. Senden Sie die Anfrage mit demselben Array tools erneut. Das Modell erzeugt dann auf Basis Ihrer Ergebnisse eine natürlichsprachige Antwort.

Schutzmaßnahmen, die sich früh einzurichten lohnen:

  • Parameter validieren – validieren Sie die Parameter vor jeder Ausführung gegen das Schema – leiten Sie Modellausgaben niemals direkt an eine Shell oder eine Datenbankabfrage weiter.
  • Schleifen begrenzen. Setzen Sie eine Obergrenze für Tool-Calling-Runden (üblicherweise drei bis fünf Runden), damit ein Modell, das fortlaufend Aufrufe anfordert, nicht endlos schleift.
  • Fehler als Tool-Ergebnis zurückgeben. Wenn eine Funktion fehlschlägt, senden Sie eine kurze Fehlerzeichenkette mit der passenden tool_call_id; das Modell kann dann erneut versuchen oder den Fehler erklären, statt zu stocken.
  • Tool-Beschreibungen präzise halten. Ungenaue Beschreibungen führen weit häufiger zu falscher Tool-Auswahl als Parameterfehler.

Tool-Definitionen werden mit der Anfrage ausgewertet und zählen zu Ihrem Token-Verbrauch. Die aktuellen Tarife sind im Preispaneel der Website veröffentlicht.

Was als Nächstes zu tun ist

Beginnen Sie mit dem minimalen curl-Aufruf, überführen Sie ihn in eine Python-Wrapper-Funktion und ergänzen Sie Streaming und Tools erst dann, wenn Ihr Anwendungsfall sie benötigt. Die Modellzeichenkette claude-opus-5-5@aws bleibt immer gleich – alles andere sind Felder in der Anfragenutzlast.

Ä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