API Kimi K3.1 Pro : points de terminaison, appels d'outils, mise en cache et erreurs

L'API Kimi K3.1 Pro s'exécute à l'adresse https://api.moonshot.ai/v1 avec les identifiants de modèle kimi-k3.1-pro et kimi-k3.1-pro-highspeed. Elle prend en charge trois formats d'échange : OpenAI Chat Completions, l'API Responses et Anthropic Messages, si bien que les SDK que vous utilisez déjà fonctionnent avec une simple URL de base modifiée. Le modèle se débloque après un rechargement minimum de 1 $.

Ceci est la référence pour le code de production. Pour votre premier appel, le streaming et les configurations Codex ou Claude Code, lisez comment utiliser Kimi K3.1 Pro ; pour les coûts, consultez la tarification de Kimi K3.1 Pro. Les faits proviennent du guide de démarrage rapide K3.1 Pro de Moonshot et des documents liés, consultés le 24 octobre 2026.

Kimi K3.1 Pro : API Responses, API Anthropic et Chat Completions

Moonshot expose K3.1 Pro via trois surfaces d'API. Choisissez celle que votre bibliothèque cliente ou votre agent parle déjà ; le modèle, la clé et la facturation sont identiques sur les trois.

Ils diffèrent par la manière dont vous définissez le TTL du cache et par l'endroit où l'utilisation atterrit (voir la mise en cache ci-dessous). Vous venez de K3 ? Notre guide de l'API Kimi K3 s'applique toujours ; K3.1 Pro est un K3 post-entraîné avec le même contexte de 1 048 576 tokens.

Clé d'API Kimi K3.1 Pro : débloquer et vérifier l'accès

Vous avez besoin d'un compte approvisionné et d'une clé issue du bon produit. Quatre étapes :

1. Rechargez au moins 1 $ sur la plateforme Kimi API. K3.1 Pro est un modèle phare et ne se débloque qu'après un rechargement réussi.
2. Créez une clé dans la console des clés d'API et exportez-la sous le nom MOONSHOT_API_KEY.
3. Vérifiez que le modèle est visible pour cette clé avec GET /v1/models.
4. Appelez kimi-k3.1-pro depuis le code.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

Si le modèle n'est pas listé, corrigez cela en premier. Kimi API, Kimi Code et Kimi Membership sont des produits distincts : une clé Kimi Code ne fonctionnera pas sur le point de terminaison de l'API, et un abonnement ne se transforme pas en solde d'API.

Paramètres de requête importants pour K3.1 Pro

La plupart des paramètres OpenAI se comportent comme vous vous y attendez. Voici ceux qui diffèrent ou qui prennent les gens au dépourvu :

Les tokens de raisonnement comptent dans votre utilisation, alors utilisez "low" pour la classification et l'extraction. Le Preserved Thinking est toujours activé, donc chaque message assistant est renvoyé avec son reasoning_content intact (guide des modèles de réflexion).

Appel d'outils avec Kimi K3.1 Pro : une boucle complète en Python

Une boucle d'outils de production sur K3.1 Pro suit quatre règles issues de la documentation de Moonshot :

• Forcez un appel d'outil au premier tour avec tool_choice="required", puis passez à "auto".
• Ajoutez le message assistant complet, reasoning_content et tool_calls inclus.
• Envoyez un message tool par tool_call_id.
• Limitez le nombre de tours pour qu'un modèle confus ne puisse pas boucler indéfiniment.

import json, os
from openai import OpenAI

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

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

Le bug classique consiste à ajouter msg.content au lieu de msg, ce qui supprime tool_calls et reasoning_content.

L'appel d'outils à grande échelle avec search_tools

Lorsque votre agent dispose de dizaines ou de centaines d'outils, n'envoyez pas chaque définition à chaque requête. Les bonnes pratiques d'appel d'outils K3 de Moonshot recommandent ce flux :

1. Déclarez une fonction search_tools (implémentée par votre backend) ainsi que quelques outils principaux.
2. Définissez tool_choice: "required" au premier tour pour que le modèle récupère les outils avant de répondre.
3. Injectez les définitions d'outils correspondantes via un message system qui porte un champ tools.
4. Laissez le modèle appeler les outils chargés aux tours suivants, avec tool_choice repassé à "auto".

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

Les définitions injectées utilisent le format tools de premier niveau et s'appliquent à partir de ce message. Le serveur ne les conserve pas, alors gardez le message dans les requêtes suivantes. Ni la modification de tool_choice ni l'ajout d'une définition ne casse le cache de préfixe.

Entrée vision et vidéo

K3.1 Pro accepte des images et de la vidéo en plus du texte et renvoie du texte. Faites de content un tableau de parties : une partie image_url (l'exemple du guide de démarrage rapide envoie une URL de données base64, et précise que les URL d'images publiques ne sont pas prises en charge) ou une partie video_url qui pointe vers un fichier téléversé avec un ID ms://.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

Passez content comme message utilisateur, et supprimez le fichier avec client.files.delete(video.id) lorsque vous avez terminé.

La mise en cache du contexte en code

La mise en cache est automatique pour les préfixes répétés, avec un TTL par défaut de 5 minutes. Les hits de cache sont facturés 0,20 $ par million de tokens contre 2,00 $ pour une entrée non mise en cache, et une écriture d'une heure coûte 4,00 $ contre 2,00 $ pour 5 minutes. Sur un préfixe de 1 M de tokens, le TTL d'une heure s'amortit après deux hits.

Placez le contenu stable en premier (prompt système, définitions d'outils, docs), le contenu changeant en dernier, et aucun horodatage dans le préfixe. Avec le SDK openai, passez le TTL via extra_body :

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

L'API Anthropic définit le TTL avec un champ cache_control de premier niveau ; les marqueurs à l'intérieur des messages sont ignorés :

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

L'endroit où l'utilisation du cache apparaît dépend de la surface :

En streaming avec Chat Completions, définissez stream_options.include_usage=true pour obtenir l'utilisation dans le chunk final. Chaque hit renouvelle le TTL, qui est verrouillé lors de la première écriture. Règles complètes : le guide de mise en cache du contexte.

Erreurs et corrections de l'API Kimi K3.1 Pro

La plupart des échecs relèvent de six schémas. Vérifiez error.type à chaque 429, car la correction en dépend.

Attention aux nouvelles tentatives. Le SDK OpenAI réessaie 2 fois par défaut en cas d'erreurs de connexion, 408, 409, 429 et 5xx, donc un appel peut devenir trois requêtes comptées dans votre RPM. Sur un palier bas, réduisez le max_retries du client et gérez vous-même le backoff selon error.type. Les requêtes interrompues par un 429 ne sont pas facturées.

Si un agent tiers échoue, appelez l'API directement avec la même clé, le même point de terminaison et le même modèle. Si cela fonctionne, c'est l'outil qui pose problème. Consultez la page de dépannage et les codes d'erreur.

Limites de débit de Kimi K3.1 Pro par palier

Votre rechargement cumulé détermine votre palier sur la page des limites :

Le palier Tier0 autorise 3 requêtes par minute, et chaque tour d'une boucle d'outils est une requête. Une exécution d'agent en cinq tours dépasse déjà une minute à ce palier, alors prévoyez 10 $ cumulés avant de tester sérieusement des agents.

Tester le contrat de l'API Kimi avec Apidog CLI

Un test de contrat détecte le jour où votre boucle d'outils cesse de recevoir des tool_calls en retour. Laissez votre agent de codage le construire avec Apidog CLI. Installez et connectez-vous une fois :

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

Puis demandez à Claude Code, Codex ou l'agent que vous utilisez :

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

L'agent lit le schéma, valide sa charge utile et exécute le cas :

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

Les cas de test nécessitent une catégorie valide ; apidog test-case category --project <projectId> les liste. Une fois l'exécution réussie, remplacez -r cli,json par -r junit avec --out-dir et la même vérification bloquera votre CI, comme le montre notre guide CI/CD d'Apidog CLI. La configuration de l'agent se trouve dans Apidog CLI dans Claude Code. Le plan gratuit d'Apidog couvre jusqu'à 4 utilisateurs.

FAQ

Quelle est l'URL de base de l'API Kimi K3.1 Pro ?

https://api.moonshot.ai/v1 pour Chat Completions et l'API Responses, et https://api.moonshot.ai/anthropic pour l'API Messages compatible avec Anthropic.

L'API Kimi K3.1 Pro prend-elle en charge le paramètre thinking ?

Non. La réflexion est toujours activée. Contrôlez-la avec le champ reasoning_effort de premier niveau ("low", "high" ou "max").

Pourquoi est-ce que j'obtiens un 429 juste après avoir rechargé ?

Lisez error.type. engine_overloaded_error correspond à la capacité du serveur et un rechargement n'y changera rien. rate_limit_reached_error signifie que les limites de votre palier sont atteintes, et le palier Tier0 n'autorise que 3 RPM.

Comment savoir si la mise en cache fonctionne ?

Un champ de lecture du cache non nul dans usage indique un hit : prompt_tokens_details.cached_tokens sur Chat Completions ou cache_read_input_tokens sur Messages.

Existe-t-il un palier gratuit pour l'API Kimi K3.1 Pro ?

Non. L'API nécessite un rechargement minimum de 1 $. Le chat gratuit dans l'application Kimi est la voie à 0 $, abordée dans comment utiliser Kimi K3.1 Pro gratuitement. Pour en savoir plus sur le modèle, consultez ce qu'est Kimi K3.1 Pro.