Come usare kimi-k3 tramite l'API hiapi: curl, Python ed esempi di richiesta eseguibili

Cosa costruirai

kimi-k3 è un modello conversazionale con capacità di ragionamento, disponibile su hiapi tramite l'endpoint standard /v1/chat/completions compatibile con OpenAI — nessun polling di attività asincrone, nessun caricamento di immagini. Questa guida ti accompagna da zero fino a una chiamata funzionante con curl e Python, poi illustra due cose che causano problemi in produzione: i token di ragionamento che consumano il tuo budget di max_tokens e l'output in streaming.

Prerequisiti: una chiave API hiapi. Se non ne hai una, ottienila dalla console — ogni richiesta sottostante si autentica tramite Authorization: Bearer sk-<your-key>.

Esempio minimo funzionante

kimi-k3 è un modello testuale, quindi non passa attraverso la coda di attività /v1/tasks che hiapi usa per i modelli di immagini/video — è una chiamata diretta e sincrona di completamento conversazionale.

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"])

Una risposta riuscita è simile a questa:

{
  "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}
  }
}

La risposta finale si trova in choices[0].message.content. L'ID del modello nella richiesta è l'ID nudo kimi-k3 — hiapi lo mappa internamente (il campo model del corpo della risposta riporta l'etichetta sottostante, ad esempio FW-Kimi-K3; è il comportamento previsto).

L'unica insidia: i token di ragionamento e max_tokens

kimi-k3 è un modello di ragionamento — scrive la catena di pensiero in message.reasoning_content prima di generare il content finale, e entrambi condividono lo stesso budget di max_tokens. Se max_tokens è impostato troppo basso, il modello può consumare l'intero budget nel ragionamento e restituire finish_reason: "length" con il campo content vuoto:

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

Non è un bug — è solo il ragionamento che esaurisce lo spazio prima di arrivare alla risposta finale. Ci sono due modi per gestirlo:

• Lascia margine sufficiente. Per risposte brevi e fattuali, un max_tokens di 200–300 di solito basta a coprire ragionamento e risposta. Per generazioni più lunghe, aumenta il budget di conseguenza.
• Controlla finish_reason. Se restituisce "length" e content è vuoto, aumenta max_tokens e riprova; non trattare la stringa vuota come risposta finale.

Output in streaming

Imposta "stream": true per ottenere Server-Sent Events (SSE) senza attendere la risposta completa. I chunk trasportano prima i delta di delta.reasoning_content, poi delta.content quando il modello inizia a scrivere la risposta finale:

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"))

Se stai costruendo un'interfaccia di chat, mostra in streaming solo delta.content — la maggior parte delle applicazioni nasconde delta.reasoning_content dietro un interruttore "sta pensando" o lo comprime, invece di mostrarlo inline.

Considerazioni per la produzione

• Gestione degli errori. Una chiave non valida o assente restituisce HTTP 401 con un corpo di risposta strutturato:

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

  Annota il request_id — se apri un ticket, il team di supporto ne ha bisogno.
• Retry. I completamenti conversazionali sono sincroni, quindi non c'è alcun ID di attività da interrogare né callback da registrare (quel pattern vale per i modelli asincroni di immagini/video di hiapi, non per il testo). In caso di timeout o di 5xx, ripeti semplicemente la richiesta; poiché il server non mette in coda alcuna attività, puoi trattarla come un normale retry idempotente, simile a una GET.
• Fatturazione. kimi-k3 viene fatturato a token come gli altri modelli testuali della piattaforma — prima di stimare i costi su larga scala, controlla le tariffe attuali nella pagina dei prezzi, perché i token di ragionamento contano come token di completamento.

Domande frequenti

kimi-k3 supporta l'output in streaming? Sì — passa "stream": true e leggi la risposta text/event-stream come mostrato sopra.

Perché il content nella mia risposta è vuoto? finish_reason è quasi certamente "length" — il modello ha speso l'intero budget di max_tokens in reasoning_content prima di arrivare alla risposta finale. Aumenta max_tokens e riprova.

kimi-k3 richiede l'endpoint /v1/tasks di hiapi? No. /v1/tasks serve per i modelli asincroni di generazione di immagini, video e musica. kimi-k3 è un modello testuale sincrono, servito tramite l'endpoint standard /v1/chat/completions.

Posso usare l'OpenAI Python SDK invece di requests nativo? Sì — punta il base_url dell'SDK a https://api.hiapi.ai/v1 e passa la tua chiave hiapi come chiave API; la struttura di richiesta/risposta è compatibile con OpenAI.

Quale ID modello devo passare nella richiesta? L'ID nudo kimi-k3. Nel campo model del corpo della risposta vedrai riportata l'etichetta interna simile a FW-Kimi-K3 — è il comportamento previsto e non influisce su fatturazione o comportamento.