L'API Moonshot reste compatible avec l'interface OpenAI, mais deux changements sont intervenus en 2026 : l'entrée de la console a migré vers la plateforme Kimi API, et toute la série moonshot-v1 a été retirée le 31 août. Un ancien projet qui recopie sa configuration obtient souvent un 401 ou un 404 model_not_found. Cet article suit l'ordre « choisir le site, choisir le modèle, valider l'appel, migrer ». Les modèles et tarifs font foi sur Tarifs et modèles.

Note : Moonshot et Kimi sont des marques de leurs titulaires. Cet article est une présentation technique de l'intégration. 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 officielle.

I. L'entrée a changé, pas le domaine de l'API

platform.moonshot.cn redirige désormais vers platform.kimi.com, et le site international platform.moonshot.ai vers platform.kimi.ai. La console, les comptes, les soldes et les clés sont gérés dans la plateforme Kimi API.

Les domaines des requêtes API ne changent pas : https://api.moonshot.cn pour le site chinois, https://api.moonshot.ai pour l'international. Une clé du site chinois ne fonctionne qu'avec le domaine chinois, et inversement. Si base_url n'est pas défini dans le code, la requête peut partir vers OpenAI ou un autre fournisseur, avec l'erreur typique model_not_found. Mémorisez séparément « adresse de la console » et « adresse de l'API » pour éviter la confusion lors d'une migration.

II. Trois protocoles compatibles et leurs URL de base

  • OpenAI Chat Completions : URL de base https://api.moonshot.cn/v1, chemin /chat/completions.
  • OpenAI Responses : même URL de base, chemin /responses.
  • Anthropic Messages : URL de base https://api.moonshot.cn/anthropic, chemin /v1/messages.
  • Liste des modèles : GET https://api.moonshot.cn/v1/models.

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 ; le SDK ajoute le chemin de l'interface. Avec curl, indiquez le chemin complet. L'entrée Anthropic n'a pas de suffixe /v1, contrairement à l'entrée OpenAI. La documentation officielle exige OpenAI SDK 1.0.0 ou supérieur, Python 3.8+ ou Node.js 18+.

III. Choisir dans la famille de modèles actuelle

Nom du modèle Contexte Tâches adaptées Attention
kimi-k3 1M Raisonnement complexe, documents longs, agents, travail de connaissance reasoning_effort vaut max par défaut
kimi-k2.7-code 256K Génération de code, questions sur dépôt, agents de codage Réflexion toujours active, reasoning_effort non pris en charge
kimi-k2.7-code-highspeed 256K Complétion à faible latence, codage interactif Version rapide du même modèle, sortie plus rapide
kimi-k2.6 256K Dialogue général, extraction, multimodal Modes réflexion et non-réflexion

En cas de doute, commencez par kimi-k3 ; pour une classification simple ou une extraction à format fixe, kimi-k2.6 est souvent plus adapté ; pour le code, envisagez la série K2.7 Code.

Le piège le plus fréquent concerne les paramètres d'échantillonnage. La température est actuellement fixe : 1.0 pour K3 et K2.7 Code, 1.0 en mode réflexion et 0.6 en mode non-réflexion pour K2.6. Ne transmettez pas temperature explicitement : une valeur non fixe provoque une erreur. top_p est également fixé à 0.95 ; ne l'ajustez pas.

IV. Premier appel réussi avec curl

export MOONSHOT_API_KEY="votre_cle"

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épondez uniquement : intégration réussie"}
    ],
    "max_completion_tokens": 64
  }'

Un code 200 avec le contenu attendu confirme les quatre points : clé, site, nom de modèle et chemin. En cas de 401, vérifiez d'abord la cohérence entre site et clé ; en cas de 404, le nom de modèle, le /v1 et l'éventuel retrait du modèle ; en cas de 400, si le message mentionne le contexte ou la limite de sortie. Certaines intégrations imposent un nom spécifique, par exemple kimi-k3[1m] pour Claude Code ; référez-vous à la documentation de l'intégration.

V. SDK Python et sortie en streaming

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": "Expliquez 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("\nConsommation :", chunk.usage)

La réponse en streaming est au format SSE : chaque ligne commence par data: et se termine par data: [DONE]. Avec include_usage, un dernier bloc avec choices vide et seulement usage est renvoyé avant la fin ; si la connexion est interrompue, ce bloc peut manquer, et la production doit tenir une comptabilité côté serveur.

Pour le dialogue multi-tours et les appels d'outils, faites attention au contenu de réflexion. Le résultat de réflexion de K3 se trouve dans reasoning_content, et K2.x possède un champ similaire ; renvoyez-le tel quel dans le message assistant. K3 contrôle l'intensité via reasoning_effort au niveau supérieur ; pour K2.x, le paramètre thinking se transmet via extra_body. Ne les envoyez pas simultanément.

VI. Migrer depuis moonshot-v1

Les anciens modèles sont retirés ; un appel renvoie model_not_found. Les remplacements actuels sont les suivants, sous réserve de la liste officielle.

Ancien modèle Remplacement conseillé Remarque de migration
moonshot-v1-8k/32k/128k/auto kimi-k2.6 ou kimi-k3 La distinction de nom 8K/32K/128K disparaît
moonshot-v1-*-vision-preview kimi-k3 ou kimi-k2.6 Les images passent en blocs image_url
Série kimi-k2 kimi-k3 Retirée le 2026-05-25
kimi-k2.5 kimi-k3 Retirée le 2026-08-31
kimi-latest kimi-k3 Retirée le 2026-01-28

Étapes de migration :

  1. Recherchez globalement les anciens noms de modèles et les base_url dans le code et la configuration, et établissez la table de remplacement.
  2. Modifiez base_url en confirmant le site chinois ou international ; en cas de changement de site, changez aussi la clé.
  3. Remplacez le nom de modèle par kimi-k3 par défaut ; pour les tâches courtes sensibles au coût, évaluez kimi-k2.6.
  4. Remplacez max_tokens par max_completion_tokens. K3 vaut 131072 par défaut, avec une sortie maximale de 1048576 moins la longueur d'entrée ; la série K2 plafonne à environ 256K moins la longueur d'entrée.
  5. Supprimez temperature et top_p personnalisés et utilisez les valeurs fixes du modèle.
  6. Remplacez l'ancien réglage thinking par reasoning_effort pour K3, et transmettez thinking via extra_body pour K2.x.
  7. Convertissez les contenus multimodaux en blocs text, image_url et video_url.
  8. Ajoutez stream_options={"include_usage": True} aux requêtes en streaming.
  9. Faites une régression sur le même lot de tâches réelles, en relevant qualité, latence, finish_reason et consommation ; déployez progressivement avec un interrupteur de retour arrière.

Ne basculez pas tout d'un coup. Testez d'abord l'environnement de test, puis les activités à faible risque, enfin les chaînes critiques ; chaque étape doit pouvoir être annulée.

VII. Liste de vérification avant mise en production

  • Appelez GET /v1/models avec la même clé et confirmez que le modèle cible figure dans la liste.
  • Envoyez une requête minimale non-streaming et vérifiez le code 200 et le contenu.
  • Envoyez une requête en streaming et vérifiez la réception des incréments et du usage final.
  • Contrôlez finish_reason : stop pour une fin normale, length à la limite de sortie.
  • Comparez qualité, latence et consommation de tokens avant/après sur un jeu d'évaluation fixe.
  • Validez le retrait sur 429, les dépassements et le plafond de réessais, pour éviter que les réessais automatiques du SDK n'amplifient la concurrence.
  • Consignez dans les journaux l'heure, le nom de modèle, le code de statut et la consommation, pour le diagnostic et le rapprochement.

VIII. Correspondance des erreurs courantes

  • 401 invalid_authentication_error : clé invalide, supprimée, ou mélange de clés chinoise et internationale. Les clés de la plateforme ouverte et celles de Kimi Code ne sont pas interchangeables non plus.
  • 403 permission_denied_error : l'IP de sortie n'est pas dans la liste blanche, ou permissions de projet insuffisantes.
  • 404 model_not_found : base_url ne pointe pas vers Moonshot, nom de modèle erroné, modèle retiré, ou /v1 manquant dans le chemin.
  • 400 invalid_request_error : entrée plus limite de sortie supérieure au contexte, ou paramètre non pris en charge, comme une température personnalisée.
  • 400 content_filter : l'entrée ou la sortie déclenche la politique de sécurité ; ajustez l'invite ou le média.
  • 429 : engine_overloaded_error indique un serveur surchargé ; rate_limit_reached_error une limite d'organisation ; exceeded_current_quota_error souvent un solde insuffisant.
  • 504 ou délai de connexion : une requête longue non-streaming attend trop ; privilégiez le streaming pour les textes longs et les agents.

Le SDK OpenAI réessaie deux fois par défaut les requêtes en échec : un appel peut générer trois requêtes. Sur un compte à faible quota, réduisez d'abord le nombre de réessais et la concurrence avant d'examiner le quota.

Questions fréquentes

Peut-on encore utiliser moonshot-v1 ?

Non. Toute la série moonshot-v1 a été retirée le 31 août 2026 ; un appel renvoie model_not_found. Migrez vers kimi-k3 ou kimi-k2.6.

Jusqu'à quel niveau faut-il renseigner l'URL de base ?

SDK OpenAI : https://api.moonshot.cn/v1, sans /chat/completions. curl : chemin complet /v1/chat/completions. SDK Anthropic : https://api.moonshot.cn/anthropic.

Pourquoi transmettre temperature provoque-t-il une erreur ?

La température des modèles actuels est fixe : 1.0 pour K3 et K2.7 Code, valeur fixe selon le mode de réflexion pour K2.6. Ne transmettez pas de valeur personnalisée ; top_p est également fixé à 0.95.

Une clé du site chinois peut-elle appeler le site international ?

Non. Comptes, soldes et clés sont isolés par région ; un mélange renvoie généralement 401. Lors d'un changement de site, modifiez ensemble la clé, l'URL de base et le nom de modèle.

Pourquoi l'usage manque-t-il à la fin du streaming ?

Il faut définir explicitement stream_options={"include_usage": True}. Même ainsi, une interruption de connexion peut empêcher la réception du dernier bloc ; la production doit tenir ses propres statistiques côté serveur.

Pour aller plus loin

Créez d'abord une clé de test sur la passerelle IA ZSQH, exécutez une tâche réelle avec kimi-k3 puis avec kimi-k2.6, et intégrez la production une fois la chaîne validée. Les modèles disponibles et la facturation font foi sur Tarifs et modèles.

Lectures associées :