Guide d’intégration API et d’utilisation agent de Kimi K3.1 Pro
Kimi K3.1 Pro est un modèle de la série K3.1 de Moonshot AI, destiné au code, à la création 3D, à la recherche financière et aux tâches longues pilotées par des agents. Son identifiant API officiel est kimi-k3.1-pro et l’URL de base de l’OpenAI SDK est https://api.moonshot.cn/v1. Le mode de réflexion est toujours activé ; l’intensité peut être réglée sur low, high ou max (valeur par défaut : max). Guide officiel de démarrage
Ce guide présente l’intégration, le raisonnement, la vision et les boucles d’outils selon la documentation officielle. Les résultats de référence publiés par Moonshot sont des évaluations du fournisseur, et non des tests réalisés par Guishu Intelligence.
Informations essentielles
| Élément | Information vérifiée |
|---|---|
| Identifiant officiel du modèle | kimi-k3.1-pro |
| URL de base API officielle | https://api.moonshot.cn/v1 |
| Intensité de raisonnement | low, high, max ; max par défaut |
| Mode de réflexion | Toujours activé |
| Contexte | La documentation officielle indique une prise en charge d’un million de tokens |
| Variante haute vitesse | kimi-k3.1-pro-highspeed ; modèle distinct, disponibilité et prix à vérifier dans le catalogue de la plateforme concernée |
| Date de vérification de la documentation | 2026-10-24 |
Les capacités et variantes ci-dessus proviennent de la documentation officielle de Kimi K3.1 Pro. Les versions, droits d’accès et tarifs peuvent évoluer ; consultez les prix des modèles pour connaître la disponibilité et les prix sur notre plateforme.
À quoi cette mise à niveau peut-elle servir ?
L’intérêt de K3.1 Pro réside dans les tâches en plusieurs étapes : comprendre les exigences, produire un artefact, vérifier le résultat, puis le modifier à partir des retours. Un contexte d’un million de tokens permet de fournir davantage de matériaux, mais la réussite d’une tâche longue dépend aussi des outils, de l’environnement et des critères d’acceptation. Les exemples ci-dessous portent sur le code, la création 3D et la recherche financière ; ils proviennent d’expériences tierces et de démonstrations du fournisseur, pas de nos propres exécutions.
Caméra 3D : vérifier que la structure évolue avec les paramètres
Dans son article « Les modèles chinois ont encore franchi un cap : test de Kimi K3.1 Pro », Liu Xiaopai a demandé à plusieurs modèles de créer une caméra interactive. Il rapporte que K3.1 Pro a généré 34 pièces sélectionnables et 9 lamelles de diaphragme, avec 35 mesures optiques conformes à ses critères. Au second tour, lorsque l’objectif est passé de 50 mm à 85 mm, le modèle a également modifié la géométrie au lieu de simplement remplacer l’étiquette.
Le même exemple présente des défauts : les unités d’exportation n’ont pas été traitées comme demandé et un problème subsistait dans l’espace entre le châssis et le diaphragme. Pour une tâche de conception, il est plus utile de vérifier ensemble les dimensions, l’interactivité, les fichiers exportés et la possibilité d’une modification ultérieure que de juger une seule image rendue. L’auteur a utilisé différents environnements d’outils de programmation ; ces observations ne constituent donc pas un classement à variables contrôlées.
Carte de jeu : créer un outil, puis laisser l’agent s’en servir
Le même auteur a aussi créé un éditeur de cartes Terraria dans le navigateur. Les blocs devaient respecter les règles du jeu et la carte exportée devait pouvoir être réutilisée dans le jeu. Il a ensuite demandé à K3.1 Pro de construire un décor au moyen de l’éditeur généré. Cette tâche associe compréhension de format de fichier, développement d’interface et manipulation d’outils ; elle se rapproche davantage d’un flux de travail réel que la génération d’un simple extrait de démonstration. L’auteur estime que Kimi et les modèles comparés ont chacun des qualités visuelles ; il s’agit d’une observation personnelle, pas d’un jugement esthétique universel.
Recherche financière : vérifier formules et références, pas seulement les conclusions
Les présentations de Zenan, Zhang Qian et Panda, de l’équipe éditoriale de jiqizhixin.com, rassemblent des exemples de modélisation financière, de rapports de recherche et d’ingénierie 3D. La documentation officielle montre aussi un modèle financier dont les hypothèses opérationnelles peuvent être ajustées ainsi qu’un rapport de recherche avec ses sources. Le point utile de ces exemples est la méthode de vérification : les formules se recalculent-elles après modification des hypothèses ? Les chiffres importants peuvent-ils être retracés jusqu’aux fichiers d’origine ? Chaque référence du rapport peut-elle être ouverte ? Une démonstration du fournisseur ne garantit pas l’exactitude pour n’importe quelle tâche financière. Présentation officielle des capacités et exemples
À la date de vérification de cet article, le fournisseur indique que les poids complets devraient être ouverts avant le 4 novembre. Il s’agit d’un calendrier prévisionnel, pas d’une publication déjà réalisée ; les fonctions 3D de l’application officielle ne doivent pas non plus être considérées comme un outil de modélisation intégré à l’API.
Appel API de base
L’exemple officiel utilise Python 3.9+ et l’OpenAI SDK. Stockez la clé API dans une variable d’environnement ; ne l’inscrivez pas dans le code source et ne la commitez pas dans le dépôt.
python3 -m pip install --upgrade 'openai>=1.0'
export MOONSHOT_API_KEY="your-api-key"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.cn/v1",
)
result = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explique en trois points comment concevoir un processus fiable de revue de code."}],
reasoning_effort="high",
)
print(result.choices[0].message.content)
Pour appeler directement Moonshot, utilisez une clé délivrée par Moonshot et l’URL de base officielle ci-dessus. Avec un service tiers compatible API, remplacez l’URL de base, la clé et l’identifiant du modèle par ceux fournis par ce service ; ne transmettez pas vos identifiants officiels à un tiers. Les modèles actuellement pris en charge et leur facturation chez Guishu Intelligence sont indiqués sur la page des prix.
Choisir l’intensité de raisonnement
K3.1 Pro reste toujours en mode réflexion ; reasoning_effort règle l’intensité du raisonnement et ne sert pas à activer ou désactiver ce mode. La documentation officielle propose low, high et max, avec max par défaut. Explication officielle de l’intensité de raisonnement
- Pour des réponses brèves ou des transformations aux exigences bien définies, commencez par
low. - Pour des modifications de code en plusieurs étapes, des analyses ou des tâches de planification, essayez d’abord
high. - Pour les tâches complexes qui demandent un raisonnement plus poussé, comparez la qualité, la latence et le coût réel de
max.
Ce sont des recommandations de flux de travail, pas des garanties de performance. En production, évaluez le taux de réussite, la latence et le coût sur vos propres tâches.
Conversations multi-tours : conserver le message assistant complet
Pour les conversations multi-tours et les retours d’outils, la documentation officielle demande d’ajouter au prochain appel le message assistant complet renvoyé par l’API, et non uniquement son texte content. Les champs structurés, notamment les appels d’outils, peuvent être nécessaires aux étapes suivantes. Documentation officielle sur les conversations multi-tours
messages = [{"role": "user", "content": "Présente d’abord le plan de migration, puis explique les risques."}]
first = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=messages,
reasoning_effort="high",
)
messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "Transforme la partie sur les risques en liste de contrôle."})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)
Si votre application doit conserver une session entre plusieurs requêtes, stockez les champs de message requis par le protocole et vérifiez dans la documentation officielle comment le SDK sérialise les objets de message.
Appels d’outils et boucle d’agent
L’application définit et exécute les outils : le modèle produit un appel, l’application en valide les paramètres, exécute la fonction réelle, puis renvoie le résultat au modèle. Ne traitez pas directement la sortie du modèle comme une commande fiable à exécuter.
import json
tools = [{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Consulter le statut d’une commande",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Consulte le statut de la commande A-104"}]
response = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
assistant = response.choices[0].message
messages.append(assistant) # Conserver le message assistant complet
for call in assistant.tool_calls or []:
args = json.loads(call.function.arguments)
# En production, valider d’abord les paramètres et les droits de l’utilisateur, puis appeler la fonction métier contrôlée.
tool_result = {"order_id": args["order_id"], "status": "processing"}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(tool_result),
})
final = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)
Le guide officiel des appels d’outils demande également de renvoyer chaque résultat avec le tool_call_id correspondant et de conserver le message assistant complet au tour suivant. L’application doit mettre en œuvre elle-même l’authentification, la validation des paramètres, les délais d’expiration, l’idempotence et l’audit.
Entrée visuelle : utiliser un tableau d’objets
Selon la documentation officielle, le content d’un message visuel est un tableau d’objets, et non une chaîne sérialisée. L’exemple transmet l’image sous forme de Data URL Base64 ; le flux de fichiers pris en charge peut également utiliser une référence ms://. Ne supposez pas que le modèle peut lire directement une URL d’image publique ordinaire. Instructions officielles pour l’entrée visuelle
import base64
from pathlib import Path
image_data = base64.b64encode(Path("diagram.png").read_bytes()).decode()
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {
"url": f"data:image/png;base64,{image_data}"
}},
{"type": "text", "text": "Décris les composants du système et leurs connexions dans le schéma."},
],
}],
)
print(response.choices[0].message.content)
Avant l’intégration, vérifiez les limites de format, de taille et d’interface de fichiers. Avant d’envoyer des images sensibles à un modèle externe, contrôlez également les règles de traitement des données de votre organisation.
Interpréter les références officielles et les expériences tierces
La documentation de Moonshot indique un score de 65,7 % pour K3.1 Pro sur Terminal-Bench 4.0 et présente une comparaison avec GPT-6 Astra et Claude Opus 5.5. Ces chiffres sont des résultats publiés par le fournisseur ; ils doivent être interprétés selon le jeu de tâches, la configuration de test et la date de publication. Ils ne permettent pas d’inférer le taux de réussite du modèle pour toutes les tâches de programmation. Présentation officielle du modèle et résultats
Le tiers Liu Xiaopai a partagé des expériences, notamment une caméra 3D interactive, et son appréciation personnelle des modèles comparés. Ce témoignage n’est ni un test de Guishu Intelligence ni un benchmark uniforme et reproductible. Pour évaluer un modèle, utilisez vos propres dépôts de code, contraintes de conception et exemples d’échec ; consignez les prompts, outils, tentatives, délais et coûts.
Liste de contrôle d’intégration
- Déterminez si l’appel est direct vers le fournisseur officiel ou passe par un service compatible, puis utilisez l’identifiant de modèle, l’URL de base et la clé correspondants.
- Commencez avec une intensité de raisonnement faible et comparez progressivement la qualité, la latence et la facture sur des tâches représentatives.
- Dans les scénarios multi-tours et agent, conservez le message assistant complet et associez correctement les résultats des outils.
- Construisez les messages visuels sous forme de tableaux d’objets ; pour les images locales, utilisez l’encodage ou le flux de fichiers officiellement pris en charge.
- Définissez des limites d’autorisation, la validation des paramètres, des délais d’expiration et une gestion des échecs pour l’exécution des outils.
- Avant le déploiement, vérifiez le catalogue actuel des modèles, les régions disponibles et les tarifs ; n’utilisez pas une ancienne configuration sans vérification.
Questions fréquentes
Quel est l’identifiant API de Kimi K3.1 Pro ?
La documentation officielle indique kimi-k3.1-pro. La variante haute vitesse s’écrit kimi-k3.1-pro-highspeed ; ne confondez pas les deux dans la configuration du modèle.
Quelle est l’intensité de raisonnement par défaut ?
La documentation officielle répertorie low, high et max, avec max par défaut. Le mode de réflexion du modèle est toujours activé.
Puis-je transmettre directement une URL d’image ?
La documentation officielle ne prend pas en charge les URL d’images publiques. Utilisez un tableau d’objets visuels avec une Data URL Base64, ou une référence ms:// selon le flux de fichiers.
Pourquoi un agent doit-il renvoyer le message assistant complet ?
Celui-ci peut contenir des champs structurés, comme des appels d’outils. Ne conserver que le texte ferait perdre des informations nécessaires à la suite de l’échange ; le résultat de l’outil doit aussi reprendre le tool_call_id correspondant.
Guishu Intelligence propose-t-elle Kimi K3.1 Pro ?
Consultez la page des prix pour les modèles, le routage et les tarifs actuellement disponibles sur la plateforme. Les capacités d’accès direct du fournisseur ne signifient pas automatiquement que le modèle ou sa variante haute vitesse est proposé ici.
Pour aller plus loin
Date de vérification des informations officielles : 2026-10-24. Les capacités du modèle, les paramètres API et les conditions d’accès peuvent évoluer ; référez-vous à la documentation Kimi API de Moonshot.