Blog

Tutorial

So rufen Sie kimi-k3.1-pro-highspeed über die HiAPI API auf: curl- und Python-Beispiele

Nov 12, 2026
HiAPI-Blog-Coverbild: Auf dunkelbraunem Hintergrund kreuzen sich breite Gewebebänder im Rhythmus einer Korbflechtung, akzentuiert mit Beige- und Messingtönen, die eine flächige Komposition bilden.
Auf dieser Seite

Was kimi-k3.1-pro-highspeed ist und wann Sie es wählen sollten

kimi-k3.1-pro-highspeed ist eines der Chat-Modelle, die HiAPI anbietet. Der Aufruf funktioniert genau wie bei jedem anderen Chat-Modell der Plattform: Sie senden eine Reihe von Nachrichten und erhalten eine Completion zurück. Der Namensbestandteil „high-speed“ deutet den beabsichtigten Kompromiss an – wählen Sie es, wenn Ihnen Latenz wichtiger ist als rohe Schlussfolgerungstiefe und Sie vorhersehbare Antwortzeiten statt der langsamsten, ausführlichsten Antwort wünschen.

Daher eignet es sich gut für die folgenden konkreten Workloads:

  • Interaktive Oberflächen – Chat-UI, Autovervollständigung und Inline-Assistenten, bei denen Nutzer auf eine Antwort warten.
  • Pipelines mit hohem Durchsatz – Klassifizierung, Extraktion, Zusammenfassung und Umschreibungsaufgaben, bei denen Sie Durchsatz benötigen und einzelne Anfrageergebnisse kurz sind.
  • Mehrstufige Agenten-Schleifen – mehrstufige Abläufe, bei denen jeder Aufruf klein ist und die Gesamtlatenz hauptsächlich von der Anzahl der Roundtrips abhängt, nicht von einem einzelnen Aufruf.

Wenn die Aufgabe langes, wohlüberlegtes Schlussfolgern über einen großen Kontext erfordert oder wenn Sie Inhalte erzeugen, bei denen „ein langsamer, aber hochwertiger Durchlauf besser ist als viele schnelle Durchläufe“, ist es nicht die naheliegende Wahl. Benchmarken Sie in diesen Fällen zuerst die Ausgabequalität und optimieren Sie erst dann auf Geschwindigkeit – eine schnelle, aber falsche Antwort kostet mehr als eine langsame, aber richtige.

Da das Modell über die einheitliche Schnittstelle von HiAPI bereitgestellt wird, ist ein Wechsel zu einem anderen Modell oder zurück nur eine Änderung der Anfrage-Nutzlast und kein Neuschreiben von Code. Legen Sie den Modellnamen in der Konfiguration ab, statt ihn an der Aufrufstelle fest zu verdienen, dann können Sie A/B-Tests mit anderen Modellen durchführen, ohne den Code zur Erstellung der Anfrage zu ändern.

Was „chatbasiert“ in der Praxis bedeutet

Jede Anfrage hat folgende Struktur: eine Modellkennung, eine geordnete Nachrichtenliste (jede Nachricht enthält role und content) sowie optionale Parameter wie stream, temperature und max_tokens. Der System-Prompt wird als Nachricht mit role: "system" übergeben. Das ist das gesamte mentale Modell – der Rest dieses Leitfadens beschäftigt sich nur mit der Verrohrung rund um diese Form.

Voraussetzungen: Anmeldedaten, Endpunkt und Modellname

Bevor Sie Code schreiben, stellen Sie sicher, dass Sie die folgenden vier Dinge haben. Die meisten Fehler beim ersten Aufruf entstehen durch Lücken in dieser Checkliste und nicht durch einen Bug im Anfragetext.

1. Ein API-Schlüssel

Generieren Sie den Schlüssel im Dashboard Ihres HiAPI-Kontos. Behandeln Sie ihn als geheim: aus Umgebungsvariablen laden, niemals in ein Repository committen und rotieren, sobald er in Logs oder einem geteilten Notebook auftaucht.

export HIAPI_API_KEY="your-key-here"

2. Die Basis-URL

Der Endpunkt besteht aus der HiAPI-Basis-URL plus dem Pfad für Chat-Completions. Legen Sie die Basis-URL in der Konfiguration ab, damit Änderungen keinen Code anfassen müssen:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1"

3. Die Modellkennung

Der zu sendende Modellstring lautet exakt:

kimi-k3.1-pro-highspeed

Kopieren Sie ihn Zeichen für Zeichen. Modellnamen werden wörtlich abgeglichen – ein zusätzliches Leerzeichen, eine andere Groß-/Kleinschreibung oder ein Tippfehler liefert einen Fehler der Kategorie „Modell nicht gefunden“ statt einer Validierung eines anderen Feldes, was Sie an der falschen Stelle suchen lässt.

4. Ein Client, der HTTPS senden kann

Für die curl-Beispiele unten benötigen Sie nur eine Shell mit installiertem curl, was unter macOS und den meisten Linux-Images Standard ist. Für den Python-Teil benötigen Sie Python 3.8+ und das Paket requests:

pip install requests

Wenn Sie einen SDK-artigen Client bevorzugen, gelten derselbe Endpunkt, derselbe Schlüssel und derselbe Modellname – entscheidend ist das Wire-Format, und dieser Leitfaden bleibt bei rohem HTTP, damit nichts hinter einer Abstraktion verborgen bleibt.

Plausibilitätsprüfung

Bevor Sie die vollständige Anfrage bauen, führen Sie einen schnellen Test durch, um zu bestätigen, dass Schlüssel und Basis-URL aufgelöst werden können – ein absichtlich minimaler Aufruf mit einem Ein-Wort-Prompt. Wenn er gelingt, betrifft jeder spätere Fehler Ihre Anfrage-Nutzlast und nicht Ihre Anmeldedaten.

Eine funktionierende curl-Anfrage

Hier ist eine vollständige, direkt kopier- und einfügbare Anfrage. Sie verwendet eine Systemnachricht, um das Verhalten festzulegen, eine Benutzernachricht als eigentliche Anfrage und fixiert max_tokens, damit die Antwort beim Testen kurz bleibt.

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [
      {"role": "system", "content": "Du bist ein prägnanter technischer Assistent. Antworte in zwei Sätzen oder weniger."},
      {"role": "user", "content": "Erkläre, was ein Idempotenzschlüssel ist und warum er für Wiederholungen wichtig ist."}
    ],
    "temperature": 0.3,
    "max_tokens": 200,
    "stream": false
  }'

Feldweise Erklärung

  • model – die Modellkennung aus dem vorherigen Abschnitt. Erforderlich.
  • messages – ein geordnetes Array. system legt Persona und Einschränkungen fest; user trägt die Aufgabe. Die Reihenfolge ist wichtig: Spätere Nachrichten haben höhere Priorität bei der Steuerung des Verhaltens. Hängen Sie bei mehrstufigen Abläufen fortlaufend user- und assistant-Runden an dasselbe Array an, statt alles in eine riesige Benutzernachricht zu verketten.
  • temperature – Zufälligkeit der Stichprobenentnahme. Niedrige Werte liefern reproduzierbarere Ausgaben, was genau das ist, was Extraktion und Klassifizierung benötigen. Erhöhen Sie den Wert nur, wenn Sie tatsächlich Variation wünschen.
  • max_tokens – Obergrenze für die generierte Antwort. Explizites Setzen schützt Sie vor außer Kontrolle geratener Generierung und macht die Latenz vorhersehbar.
  • stream – hier false, was bedeutet, dass Sie bei Abschluss der Generierung ein JSON-Objekt erhalten. Spätere Abschnitte behandeln true.

Was zurückkommt

Die Antwort ist ein JSON-Objekt mit einem choices-Array. Der gewünschte Text steht in choices[0].message.content. Zudem gibt es einen usage-Block, der den Token-Verbrauch beschreibt – protokollieren Sie ihn, denn bei tokenbasierter Abrechnung ist er Ihr einziges Kosten-Signal pro Anfrage.

Wenn Sie debuggen, leiten Sie die Ausgabe durch einen Formatierer, um sie lesbar zu machen:

curl -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | python -m json.tool

Legen Sie den Anfragetext in payload.json ab und verwenden Sie -d @payload.json – so vermeiden Sie Shell-Quoting-Probleme, sobald die Nutzlast mehr als ein paar Felder umfasst.

Die Anfrage nach Python übertragen

Das Ziel ist hier keine Demo-Skript, sondern eine importierbare Funktion. Halten Sie die Anfrage-Nutzlast identisch mit der curl-Version – dieselben Felder, dieselben Namen, derselbe Modellstring – damit sich das Verhalten beim Werkzeugwechsel nicht ändert.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"


def chat(
    user_message: str,
    system_message: str = "Du bist ein prägnanter technischer Assistent.",
    temperature: float = 0.3,
    max_tokens: int = 400,
    timeout: float = 30.0,
) -> str:
    payload = {
        "model": MODEL,
        "messages": [
            {"role": "system", "content": system_message},
            {"role": "user", "content": user_message},
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
        "stream": False,
    }
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    data = response.json()
    return data["choices"][0]["message"]["content"]

Dann:

print(chat("Fasse den Unterschied zwischen PUT und PATCH in einem Satz zusammen."))

Warum so geschrieben

  • json=payload statt handgeschriebenem JSON – requests serialisiert korrekt und setzt den Inhaltstyp, was eine ganze Klasse von Quoting-Bugs eliminiert.
  • Explizites timeout – ohne es kann eine hängende Verbindung Ihren Worker unbegrenzt blockieren. Für kurze Completions sind dreißig Sekunden großzügig; für interaktive Pfade setzen Sie es niedriger.
  • raise_for_status() so früh wie möglich – Sie möchten, dass HTTP-Fehler an der Aufrufgrenze als Ausnahme auftreten und nicht drei Zeilen später als KeyError auf choices.
  • Konfiguration auf Modulebene – Schlüssel, Basis-URL und Modell an einer Stelle. Für spätere A/B-Tests anderer Modelle ändern Sie nur eine Konstante.

Mehrrunden-Konversationen

Für echte Konversationen akzeptieren Sie eine Nachrichtenliste als Parameter, statt zwei feste Nachrichten zu bauen:

def chat_with_history(messages: list, **kwargs) -> dict:
    payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
    r = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=30.0,
    )
    r.raise_for_status()
    body = r.json()
    return {
        "content": body["choices"][0]["message"]["content"],
        "usage": body.get("usage"),
    }

Hängen Sie die Antwort des Assistenten als role: "assistant" wieder an messages an, um das Gespräch fortzusetzen, und kürzen Sie ältere Runden, wenn die Historie länger wird – Kontext wird abgerechnet, daher verteuert ein unbegrenzter Gesprächsverlauf stillschweigend jede Anfrage.

Streaming-Antworten aktivieren und konsumieren

Setzen Sie "stream": true, und der Server sendet die Antwort inkrementell als Server-Sent Events statt eines Objekts am Ende. Für alles, was ein Nutzer gerade ansieht, lohnt sich der zusätzliche Client-Aufwand: Selbst wenn die gesamte Generierungszeit gleich bleibt, sinkt die Zeit bis zum ersten Token deutlich.

Aus curl-Sicht

curl -N -s "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro-highspeed",
    "messages": [{"role": "user", "content": "Schreibe ein Haiku über Wiederholungen."}],
    "stream": true
  }'

-N deaktiviert die Ausgabepufferung von curl, sodass Sie tatsächlich sehen, wie die Ereignisse beim Senden eintreffen. Sie erhalten eine Reihe von Zeilen, jede beginnt mit data: und trägt ein JSON-Fragment. Das letzte Ereignis ist data: [DONE]. Behandeln Sie diesen Sentinels als Endemarkierung des Streams und nicht als parsebares JSON.

Python-Client

import json
import requests


def stream_chat(user_message: str, timeout: float = 60.0) -> str:
    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": user_message}],
        "stream": True,
    }
    pieces = []
    with requests.post(
        f"{BASE_URL}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        stream=True,
        timeout=timeout,
    ) as r:
        r.raise_for_status()
        for raw in r.iter_lines(decode_unicode=True):
            if not raw or not raw.startswith("data: "):
                continue
            data = raw[len("data: "):].strip()
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0].get("delta", {})
            text = delta.get("content")
            if text:
                pieces.append(text)
                print(text, end="", flush=True)
    return "".join(pieces)

Regeln, damit Streaming korrekt bleibt

  • Verketten, nicht ersetzen. Jeder Block trägt nur das neue Fragment. Sammeln Sie in einer Liste und joinen Sie am Ende einmal; das Anhängen an einen String in einer Schleife ist bei langen Ausgaben quadratisch.
  • Fehlende Inhalte abfangen. Manche Blöcke tragen nur Metadaten, daher hat delta möglicherweise keinen content-Schlüssel. Verwenden Sie .get() und überspringen Sie leere Werte.
  • Unvollständige Zeilen behandeln. Frame-Grenzen können Zeilen aufteilen. iter_lines übernimmt das, aber wenn Sie den rohen Byte-Stream selbst parsen, puffern Sie bis zum Zeilenumbruch.
  • Für Streaming geeignete Timeouts setzen. Ein Gesamtstream kann legitime kurz Anfrage-Timeouts überschreiten. Verwenden Sie ein längeres Read-Timeout oder eine Deadline pro Block, statt Timeouts ganz zu deaktivieren.
  • Den Nicht-Streaming-Pfad behalten. Wenn Sie nur den endgültigen Text für Hintergrundaufgaben benötigen, ist stream: false einfacher und kostet weniger Schlussfolgerungsaufwand. Überlassen Sie Streaming den interaktiven Pfaden.

Fehlerantworten interpretieren und Wiederholungen entwerfen

Wiederholungen helfen nur, wenn der Fehler vorübergehend ist. Blindes Wiederholen fehlerhafter Anfragen verstärkt nur den Fehler. Die nützliche Unterscheidung ist: Fehler, die Sie im Code beheben, versus Fehler, die das Netzwerk oder der Server von selbst löst.

Klassifizierung nach Statuscode

Nicht wiederholen – Anfrage korrigieren:

  • 400 Bad Request – fehlerhaftes JSON, fehlende Pflichtfelder oder ungültige Parameterwerte. Lesen Sie die Fehlermeldung, korrigieren Sie die Anfrage-Nutzlast und fügen Sie einen Test hinzu, damit es nicht wieder auftritt.
  • 401 Unauthorized – Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen. Prüfen Sie das Format des Authorization-Headers und ob die Umgebungsvariable tatsächlich im laufenden Prozess gesetzt ist und nicht nur in Ihrer Shell.
  • 403 Forbidden – der Schlüssel ist gültig, aber darf diese Aktion nicht ausführen oder dieses Modell nicht verwenden. Eine Wiederholungsschleife ist hier reines Rauschen.
  • 404 Not Found – meist ein falscher Pfad oder eine unbekannte Modellkennung. Überprüfen Sie Basis-URL und den exakten Modellstring.
  • 422-artige Validierungsfehler – Parametertyp korrekt, aber Wert nicht akzeptabel (z. B. temperature außerhalb des Bereichs). Begrenzen Sie den Wert im Code.

Mit Backoff wiederholen:

  • 429 Too Many Requests – Sie haben das Rate-Limit überschritten. Backoff, und wenn die Antwort einen retry-after-Hinweis enthält, befolgen Sie ihn statt zu raten.
  • 500 / 502 / 503 / 504 – server- oder gatewayseitige Ausfälle. Genau hier ist exponentielles Backoff angebracht.
  • Verbindungsfehler und Timeouts – der Socket schlägt vor Abschluss der Antwort fehl. Wiederholen, aber nur wenn die Operation sicher wiederholbar ist.

Eine wohlverhaltene Wiederholungsschleife

import random
import time
import requests

RETRYABLE_STATUS = {429, 500, 502, 503, 504}


def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=30.0)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in RETRYABLE_STATUS:
                raise RuntimeError(f"Nicht wiederholbar {r.status_code}: {r.text[:200]}")
            if attempt == max_attempts:
                raise RuntimeError(f"Wiederholungen erschöpft, zuletzt {r.status_code}")
        delay = base_delay * (2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 0.5))
    raise RuntimeError("unreachable")

Zwei Details, die in der Produktion wichtig sind

  • Jitter ist keine Option. Ohne ihn wiederholen eine Gruppe von Workern, die gleichzeitig ins Rate-Limit laufen, im Gleichtakt und erzeugen erneut Spitzen. Der Zufallsterm oben verteilt sie.
  • Gesamtzeit begrenzen, nicht nur die Anzahl der Versuche. Vier exponentielle Backoff-Versuche können Ihr Anfrage-Deadline überschreiten. Begrenzen Sie die Versuchsanzahl so, dass der schlimmste Fall im Budget des Aufrufers bleibt, und geben Sie die verbleibende Zeit als Timeout für den nächsten Versuch nach unten weiter.

Wiederholen Sie Streaming-Anfragen nicht bei Teilausfällen, es sei denn, Sie entscheiden, wie mit Text umgegangen wird, der bereits an den Nutzer gesendet wurde. Ein übliches Muster ist, nur dann zu wiederholen, wenn noch nichts angezeigt wurde; andernfalls den Abbruch offenzulegen.

Checkliste vor dem Go-Live

Bevor dieser Code zu kritischer Last wird, führen Sie eine kurze Checkliste durch.

  • Überall Timeouts. Jede Anfrage hat explizite Verbindungs-/Lese-Timeouts, und der Wert stammt aus Ihrem Latenz-Budget, nicht aus dem Beispiel kopiert.
  • Geheimnisse außerhalb des Repositories. Der API-Schlüssel kommt aus der Umgebung oder einem Secret-Manager und wird niemals in Logs geschrieben. Entfernen Sie Header aus jedem Anfrage-Logger.
  • Modellname an einer Stelle. kimi-k3.1-pro-highspeed erscheint als einzelne Konstante, sodass Sie es ohne Suchen-und-Ersetzen austauschen oder A/B-testen können.
  • Fehler werden klassifiziert, nicht verschluckt. Wiederholbare und nicht wiederholbare Pfade sind im Code getrennt, Backoff enthält Jitter und die Versuchsanzahl ist begrenzt.
  • Nutzung protokollieren. Zeichnen Sie den Token-Verbrauch jeder Antwort zusammen mit Latenz und Status auf. Bei tokenbasierter Abrechnung ist das eine Frühwarnung, wenn Prompts stillschweigend zu groß werden.
  • Streaming-Pfad real getestet. Verifizieren Sie, dass die verkettete Ausgabe bei gleichem Prompt der Nicht-Streaming-Ausgabe entspricht und ein Abbruch mitten im Stream Ihre UI nicht in einem kaputten Zustand zurücklässt.
  • Kosten by Design kontrollieren. Setzen Sie immer max_tokens, kürzen Sie den Gesprächsverlauf und fassen Sie lange Dokumente zusammen, bevor Sie sie in den Kontext stopfen – diese drei Hebel halten die Ausgaben proportional zum Wert.

Wenn das erledigt ist, ist der Weg vom curl-Proof-of-Concept zum Produktionsaufrufer hauptsächlich Konfigurationsarbeit. Beginnen Sie mit der Nicht-Streaming-Funktion, fügen Sie Streaming hinzu, sobald interaktive Pfade existieren, und lassen Sie den Retry-Wrapper die Fehler abfangen, die Sie nicht verhindern können.

Ä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