Comment appeler kimi-k3.1-pro via l'API HiAPI : curl, Python et requêtes directement exécutables

Pourquoi appeler kimi-k3.1-pro via une API agrégée

Chaque intégration de modèle s'accompagne d'un même coût caché : le premier jour est amusant, le deuxième mois relève de la maintenance. Lorsque vous branchez kimi-k3.1-pro directement dans votre application, vous héritez aussi du schéma d'authentification, de la sémantique des erreurs, du modèle de quotas et du rythme de publication de ce fournisseur. Pour un prototype mono-modèle, cela ne pose aucun problème. Mais dès que vous voulez un deuxième modèle, un deuxième environnement, ou une voie de repli lorsque un endpoint tombe en panne, cela devient source de friction.

Une API agrégée unifie ces différences en un seul contrat. HiAPI expose kimi-k3.1-pro sous une forme de requête compatible OpenAI, ce qui signifie que le code client que vous écrivez ici n'est pas jetable. Changez l'identifiant du modèle, et la même structure de requête s'applique aux autres modèles de la plateforme — mêmes en-têtes, même tableau de messages, même encapsulation de streaming.

Concrètement, pour kimi-k3.1-pro, cela a trois implications pratiques :

• Une surface d'identifiants unique. Vous ne gérez qu'une seule clé API et une seule URL de base, au lieu d'un ensemble croissant de comptes fournisseurs.
• Des charges utiles prévisibles. Les schémas de requête et de réponse restent stables d'un modèle à l'autre, de sorte que votre couche de parsing, de reprise et de journalisation n'est écrite qu'une fois.
• Un coût de migration faible. Si un type de charge de travail s'avère mieux adapté à un autre modèle par la suite, la modification se résume à une chaîne de caractères dans la charge utile, et non à une réécriture de la couche de transport.

Le reste de ce guide porte sur l'intégration elle-même : anatomiede la requête, appels curl directement copiables, client Python équivalent, puis les deux fonctionnalités qui posent le plus souvent problème en production — le streaming et l'appel d'outils — et enfin une liste de vérification pour le dépannage des erreurs.

Ce dont vous avez besoin avant de commencer

• Une clé API HiAPI, stockée là où votre projet conserve ses secrets.
• L'URL de base de l'API de votre compte, fournie par la console HiAPI. Tous les exemples ci-dessous utilisent https://api.hiapi.ai/v1 comme base fictive ; vérifiez l'hôte réel dans la console avant la mise en production.
• La chaîne d'identifiant du modèle kimi-k3.1-pro — copiez-la telle quelle depuis la liste des modèles de la console, car l'identifiant est sensible à la casse.
• curl pour le premier test, et Python 3.9+ avec la bibliothèque requests pour l'exemple client.

Forme de la requête : endpoint, en-têtes et paramètres du modèle

Chaque appel de conversation suit la même anatomie. Comprenez chaque partie une fois, et vous n'aurez plus à déboguer champ par champ.

Endpoint

Les complétions de conversation se trouvent sur un chemin unique sous l'URL de base :

POST {BASE_URL}/chat/completions

C'est le seul endpoint nécessaire pour tous les exemples de ce guide. Le streaming et les appels d'outils ne sont pas des endpoints distincts — ce sont des options sur le même corps de requête.

En-têtes

Seuls deux en-têtes comptent réellement :

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

La clé va dans l'en-tête Authorization, préfixée par Bearer. Ne la placez pas dans l'URL, les paramètres de requête ou le corps — ces trois pratiques la font fuiter dans les journaux et les rapports d'erreur. Définissez explicitement Content-Type ; certains clients HTTP ne le déduisent pas à votre place.

Les champs du corps qui comptent vraiment

Un corps de requête minimal comporte quatre champs significatifs :

• model — l'identifiant kimi-k3.1-pro. Obligatoire. C'est le champ le plus souvent mal saisi lors du premier essai, car il doit correspondre exactement.
• messages — un tableau ordonné d'objets, chacun contenant role (system, user ou assistant) et content. Obligatoire et non vide. L'ordre constitue votre historique de conversation ; c'est exactement ce tableau que voit le modèle, rien d'autre.
• stream — booléen, false par défaut. Lorsqu'il vaut true, la réponse arrive sous forme d'événements envoyés par le serveur, et non comme un corps JSON unique. Une section y est consacrée ci-dessous.
• temperature — contrôle d'échantillonnage optionnel. Une valeur basse produit des sorties plus déterministes ; une valeur élevée plus de variété. Choisissez une valeur une fois par cas d'usage et n'y touchez plus, sans la modifier à chaque requête.

Champs optionnels que vous pouvez ajouter à mesure que l'intégration mûrit :

• max_tokens — limite supérieure de génération. Utile comme garde-fou de coût et de latence. Notez qu'il limite la sortie, pas l'entrée.
• tools — tableau de définitions d'outils, détaillé plus loin.
• tool_choice — contrôle si et comment le modèle appelle les outils que vous fournissez.
• stop — une ou plusieurs séquences qui arrêtent la génération.

La réponse à laquelle vous attendre

Une réponse non streaming renvoie un objet JSON dont le tableau choices contient au moins un élément. Dans cet élément, vous trouverez un objet message avec role et content, plus un finish_reason qui indique pourquoi la génération s'est arrêtée. Branchez toujours votre logique sur finish_reason plutôt que de supposer que le contenu est complet — une réponse tronquée a toujours du contenu, mais ce n'est pas une réponse complète.

Écrivez votre parseur pour cette structure, et non pour une réponse sérialisée en chaîne. Il survivra ainsi à tout changement de modèle sur la plateforme.

Une requête curl directement exécutable

Commencez ici. Si cela renvoie une réponse valide, votre clé, votre URL de base et votre identifiant de modèle sont corrects, et tout problème ultérieur se situera dans le code et non dans les identifiants.

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "system", "content": "Tu es un assistant technique concis."},
      {"role": "user", "content": "Explique en deux phrases ce qu'est une clé d'idempotence."}
    ],
    "temperature": 0.3,
    "max_tokens": 256
  }'

Explication de chaque champ

• -sS fait taire curl sur la progression tout en exposant les erreurs. Sans le second S, une requête échouée peut se terminer silencieusement, gâchant une session de débogage.
• Les variables d'environnement gardent la clé hors de l'historique du shell et hors du tampon de défilement du terminal. Exportez HIAPI_BASE_URL et HIAPI_API_KEY dans votre profil shell ou un fichier .env chargé.
• Entourer le corps de guillemets simples est correct pour un shell POSIX, tant que la charge utile ne contient pas de guillemets simples. Dès que vous en avez besoin, déplacez le corps dans un fichier et passez-le avec -d @body.json — cela évite une catégorie de bugs de guillemets qui ressemblent à des erreurs de format JSON.
• Le message system est facultatif, mais mérite d'être inclus. C'est l'endroit le plus simple pour fixer le ton et le format de sortie.
• max_tokens est volontairement prudent dans cet exemple. Il limite à la fois la latence et le coût du test de fumée.

Interpréter le résultat

Un appel réussi renvoie un HTTP 200 et un corps JSON. Vérifiez trois choses avant de continuer :

1. choices est un tableau non vide.
2. choices[0].message.content contient une vraie réponse.
3. choices[0].finish_reason est une valeur d'achèvement normal, et non une troncature par longueur.

Si le corps de la réponse est un objet d'erreur, sautez à la section de dépannage — le message d'erreur indique généralement le champ fautif.

Astuce de reproductibilité

Enregistrez cet appel curl sous forme de script shell dans votre dépôt. Une commande qui teste en direct l'API constitue le moyen le plus rapide de distinguer « mon intégration est cassée » de « mon compte ou ma clé a changé ». Lancez-la chaque fois que quelque chose semble anormal.

La même requête écrite en Python

La version Python devrait sembler ennuyeuse — c'est précisément l'objectif. Toutes les décisions intéressantes (identifiant de modèle, URL de base, délai d'attente) doivent se trouver dans la configuration, et non dispersées aux points d'appel.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("HIAPI_MODEL", "kimi-k3.1-pro")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def chat(messages, temperature=0.3, max_tokens=512, timeout=60):
    payload = {
        "model": MODEL,
        "messages": messages,
        "temperature": temperature,
        "max_tokens": max_tokens,
    }
    resp = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=HEADERS,
        json=payload,
        timeout=timeout,
    )
    resp.raise_for_status()
    data = resp.json()
    choice = data["choices"][0]
    return choice["message"]["content"], choice.get("finish_reason")


if __name__ == "__main__":
    text, reason = chat([
        {"role": "system", "content": "Tu es un assistant technique concis."},
        {"role": "user", "content": "Explique en deux phrases ce qu'est une clé d'idempotence."},
    ])
    print(reason)
    print(text)

Pourquoi cette organisation

• Utiliser json= plutôt que data= — la bibliothèque requests sérialise le dictionnaire et définit le type de contenu à votre place. Une sérialisation manuelle introduit facilement des erreurs d'échappement.
• Toujours timeout=60 — l'absence de délai d'attente est la cause la plus fréquente de processus de travail suspendus jusqu'à ce que le gestionnaire les tue. Tout appel réseau en service doit avoir un délai d'attente.
• raise_for_status() avant de parser — cela transforme un échec de la couche HTTP en exception au point d'appel, au lieu de laisser un corps de réponse mal formé s'écouler en aval.
• MODEL vient de l'environnement — lors d'un changement de modèle, l'identifiant de modèle est la seule chose qui change. Le placer dans la configuration fait du changement une variable de déploiement, et non une modification de code.
• Renvoie finish_reason — l'appelant a presque toujours besoin de savoir si la réponse a été tronquée.

Rester réutilisable d'un modèle à l'autre

La signature de chat(messages, ...) n'expose délibérément rien de spécifique au modèle. Si vous routez plus tard des charges de travail moins coûteuses vers d'autres modèles, passez soit un paramètre explicite de remplacement du modèle, soit construisez un second objet client avec un autre MODEL. Le transport, les en-têtes, la stratégie de reprise et la gestion des erreurs restent identiques.

Note sur les reprises

Ne réessayez pas aveuglément à l'intérieur de chat(). Réessayez à la couche qui sait si l'opération est sûre à répéter — une complétion échouée est généralement sûre, mais une requête qui a déjà modifié un état en aval ne l'est pas. Ne réessayez que pour les échecs de transport transitoires et les réponses de limitation de débit, et uniquement avec un backoff exponentiel plafonné.

Diffuser la réponse sans casser le client

Le streaming fait la différence entre une interface de chat qui semble instantanée et un écran vide pendant dix secondes. Il introduit aussi le plus de bugs d'intégration, car la réponse n'est plus un document JSON.

Comment l'activer

Ajoutez "stream": true au corps de la requête. Le reste de la requête ne change pas.

with requests.post(
    f"{BASE_URL}/chat/completions",
    headers=HEADERS,
    json={"model": MODEL, "messages": messages, "stream": True},
    stream=True,
    timeout=120,
) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        chunk = line[len("data:"):].strip()
        if chunk == "[DONE]":
            break
        # parser chunk comme du JSON et lire choices[0].delta.content

Ce qui arrive réellement

Le corps de la réponse est une série d'événements envoyés par le serveur. Chaque événement est une ligne data: portant un petit objet JSON. Dans choices[0], il s'agit d'un objet delta et non d'un objet message — le delta contient généralement un fragment de content, et peut aussi ne rien contenir. Le flux se termine par la ligne sentinelle data: [DONE].

Quatre règles couvrent la quasi-totalité des erreurs :

1. Accumulez, ne remplacez pas. Chaque delta est un fragment. Ajoutez delta.content à un tampon ; la réponse complète est la concaténation ordonnée de chaque fragment.
2. Ignorez les deltas vides. Le premier et le dernier événement ne portent souvent pas de contenu. Évitez d'ajouter None.
3. Traitez [DONE] comme un terminateur, pas comme une donnée. Arrêtez la lecture là ; ce qui suit ne fait pas partie de la réponse.
4. Lisez-le depuis le dernier événement portant finish_reason. En mode streaming, l'état d'achèvement apparaît dans un delta tardif, et non dans un champ de premier niveau.

Les pièges qui méritent d'être nommés

• Oublier stream=True dans l'appel client. Vous recevrez alors le flux entier comme un seul tampon, ce qui va à l'encontre du but et ressemble à une requête non streaming très lente.
• Un délai d'attente réglé comme en non streaming. Un flux long dure plus longtemps qu'une requête courte. Donnez au chemin streaming un délai de lecture plus permissif, et envisagez un minuteur d'inactivité qui interrompt si aucun octet n'arrive pendant un intervalle donné.
• Parser ligne par ligne sans vérifier le préfixe. Toutes les lignes ne sont pas des données. Les lignes vides séparent les événements ; ignorez-les.
• Supposer que le delta a une clé content. Le streaming d'appels d'outils place d'autres clés dans le delta. Lisez toujours de manière défensive.
• Oublier le consommateur côté client. Un serveur qui écrit le flux dans un tampon et ne l'affiche qu'à la fin est techniquement du streaming, mais pas en pratique. Assurez-vous que l'aval affiche les fragments à leur arrivée.

Quand ne pas diffuser en streaming

Les tâches par lots, les résumés en arrière-plan et tout ce dont la sortie est consommée par un programme plutôt que montrée à un humain sont généralement plus simples sans streaming. Une réponse non streaming ne s'analyse qu'une fois, se journalise plus facilement et se valide plus facilement selon un schéma. Utilisez le streaming là où la latence est visible pour l'utilisateur ; ne diffusez pas par défaut.

Ajouter des appels d'outils au flux de travail

Les appels d'outils permettent au modèle de demander à votre code d'exécuter des actions au lieu d'inventer des réponses. Le protocole est une conversation en deux tours : vous déclarez les outils, le modèle peut répondre par une demande d'appel, vous l'exécutez, puis vous renvoyez le résultat.

Déclarer un outil

Ajoutez un tableau tools à la requête. Chaque entrée enveloppe une description de fonction :

{
  "model": "kimi-k3.1-pro",
  "messages": [{"role": "user", "content": "Quel temps fait-il à Lisbonne ?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Renvoie la météo actuelle d'une ville donnée.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "Nom de la ville"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Le description de la fonction et de chacun de ses paramètres n'est pas décoratif — c'est le seul guide dont dispose le modèle pour décider quand et comment appeler l'outil. Rédigez-le comme vous écririez des instructions à un nouveau collègue.

La boucle de réponse

1. Envoyez la requête.
2. Si choices[0].finish_reason indique un appel d'outil, lisez choices[0].message.tool_calls. Chaque entrée a un id, un name de fonction et des arguments — une chaîne encodée en JSON, et non un objet. Analysez-la.
3. Exécutez la fonction dans votre code. Validez les arguments avant tout traitement ; le modèle peut générer une charge utile plausible mais avec des champs manquants ou des types erronés.
4. Ajoutez le message de l'assistant — y compris ses tool_calls — à votre tableau messages.
5. Ajoutez un nouveau message avec le rôle tool, portant le tool_call_id correspondant, et le résultat comme content.
6. Envoyez à nouveau la requête. Le modèle utilise maintenant la sortie de l'outil pour composer la réponse finale.

L'étape 4 est celle que l'on saute, et c'est précisément celle qui casse. Si vous ne renvoyez que le résultat de l'outil sans le tour d'appel d'outil de l'assistant, la conversation contient une référence orpheline et le modèle n'a pas trace de ce qu'il avait demandé.

Gérer plusieurs appels

Une réponse peut contenir plusieurs appels d'outils dans le même tour. Exécutez-les un par un et renvoyez un message tool pour chaque appel, chacun portant son propre tool_call_id. Ne les fusionnez pas.

Contrôler les appels

tool_choice est votre levier de politique : auto laisse le modèle décider, exiger un outil spécifique force son appel, désactiver les outils lui indique de répondre directement. Gardez un budget — si un outil échoue en continu et que le modèle réessaie en continu, la boucle d'outils peut durer longtemps. Limitez le nombre d'itérations dans votre propre boucle et, à la limite, renvoyez un message clair au lieu de laisser la requête s'éterniser.

Traiter la sortie d'outil comme non fiable

Le modèle lit les résultats d'outils comme du texte. Gardez-les petits, structurés, sans instructions, et validez les arguments de votre côté. Un outil qui renvoie du texte non borné est à la fois un problème de coût et un risque de correction.

Diagnostiquer les erreurs courantes

La plupart des échecs d'intégration se rangent dans cinq catégories. Parcourez cette liste avant de modifier le prompt.

1. Authentification et autorisation

• Symptôme : code HTTP dans la plage 401/403.
• Vérifiez : la clé existe, ne contient pas d'espaces avant ou après lors du copier-coller, et porte exactement le préfixe Bearer .
• Vérifiez : l'URL de base correspond à celle affichée dans la console HiAPI — un hôte obsolète ou mal copié produit des erreurs d'authentification déroutantes.
• Correction : réexportez la variable d'environnement, puis relancez le test de fumée curl avant de toucher au code.

2. Charges utiles mal formées

• Symptôme : erreur de validation de requête nommant un champ, ou corps de réponse impossible à parser.
• Vérifiez : le corps de la requête est du JSON valide. Lors d'une construction manuelle, validez-le une fois avec json.tool ; lors d'une construction par code, assurez-vous que le dictionnaire n'est pas accidentellement imbriqué d'un niveau supplémentaire.
• Vérifiez : messages n'est pas vide et chaque entrée a role et content.
• Vérifiez : les valeurs de role appartiennent à l'ensemble pris en charge. Une faute de frappe comme role: "human" est une erreur silencieuse dans certains clients plutôt qu'une erreur évidente.
• Vérifiez : les entrées de tools ont type: "function" et un objet function imbriqué. Une définition aplatie est l'erreur la plus fréquente lors des appels d'outils.

3. Identifiant de modèle

• Symptôme : une erreur du type « non trouvé », ou indiquant que le modèle n'est pas disponible pour votre compte.
• Vérifiez : l'identifiant est copié tel quel depuis la console. La casse et les séparateurs comptent.
• Vérifiez : le modèle est activé pour votre clé. Même avec un identifiant valide, un modèle que votre compte ne peut pas appeler échouera.

4. Limites de contexte et de longueur

• Symptôme : une erreur indiquant que la requête dépasse le contexte maximal, ou une réponse se terminant par un finish_reason lié à la longueur.
• Vérifiez : la somme de votre prompt système, de l'historique des messages et de toute définition d'outil. Les schémas d'outils comptent dans le budget et sont facilement oubliés.
• Correction : raccourcissez l'historique, résumez les tours anciens ou divisez la tâche. En cas de troncature de sortie, augmentez max_tokens si la charge utile en a réellement besoin ; sinon, gardez-le borné.

5. Limitation de débit et délais d'attente

• Symptôme : statut de limitation sous charge, ou délai de lecture côté client.
• Vérifiez : si les reprises sont effectuées sans aucun backoff. Une boucle de reprise serrée transforme une limitation passagère en limitation persistante.
• Correction : respectez les signaux de limitation indiqués dans la réponse, utilisez un backoff exponentiel plafonné avec jitter, et maîtrisez la concurrence par clé. Pour les délais d'attente, vérifiez d'abord la valeur côté client — une limite client plus courte que le temps de génération du modèle produit exactement ce symptôme.

Discipline générale de débogage

Pour chaque échec, journalisez quatre choses : le code HTTP, le corps de la réponse, l'identifiant de modèle et si stream est défini. Ces quatre éléments expliquent la grande majorité des incidents. Et maintenez le test de fumée curl à jour — lorsqu'il passe et que votre application échoue, vous savez que le problème est dans le code, pas dans les identifiants.

Lire les messages d'erreur

La couche d'agrégation indique généralement clairement quel champ a provoqué le rejet. Résistez à l'envie de réécrire le prompt. Lisez le message, corrigez le champ incriminé, réessayez une fois. Si la même erreur persiste, validez la requête par rapport au test de fumée avant d'aller plus loin.

Avant la mise en ligne : liste de vérification de production

L'écart entre « ça fonctionne dans mon terminal » et « ça fonctionne en production » tient surtout à une liste que personne n'a écrite. En voici une à copier.

Configuration et clés

• La clé API est stockée dans un gestionnaire de secrets, jamais dans le contrôle de source, jamais dans une URL ou une ligne de journal. Vérifiez que votre client HTTP ne peut pas imprimer l'en-tête Authorization au niveau debug.
• L'URL de base et l'identifiant de modèle sont de la configuration, pas des constantes dispersées dans le code. Confirmez l'URL de base avec la console.
• Faites tourner les clés selon un calendrier, et après le départ de tout membre de l'équipe. Votre code client doit adopter une clé renouvelée sans modification.

Hygiène des requêtes

• Chaque appel sortant a un délai d'attente explicite, et les chemins streaming ont un délai plus permissif plus une règle d'abandon en cas d'inactivité.
• max_tokens est défini sur tous les chemins d'appel. Une génération non bornée, c'est une facture non bornée.
• Les paramètres d'échantillonnage sont fixés par cas d'usage et documentés, pour que les résultats soient reproductibles en cas de débogage.

Traitement des réponses

• Votre parseur branche sur finish_reason et traite la troncature comme un résultat distinct, et non comme une réponse complète.
• L'accumulation en streaming est testée à la fois pour les réponses courtes et longues, y compris celles qui se terminent prématurément.
• Les arguments d'appel d'outils sont validés avant utilisation, et le tour d'appel d'outil de l'assistant est toujours réintégré dans le tableau de messages.
• La boucle d'outils a une limite d'itérations et un message d'échec clair.

Comportement en cas d'échec

• Les reprises sont bornées, utilisent un backoff exponentiel plafonné avec jitter, et ne s'appliquent qu'aux opérations sûres à répéter.
• Les réponses de limitation sont respectées, et non bombardées.
• Les échecs enregistrent le statut, le corps de réponse, l'identifiant de modèle et l'indicateur stream — ces quatre champs résolvent réellement les incidents.
• Le test de fumée curl tourne en CI ou selon un calendrier, de sorte que vous appreniez les changements d'identifiants ou de modèle depuis le tableau de bord plutôt que de vos clients.

Coût et capacité

• Vous savez comment l'usage est facturé — la plateforme facture les tokens traités, donc les longs prompts et les longues générations comptent tous les deux. Consultez les tarifs actuels dans le panneau de tarification de la console.
• Vous savez quel type de charge de travail consomme le plus, et s'il a besoin du modèle complet ou d'un modèle plus léger.
• Vous avez une voie de dégradation : si un appel échoue de manière répétée, l'application se dégrade visiblement au lieu de se bloquer silencieusement.

Une dernière question

Posez-la : quelqu'un qui n'a pas écrit cette intégration peut-il l'observer ? Si un développeur de votre équipe peut lire le test de fumée, les champs de journal d'erreur et la configuration, et comprendre comment diagnostiquer une panne, vous avez terminé. Sinon, la liste n'est pas encore terminée.

Avec un appel curl fonctionnel, un client Python réutilisable et cette liste, kimi-k3.1-pro est réellement intégré, et pas seulement connecté.