Tutorial
So rufen Sie kimi-k3.1-pro-highspeed über die HiAPI API auf: curl- und Python-Beispiele
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.systemlegt Persona und Einschränkungen fest;userträ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 fortlaufenduser- undassistant-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– hierfalse, was bedeutet, dass Sie bei Abschluss der Generierung ein JSON-Objekt erhalten. Spätere Abschnitte behandelntrue.
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=payloadstatt 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 alsKeyErroraufchoices.- 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
deltamöglicherweise keinencontent-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: falseeinfacher 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.
temperatureauß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-highspeederscheint 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 →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen