L'API Kimi est compatible avec l'interface OpenAI ; lors d'une migration, seuls trois éléments changent généralement : l'URL de base, la clé API et le nom du modèle. Mais en 2026, plusieurs détails peuvent poser problème : d'anciens modèles ont été retirés, max_tokens est obsolète, K3 utilise par défaut l'intensité de raisonnement maximale, et l'usage d'une requête en streaming n'est renvoyé que dans le dernier bloc.

Cet article reprend l'intégration depuis zéro : choix du site et du protocole, sélection du modèle, premier appel curl et Python, puis checklist de migration et correspondance des erreurs. Les modèles et les prix sont ceux de la page Tarifs des modèles.

Remarque : Moonshot et Kimi sont des marques de leurs détenteurs respectifs ; cet article n'a qu'une vocation d'explication technique. La liste des modèles, la longueur de contexte et les règles de paramètres peuvent évoluer ; référez-vous à la version actuelle de la documentation du fournisseur.

1. Trois points à vérifier avant l'intégration

  1. Site : le site chinois utilise platform.kimi.com, le site international platform.kimi.ai. Les comptes, soldes et clés des deux sites sont totalement indépendants.
  2. Protocole : la plupart des projets utilisent Chat Completions compatible OpenAI ; un projet déjà équipé du SDK Anthropic peut passer par l'entrée compatible Messages.
  3. Modèle : vérifiez d'abord quels modèles sont visibles sur le compte, puis inscrivez-les dans le code. Ne recopiez pas un tutoriel vieux de plusieurs mois.

Le domaine de requête du site chinois est https://api.moonshot.cn, celui du site international https://api.moonshot.ai. Le domaine et la clé doivent correspondre : c'est l'une des causes les plus fréquentes de 401.

2. URL de base et chemins d'interface

Protocole URL de base Chemin
OpenAI Chat Completions https://api.moonshot.cn/v1 /chat/completions
OpenAI Responses https://api.moonshot.cn/v1 /responses
Anthropic Messages https://api.moonshot.cn/anthropic /v1/messages
Liste des modèles https://api.moonshot.cn/v1 /models
Consultation du solde https://api.moonshot.cn/v1 /users/me/balance

Pour le site international, remplacez le domaine par api.moonshot.ai ; les chemins restent identiques. Dans le SDK OpenAI, base_url s'arrête à /v1 et le SDK ajoute lui-même /chat/completions ; avec curl, il faut écrire le chemin complet. Mélanger les deux produit soit un /v1 en trop, soit un /v1 manquant, ce qui se traduit par une 404.

L'URL de base de l'entrée compatible Anthropic ne contient pas /v1, contrairement à l'entrée OpenAI. Pour utiliser Claude Code ou un autre SDK Anthropic, indiquez https://api.moonshot.cn/anthropic comme dans l'exemple du fournisseur.

3. Comment choisir le modèle

Nom du modèle Contexte Tâches adaptées Remarque
kimi-k3 1M Raisonnement complexe, ingénierie logicielle, travail intellectuel, documents très longs reasoning_effort par défaut à max
kimi-k2.7-code 256K Génération de code, questions sur un dépôt, agents Meilleure obéissance aux instructions sur contexte long
kimi-k2.7-code-highspeed 256K Complétion à faible latence, codage interactif Même modèle que la version standard, plus rapide
kimi-k2.6 256K Conversation générale, extraction, entrées visuelles et textuelles Prend en charge les modes avec et sans réflexion

Les anciens modèles ont été retirés : toute la série moonshot-v1 et kimi-k2.5 ont cessé d'être pris en charge le 31 août 2026, la série kimi-k2 le 25 mai 2026, et kimi-latest encore plus tôt. Les projets qui utilisent encore ces noms doivent migrer directement vers kimi-k3 ou la série K2, sans chercher d'ancienne documentation.

Les tâches générales n'ont pas besoin de K3 par défaut. K3 est puissant, mais son intensité de raisonnement par défaut augmente la latence et le nombre de tokens de sortie ; pour une classification simple ou une extraction à format fixe, kimi-k2.6 est souvent plus adapté. Réservez la série K2.7 Code aux tâches de code.

4. Premier appel : curl

export MOONSHOT_API_KEY="votre-clé"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Réponds seulement : intégration réussie"}
    ],
    "max_completion_tokens": 64
  }'

Un code 200 avec un contenu conforme indique que la clé, le site, le nom du modèle et le chemin sont corrects. En cas de 401, vérifiez d'abord la correspondance entre site et clé ; en cas de 404, vérifiez le nom du modèle et le /v1 ; en cas de 400, regardez si le message d'erreur mentionne le contexte ou la limite de sortie.

5. SDK Python et streaming

Installez le SDK OpenAI 1.0 ou une version ultérieure, puis modifiez base_url et la clé :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explique en trois points à quelles équipes convient une passerelle API"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nUsage :", chunk.usage)

La réponse en streaming est un flux SSE : chaque ligne commence par data: et se termine par data: [DONE]. Avec include_usage, un dernier bloc est renvoyé avant la fin, avec choices vide et seulement usage. Si la connexion est interrompue en cours de route, ce bloc peut ne pas arriver ; ne faites donc pas dépendre entièrement le comptage de consommation du client.

6. max_completion_tokens et intensité de raisonnement

max_tokens est obsolète : le nouveau code doit utiliser max_completion_tokens. Cette valeur désigne la longueur de sortie attendue, et non la longueur totale entrée plus sortie. La valeur par défaut de K3 est 131072, avec un maximum de 1048576 ; si l'entrée plus cette valeur dépasse la fenêtre de contexte, la requête renvoie invalid_request_error.

Deux règles pratiques :

  • Pour les tests et les tâches à format fixe, choisissez une valeur faible, par exemple 256 à 1024, pour éviter les sorties interminables.
  • À la limite, finish_reason vaut length ; une fin normale vaut stop. En voyant length, ne réessayez pas immédiatement : déterminez si la sortie a réellement besoin d'être plus longue ou si l'invite est trop ouverte.

K3 possède aussi un paramètre de premier niveau reasoning_effort, avec les valeurs low, high et max, par défaut max. Pour une tâche simple, low réduit la latence et la consommation de tokens ; pour un raisonnement complexe, montez d'un niveau. Avec le SDK OpenAI, si la version utilisée ne prend pas ce paramètre en charge, passez-le via extra_body. Le contenu de raisonnement de K3 se trouve dans reasoning_content et doit être renvoyé tel quel lors des conversations multi-tours et des appels d'outils.

7. Migrer depuis OpenAI ou une ancienne version de Moonshot

  1. Recensez tous les anciens noms de modèles dans le code et la configuration, et établissez une table de remplacement.
  2. Modifiez base_url : site chinois https://api.moonshot.cn/v1, site international https://api.moonshot.ai/v1.
  3. Utilisez la clé du site correspondant, sans réutilisation entre sites.
  4. Remplacez les noms de modèles par les modèles actuels de kimi-k3 ou de la série K2.
  5. Remplacez max_tokens par max_completion_tokens.
  6. Remplacez le réglage thinking de K2.x par reasoning_effort de K3, sans envoyer les deux en même temps.
  7. Ajoutez stream_options={"include_usage": True} aux requêtes en streaming.
  8. Rejouez un lot de tâches réelles et consignez la qualité, la latence, finish_reason et l'usage.
  9. Conservez l'ancienne configuration pendant un cycle de publication, puis supprimez-la après validation.

Ne basculez pas tout d'un coup. Commencez par l'environnement de test, puis les activités à faible risque, et enfin le chemin critique, avec un commutateur de retour arrière à chaque étape.

8. Correspondance des erreurs fréquentes

Code Type d'erreur Cause fréquente Traitement
400 invalid_request_error Paramètre erroné, contexte trop long, limite de sortie dépassée Corriger la requête
400 content_filter Entrée ou sortie bloquée par la sécurité du contenu Ajuster l'invite
401 invalid_authentication_error Clé invalide, site incompatible Changer de clé ou de domaine
404 resource_not_found_error Nom de modèle ou chemin erroné Consulter la liste des modèles
429 rate_limit_reached_error Concurrence, RPM, TPM ou TPD dépassé Réduire le débit ou augmenter le niveau
429 exceeded_current_quota_error Impayé ou solde insuffisant Recharger
504 Gateway Time-out Attente trop longue d'une requête longue non streamée Passer au streaming

Une requête non streamée peut renvoyer une 504 si le serveur attend plus de 900 secondes. Pour la génération de textes longs, l'analyse de documents longs et les agents de code, privilégiez le streaming : le client reçoit des données en continu et vous évitez de perdre du temps à attendre un timeout avant de réessayer.

Questions fréquentes

Jusqu'où faut-il renseigner l'URL de base ?

Avec le SDK OpenAI, indiquez https://api.moonshot.cn/v1, sans /chat/completions. Avec curl, écrivez l'adresse complète https://api.moonshot.cn/v1/chat/completions. Avec le SDK Anthropic, indiquez https://api.moonshot.cn/anthropic.

Pourquoi max_tokens ne fonctionne-t-il pas ?

Ce paramètre est obsolète ; certains modèles l'ignorent ou renvoient une erreur. Utilisez max_completion_tokens, en gardant à l'esprit qu'il s'agit d'une limite de sortie, et non d'une limite entrée plus sortie.

Pourquoi K3 répond-il plus lentement que prévu ?

K3 utilise par défaut reasoning_effort à max, ce qui déclenche un raisonnement approfondi. Pour une tâche simple, passez à low ou high et limitez la longueur de sortie ; la latence s'améliore généralement nettement.

Pourquoi l'usage manque-t-il après un streaming ?

Il faut définir explicitement stream_options={"include_usage": True}. Même dans ce cas, le dernier bloc peut être perdu si la connexion est interrompue ; en production, effectuez un comptage séparé côté serveur.

Que faut-il encore modifier lors d'une migration depuis OpenAI ?

La plupart des codes ne changent que l'URL de base, la clé et le nom du modèle. Vérifiez aussi max_tokens, l'usage en streaming, la correspondance des types d'erreur et la stratégie de nouvelle tentative, en particulier le traitement des 429.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, exécutez une tâche réelle avec kimi-k3 puis avec kimi-k2.6, et intégrez la production après validation. Les modèles disponibles et la facturation sont indiqués sur la page Tarifs des modèles.

À lire également :