Blog

Tutoriel

Comment appeler kimi-k3.1-pro-highspeed via l'API HiAPI : exemples curl et Python

Nov 12, 2026
Image de couverture du blog HiAPI : sur un fond brun café foncé, de larges sangles s'entrecroisent au rythme d'une armure de vannerie, rehaussées de touches beige et laiton, formant une composition plane.
Sur cette page

Qu'est-ce que kimi-k3.1-pro-highspeed et quand le choisir

kimi-k3.1-pro-highspeed est l'un des modèles conversationnels proposés par HiAPI. L'appel se fait comme pour n'importe quel autre modèle conversationnel de la plateforme : on envoie une liste de messages et on récupère un résultat de complétion. Le « high-speed » du nom indique le compromis attendu : choisissez-le lorsque vous privilégiez la latence à la profondeur de raisonnement brute, lorsque vous voulez des temps de réponse prévisibles plutôt que la réponse la plus lente et la plus détaillée.

Il convient donc particulièrement à plusieurs types de charges de travail :

  • Interfaces interactives — UI de chat, autocomplétion et assistants intégrés, où l'utilisateur attend une réponse.
  • Pipelines à haut débit — tâches de classification, d'extraction, de résumé et de réécriture, où vous avez besoin de débit et où chaque requête produit un résultat court.
  • Boucles d'agents multi-sauts — flux à plusieurs étapes où chaque appel est petit et où la latence totale dépend principalement du nombre d'allers-retours, plutôt que d'un appel isolé.

Ce n'est pas le choix évident lorsque la tâche exige un raisonnement long et réfléchi sur un contexte volumineux, ou lorsque ce que vous générez relève du principe « un passage lent mais de haute qualité vaut mieux que plusieurs passages rapides ». Dans ces cas, évaluez d'abord la qualité de sortie, puis optimisez la vitesse — une réponse rapide mais fausse coûte plus cher qu'une réponse lente mais correcte.

Comme le modèle est fourni via l'interface unifiée de HiAPI, passer plus tard à un autre modèle ou revenir à celui-ci ne demande que de modifier la charge utile de la requête, sans réécrire le code. Placez le nom du modèle dans la configuration plutôt que de le coder en dur à l'endroit de l'appel : vous pourrez ainsi faire des tests A/B avec d'autres modèles sans toucher au code de construction des requêtes.

Ce que signifie « conversationnel » en pratique

Chaque requête a cette structure : un identifiant de modèle, une liste ordonnée de messages (chaque message contient role et content), ainsi que des paramètres optionnels comme stream, temperature et max_tokens. Le prompt système est transmis via un message avec role: "system". C'est tout le modèle mental — le reste de ce guide n'est que de la plomberie autour de cette forme.

Prérequis : identifiants, point de terminaison et nom du modèle

Avant d'écrire la moindre ligne de code, vérifiez que vous disposez des quatre éléments suivants. La plupart des échecs au premier appel proviennent d'un manque dans cette liste, et non d'un bug dans le corps de la requête.

1. Une clé API

Générez une clé depuis le tableau de bord de votre compte HiAPI. Traitez-la comme un secret : chargez-la depuis une variable d'environnement, ne la commitez jamais dans un dépôt, et renouvelez-la dès qu'elle apparaît dans des logs ou un notebook partagé.

export HIAPI_API_KEY="your-key-here"

2. L'URL de base

Le point de terminaison est constitué de l'URL de base de HiAPI suivie du chemin de complétion de chat. Placez l'URL de base dans la configuration, afin de ne pas avoir à modifier le code en cas de changement :

export HIAPI_BASE_URL="https://api.hiapi.ai/v1"

3. L'identifiant du modèle

La chaîne de modèle à envoyer est exactement :

kimi-k3.1-pro-highspeed

Copiez-la caractère par caractère. Les noms de modèle sont mis en correspondance littéralement — un espace en trop, une casse différente ou une faute de frappe renverront une erreur de type modèle introuvable, plutôt qu'une erreur de validation sur un autre champ, ce qui peut vous pousser à chercher au mauvais endroit.

4. Un client capable d'envoyer du HTTPS

Pour l'exemple curl ci-dessous, il vous suffit d'un shell avec curl installé, ce qui est standard sur macOS et la plupart des images Linux. Pour la partie Python, vous aurez besoin de Python 3.8+ et du paquet requests :

pip install requests

Si vous préférez un client de type SDK, le même point de terminaison, la même clé et le même nom de modèle s'appliquent — c'est le format sur le fil qui compte, et ce guide s'en tient au HTTP brut pour que rien ne se cache derrière une abstraction.

Vérification de bon fonctionnement

Avant de construire la requête complète, faites un contrôle rapide pour confirmer que la clé et l'URL de base se résolvent — un appel volontairement minimal, avec un prompt d'un seul mot. S'il réussit, tout échec ultérieur concernera votre charge utile, et non vos identifiants.

Une requête curl fonctionnelle

Voici une requête complète, prête à copier-coller. Elle utilise un message système pour définir le comportement, un message utilisateur comme demande réelle, et fixe max_tokens afin que la réponse reste courte pendant les tests.

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": "Tu es un assistant technique concis. Réponds en deux phrases ou moins."},
      {"role": "user", "content": "Explique ce qu'est une clé d'idempotence et pourquoi elle est importante pour les nouvelles tentatives."}
    ],
    "temperature": 0.3,
    "max_tokens": 200,
    "stream": false
  }'

Explication champ par champ

  • model — l'identifiant de modèle de la section précédente. Obligatoire.
  • messages — un tableau ordonné. system définit le rôle et les contraintes ; user porte la tâche. L'ordre compte : les messages plus tardifs ont une priorité plus élevée pour orienter le comportement. Pour les flux multi-tours, ajoutez continuellement les tours user et assistant au même tableau, plutôt que de tout concaténer en un seul énorme message utilisateur.
  • temperature — la stochasticité de l'échantillonnage. Une valeur basse produit des sorties plus reproductibles, ce dont ont besoin l'extraction et la classification. Ne l'augmentez que lorsque vous voulez réellement de la variété.
  • max_tokens — la limite supérieure de la réponse générée. Le définir explicitement vous protège contre les générations incontrôlées et rend la latence prévisible.
  • stream — ici false, ce qui signifie que vous recevez un objet JSON lorsque la génération est terminée. Les sections suivantes abordent true.

Ce qui est renvoyé

La réponse est un objet JSON contenant un tableau choices. Le texte que vous voulez se trouve dans choices[0].message.content. Il y a aussi un bloc usage décrivant la consommation de tokens — enregistrez-le, car en facturation au token, c'est votre seul signal de coût par requête.

Si vous déboguez, faites passer la sortie dans un formateur pour la rendre lisible :

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

Placez le corps de la requête dans payload.json et utilisez -d @payload.json : dès que la charge utile dépasse quelques champs, cela évite les tracas de guillemets du shell.

Porter la requête en Python

L'objectif ici n'est pas un script de démonstration, mais une fonction importable. Gardez la charge utile strictement identique à la version curl — mêmes champs, mêmes noms, même chaîne de modèle — afin que le comportement ne change pas lorsque vous changez d'outil.

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 = "Tu es un assistant technique concis.",
    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"]

Puis :

print(chat("Résume en une phrase la différence entre PUT et PATCH."))

Pourquoi l'écrire ainsi

  • Utiliser json=payload plutôt que du JSON écrit à la main — requests sérialise correctement et définit le type de contenu, éliminant toute une catégorie de bugs de guillemets.
  • Un timeout explicite — sans lui, une connexion bloquée peut suspendre indéfiniment votre processus de travail. Pour de courtes complétions, trente secondes sont largement suffisantes ; pour les chemins interactifs, réduisez-la.
  • raise_for_status() le plus tôt possible — vous voulez que l'échec de la couche HTTP se manifeste comme exception à la frontière de l'appel, et non trois lignes plus loin sous forme de KeyError sur choices.
  • Configuration au niveau du module — la clé, l'URL de base et le modèle sont regroupés en un seul endroit. Pour tester d'autres modèles en A/B par la suite, il suffit de changer une constante.

Conversations multi-tours

Pour de vraies conversations, acceptez une liste de messages en paramètre plutôt que de construire deux messages fixes :

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

Ajoutez la réponse de l'assistant avec role: "assistant" dans messages pour poursuivre la conversation, et élaguez les anciens tours lorsque l'historique s'allonge — le contexte est facturé, donc un historique de conversation illimité augmente discrètement le coût de chaque requête.

Activer et consommer les réponses en streaming

Définissez "stream": true et le serveur enverra la réponse de manière incrémentale sous forme d'événements envoyés par le serveur, plutôt qu'un objet unique à la fin. Pour tout contenu qu'un utilisateur regarde, cela vaut le travail supplémentaire côté client : même si le temps de génération total reste inchangé, le temps jusqu'au premier token baisse nettement.

Vue côté curl

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": "Écris un haïku sur les nouvelles tentatives."}],
    "stream": true
  }'

-N désactive la mise en mémoire tampon de la sortie de curl, pour que vous voyiez réellement les événements arriver au fur et à mesure. Vous obtenez une suite de lignes, chacune commençant par data: et portant un fragment JSON. Le dernier événement est data: [DONE]. Traitez cette sentinelle comme marqueur de fin de flux, et non comme du JSON analysable.

Client Python

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)

Règles pour un streaming correct

  • Concaténer, pas remplacer. Chaque bloc ne porte que le nouveau fragment. Accumulez dans une liste puis faites un join final ; concaténer à une chaîne dans une boucle devient quadratique sur les longues sorties.
  • Se prémunir contre l'absence de contenu. Certains blocs ne portent que des métadonnées, donc delta peut ne pas avoir de clé content. Utilisez .get() et ignorez les valeurs vides.
  • Gérer les lignes incomplètes. Les frontières de trame peuvent couper une ligne. iter_lines s'en charge, mais si vous analysez vous-même le flux d'octets brut, mettez en mémoire tampon jusqu'à voir un saut de ligne.
  • Définir un timeout adapté au flux. Un flux total peut légitimement dépasser le timeout d'une requête courte. Utilisez un timeout de lecture plus long ou une échéance de lecture par bloc, plutôt que de désactiver complètement le timeout.
  • Conserver le chemin non-streaming. Lorsque vous n'avez besoin que du texte final d'une tâche en arrière-plan, stream: false est plus simple et coûte moins cher en inférence. Réservez le streaming aux chemins interactifs.

Interpréter les réponses d'erreur et concevoir les nouvelles tentatives

Une nouvelle tentative n'aide que si l'échec est temporaire. Réessayer aveuglément une requête mal formée ne fera qu'amplifier l'erreur. La distinction utile est celle entre les erreurs que vous corrigez dans le code et celles que le réseau ou le serveur résoudront d'eux-mêmes.

Classification par code de statut

Ne pas réessayer — corriger la requête :

  • 400 Bad Request — JSON mal formé, champ obligatoire manquant ou valeur de paramètre invalide. Lisez le message d'erreur, corrigez la charge utile et ajoutez un test pour éviter la récidive.
  • 401 Unauthorized — clé absente, mal formée ou révoquée. Vérifiez le format de l'en-tête Authorization et que la variable d'environnement est bien définie dans le processus d'exécution, pas seulement dans votre shell.
  • 403 Forbidden — la clé est valide, mais non autorisée à effectuer cette opération ou à utiliser ce modèle. Une boucle de nouvelles tentatives ici ne produit que du bruit.
  • 404 Not Found — généralement un chemin incorrect ou un identifiant de modèle inconnu. Vérifiez l'URL de base et la chaîne de modèle exacte.
  • Erreurs de validation de type 422 — type de paramètre correct mais valeur inacceptable (par exemple un temperature hors plage). Bornez la valeur dans le code.

Réessayer avec backoff :

  • 429 Too Many Requests — vous avez dépassé la limite de débit. Reculez, et si la réponse contient une indication retry-after, respectez-la plutôt que de deviner.
  • 500 / 502 / 503 / 504 — défaillance côté serveur ou passerelle. C'est exactement le cas d'usage du backoff exponentiel.
  • Erreurs de connexion et timeouts — la socket échoue avant la fin de la réponse. Réessayez, mais uniquement si l'opération peut être répétée sans risque.

Une boucle de nouvelles tentatives bien conçue

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"non réessayable {r.status_code}: {r.text[:200]}")
            if attempt == max_attempts:
                raise RuntimeError(f"tentatives épuisées, dernier statut {r.status_code}")
        delay = base_delay * (2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 0.5))
    raise RuntimeError("unreachable")

Deux détails importants en production

  • Le jitter n'est pas optionnel. Sans lui, une flotte de processus de travail heurtant simultanément la limite de débit réessaiera à l'unisson, recréant le pic. Le terme aléatoire ci-dessus les disperse.
  • Limiter le temps total, pas seulement le nombre de tentatives. Quatre tentatives avec backoff exponentiel peuvent dépasser votre échéance de requête. Limitez le nombre de tentatives pour que le pire cas reste dans le budget de l'appelant, et transmettez le temps restant comme timeout de la tentative suivante.

Ne réessayez pas une requête en streaming après un échec partiel, sauf si vous décidez du sort du texte déjà envoyé à l'utilisateur. Le schéma courant consiste à réessayer uniquement si rien n'a encore été affiché ; sinon, exposez la troncature.

Liste de vérification avant mise en production

Avant que ce code ne devienne une charge critique, parcourez une courte liste.

  • Des timeouts partout. Chaque requête a un timeout de connexion/lecture explicite, et cette valeur vient de votre budget de latence, pas d'une copie d'exemple.
  • Les secrets hors du dépôt. La clé API vient de l'environnement ou d'un gestionnaire de secrets, et n'est jamais écrite dans les logs. Purgez les en-têtes de tout enregistreur de requêtes.
  • Le nom du modèle centralisé. kimi-k3.1-pro-highspeed apparaît comme une constante unique, pour que vous puissiez le remplacer ou le tester en A/B sans rechercher-remplacer.
  • Les erreurs sont classifiées, pas avalées. Les chemins réessayables et non réessayables sont clairs dans le code, le backoff inclut du jitter, et le nombre de tentatives est plafonné.
  • Enregistrer l'usage. Consignez la consommation de tokens renvoyée par chaque réponse avec la latence et le statut. En facturation au token, c'est une alerte précoce quand le prompt devient discrètement trop volumineux.
  • Le chemin streaming est testé pour de vrai. Vérifiez qu'à prompt identique, la sortie concaténée est égale à la sortie non-streaming, et qu'une coupure en milieu de flux ne laisse pas votre UI dans un état corrompu.
  • Maîtriser les coûts par conception. Définissez toujours max_tokens, élaguez l'historique de conversation, résumez les longs documents avant de les insérer dans le contexte — ces trois leviers alignent dépense et valeur.

Une fois cela en place, passer de la preuve de concept curl à un appelant de production relève surtout de la configuration. Commencez par la fonction non-streaming, ajoutez le streaming lorsque le chemin interactif existe, et laissez l'enveloppe de nouvelles tentatives absorber les échecs que vous ne pouvez pas prévenir.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API