Comment utiliser kimi-k3 via l'API hiapi : curl, Python et exemples de requêtes exécutables

Ce que vous allez construire

kimi-k3 est un modèle de conversation doté de capacités de raisonnement, accessible sur hiapi via le point de terminaison standard /v1/chat/completions compatible OpenAI — sans interrogation asynchrone de tâches ni téléversement d'images. Ce guide vous accompagne de zéro jusqu'à un appel exécutable en curl et en Python, puis détaille les deux points qui posent problème en production : les tokens de raisonnement qui empiètent sur votre budget max_tokens, et la sortie en streaming.

Prérequis : une clé API hiapi. Si vous n'en avez pas, obtenez-la depuis le tableau de bord — chaque requête ci-dessous s'authentifie via Authorization: Bearer sk-<your-key>.

Exemple minimal exécutable

kimi-k3 est un modèle textuel, il ne passe donc pas par la file de tâches /v1/tasks que hiapi utilise pour les modèles d'image/vidéo — c'est un appel direct et synchrone de complétion de conversation.

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

Une réponse réussie ressemble à ceci :

{
  "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 réponse finale se trouve dans choices[0].message.content. L'ID de modèle dans la requête est l'ID brut kimi-k3 — hiapi effectue le mappage en interne (le champ model du corps de réponse renvoie le libellé sous-jacent, par exemple FW-Kimi-K3 ; c'est le comportement attendu).

Le seul piège : les tokens de raisonnement et max_tokens

kimi-k3 est un modèle de raisonnement — il écrit d'abord sa chaîne de pensée dans message.reasoning_content avant de générer le content final, et les deux partagent le même budget max_tokens. Si max_tokens est fixé trop bas, le modèle peut consommer tout le budget en raisonnement et renvoyer finish_reason: "length" avec un champ content vide :

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

Ce n'est pas un bug — le raisonnement a simplement épuisé l'espace avant d'atteindre la réponse finale. Deux façons de gérer cela :

• Laissez une marge suffisante. Pour de courtes réponses factuelles, un max_tokens de 200–300 suffit généralement à couvrir le raisonnement et la réponse. Pour des générations plus longues, augmentez le budget en conséquence.
• Vérifiez finish_reason. Si "length" est renvoyé et que content est vide, augmentez max_tokens et réessayez ; ne prenez pas la chaîne vide pour la réponse finale.

Sortie en streaming

Définissez "stream": true pour obtenir des Server-Sent Events (SSE) au lieu d'attendre la réponse complète. Les blocs transportent d'abord des delta.reasoning_content incrémentaux, puis des delta.content une fois que le modèle commence à écrire la réponse 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"))

Si vous construisez une interface de chat, ne rendez en streaming que delta.content — la plupart des applications masquent delta.reasoning_content derrière un bouton « réflexion en cours » ou le replient, plutôt que de l'afficher en ligne.

Considérations pour la production

• Gestion des erreurs. Une clé invalide ou absente renvoie un HTTP 401 avec un corps de réponse structuré :

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

  Notez le request_id — l'équipe de support en aura besoin si vous ouvrez un ticket.
• Nouvelles tentatives. La complétion de conversation est synchrone : il n'y a ni ID de tâche à interroger, ni callback à enregistrer (ce mode s'applique aux modèles asynchrones d'image/vidéo de hiapi, pas au texte). En cas de timeout ou de 5xx, relancez simplement la requête ; comme aucune tâche n'est mise en file d'attente côté serveur, traitez-la comme une nouvelle tentative ordinaire, idempotente, comparable à un GET.
• Facturation. kimi-k3 est facturé au token comme les autres modèles textuels de la plateforme — consultez les tarifs actuels sur la page de tarification avant d'estimer les coûts à grande échelle, car les tokens de raisonnement sont comptés dans les tokens de complétion.

Questions fréquentes

kimi-k3 prend-il en charge la sortie en streaming ? Oui — passez "stream": true et lisez la réponse text/event-stream comme indiqué ci-dessus.

Pourquoi mon content est-il vide dans la réponse ? finish_reason vaut presque certainement "length" — le modèle a dépensé tout le budget max_tokens dans reasoning_content avant d'atteindre la réponse finale. Augmentez max_tokens et réessayez.

kimi-k3 nécessite-t-il le point de terminaison /v1/tasks de hiapi ? Non. /v1/tasks sert aux modèles asynchrones de génération d'images, de vidéos et de musique. kimi-k3 est un modèle textuel synchrone, servi via le point de terminaison standard /v1/chat/completions.

Puis-je utiliser le SDK Python OpenAI au lieu de requests natif ? Oui — pointez le base_url du SDK vers https://api.hiapi.ai/v1 et passez votre clé hiapi comme clé API ; les structures de requête/réponse sont compatibles OpenAI.

Quel ID de modèle faut-il passer dans la requête ? L'ID brut kimi-k3. Vous verrez dans le champ model du corps de réponse un libellé interne du type FW-Kimi-K3 renvoyé en écho — c'est le comportement attendu, sans incidence sur la facturation ou le comportement.