So verwendest du kimi-k3 über die hiapi API: curl, Python und lauffähige Request-Beispiele

Was du baust

kimi-k3 ist ein Dialogmodell mit Reasoning-Fähigkeiten, das über den standardmäßigen OpenAI-kompatiblen /v1/chat/completions-Endpunkt auf hiapi verfügbar ist – kein Polling asynchroner Aufgaben und kein Hochladen von Bildern nötig. Dieser Leitfaden führt dich von null zu einem lauffähigen Aufruf mit curl und Python und erklärt anschließend zwei Dinge, bei denen es in der Produktion leicht zu Fehlern kommt: Reasoning-Token, die dein max_tokens-Budget aufbrauchen, und Streaming.

Voraussetzungen: ein hiapi-API-Schlüssel. Falls du noch keinen hast, hol ihn dir im Dashboard – jeder Request unten authentifiziert sich über Authorization: Bearer sk-<your-key>.

Minimales lauffähiges Beispiel

kimi-k3 ist ein Textmodell und läuft daher nicht über die /v1/tasks-Aufgabenwarteschlange, die hiapi für Bild-/Videomodelle verwendet – es ist ein direkter, synchroner Chat-Completion-Aufruf.

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

Eine erfolgreiche Antwort sieht so aus:

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

Die endgültige Antwort steht in choices[0].message.content. Die Modell-ID im Request ist die nackte ID kimi-k3 – hiapi nimmt die Zuordnung intern vor (im Feld model des Antworttexts wird das zugrunde liegende Label zurückgegeben, z. B. FW-Kimi-K3; das ist erwartetes Verhalten).

Die einzige Falle: Reasoning-Token und max_tokens

kimi-k3 ist ein Reasoning-Modell – es schreibt die Gedankenkette bevor es den endgültigen content erzeugt in message.reasoning_content, und beide teilen sich dasselbe max_tokens-Budget. Wird max_tokens zu niedrig gesetzt, kann das Modell das gesamte Budget für das Reasoning verbrauchen und finish_reason: "length" zurückgeben, während das Feld content leer ist:

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

Das ist kein Bug – der Reasoning-Prozess hat nur den Platz aufgebraucht, bevor er zur endgültigen Antwort kam. Es gibt zwei Umgangsweisen:

• Genug Spielraum lassen. Für kurze, faktische Antworten reichen 200–300 max_tokens in der Regel aus, um Reasoning und Antwort abzudecken. Bei längeren Generierungen erhöhe das Budget entsprechend.
• finish_reason prüfen. Wenn "length" zurückkommt und content leer ist, erhöhe max_tokens und versuche es erneut; behandle den leeren String nicht als endgültige Antwort.

Streaming

Setze "stream": true, um Server-Sent Events (SSE) zu erhalten, ohne auf die vollständige Antwort warten zu müssen. Die Datenblöcke enthalten zuerst inkrementelles delta.reasoning_content und, sobald das Modell mit der endgültigen Antwort beginnt, delta.content:

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

Wenn du eine Chat-Oberfläche baust, rendere nur delta.content als Stream – die meisten Anwendungen verbergen delta.reasoning_content hinter einem „Denkt nach“-Schalter oder klappen es ein, statt es inline anzuzeigen.

Hinweise für die Produktion

• Fehlerbehandlung. Ein ungültiger oder fehlender Schlüssel liefert HTTP 401 mit einem strukturierten Antworttext:

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  Notiere dir die request_id – der Support benötigt sie, wenn du ein Ticket einreichst.
• Wiederholungen. Chat-Completions sind synchron, es gibt also keine Aufgaben-ID zum Polling und keinen Callback zum Registrieren (dieses Muster gilt für die asynchronen Bild-/Videomodelle von hiapi, nicht für Text). Bei Timeouts oder 5xx kannst du den Request einfach erneut senden; da serverseitig keine Aufgabe in eine Warteschlange gestellt wurde, kannst du ihn wie eine gewöhnliche idempotente, GET-ähnliche Wiederholung behandeln.
• Abrechnung. kimi-k3 wird wie andere Textmodelle auf der Plattform pro Token abgerechnet – prüfe die aktuellen Tarife auf der Preisseite, bevor du die Kosten im Maßstab schätzt, da Reasoning-Token in die Completion-Token einfließen.

Häufige Fragen

Unterstützt kimi-k3 Streaming? Ja – übergib "stream": true und lies die text/event-stream-Antwort wie oben gezeigt aus.

Warum ist content in meiner Antwort leer? finish_reason ist fast sicher "length" – das Modell hat das gesamte max_tokens-Budget für reasoning_content verbraucht, bevor es zur endgültigen Antwort kam. Erhöhe max_tokens und versuche es erneut.

Muss kimi-k3 den /v1/tasks-Endpunkt von hiapi verwenden? Nein. /v1/tasks dient asynchronen Bild-, Video- und Musikgenerierungsmodellen. kimi-k3 ist ein synchrones Textmodell und wird über den standardmäßigen /v1/chat/completions-Endpunkt bereitgestellt.

Kann ich das OpenAI Python SDK statt der nativen requests verwenden? Ja – richte die base_url des SDK auf https://api.hiapi.ai/v1 und übergib deinen hiapi-Schlüssel als API-Schlüssel; die Request-/Response-Struktur ist OpenAI-kompatibel.

Welche Modell-ID soll im Request übergeben werden? Die nackte ID kimi-k3. Im Feld model des Antworttexts siehst du ein internes Label wie FW-Kimi-K3 zurückgegeben – das ist erwartetes Verhalten und beeinflusst weder Abrechnung noch Verhalten.