Comment utiliser l'API Kimi K3 ?

Moonshot AI a lancé Kimi K3 le 16 juillet 2026, le présentant comme son modèle le plus performant à ce jour : le premier modèle ouvert de classe 3T au monde, doté d'une architecture Mixture-of-Experts de 2,8 T paramètres et d'une fenêtre contextuelle de 1 048 576 tokens. Ce qui est intéressant pour les développeurs, ce n'est pas sa taille, mais son API. Kimi K3 utilise le dialecte SDK d'OpenAI, donc si vous utilisez déjà GPT ou tout autre endpoint compatible OpenAI, vous pouvez diriger le même client vers kimi-k3 et commencer à streamer les réponses en quelques minutes. Ce guide vous expliquera comment obtenir une clé, le démarrage rapide en Python, JavaScript et cURL, le streaming, les appels d'outils, le mode JSON, le paramètre configurable d'effort de raisonnement, et la mise en cache de contexte qui rend les entrées "cache-hit" environ dix fois moins chères que les "cache-miss". Ensuite, vous testerez et déboguerez ces appels dans Apidog afin de pouvoir visualiser la requête brute et les événements envoyés par le serveur au lieu de deviner.

En bref

L'ID du modèle API est kimi-k3. Sur OpenRouter, le slug est moonshotai/kimi-k3.
Le endpoint est compatible avec l'OpenAI-SDK. Définissez base_url, définissez api_key, définissez model="kimi-k3", c'est fait. Confirmez l'URL de base exacte dans la console à l'adresse platform.kimi.ai ; Kimi a historiquement utilisé https://api.moonshot.ai/v1.
La fenêtre contextuelle est de 1 million de tokens. La tarification est de 0,30 $ par million de tokens d'entrée "cache-hit", de 3,00 $ par million de tokens d'entrée "cache-miss", et de 15,00 $ par million de tokens de sortie.
Le streaming, les appels d'outils, le mode JSON, la sortie structurée et un paramètre reasoning_effort (max est disponible aujourd'hui) fonctionnent tous via le format standard des complétions de chat.
Les charges de travail de codage plus anciennes ou à budget limité peuvent encore mieux convenir à la ligne K2.7 ; une note sur le choix se trouve ci-dessous.
Importez la requête dans Apidog pour inspecter le streaming, déboguer les appels d'outils, stocker votre clé comme variable d'environnement, et faire des tests A/B entre kimi-k3 et kimi-k2-7-code.

Quel modèle Kimi devriez-vous appeler

Avant d'écrire du code, choisissez la bonne cible. Kimi K3 est le modèle de pointe de la famille : un grand MoE conçu pour le codage complexe, les tâches agendiques à long terme et les tâches de connaissance sur un contexte étendu. Il entraîne le coût de sortie par token le plus élevé de la gamme, et le billet de blog de lancement de Moonshot reconnaît que K3 est en deçà de Claude Fable 5 et GPT-5.6 Sol dans leurs comparaisons internes. Il est performant, mais pas un vainqueur incontestable, et son prix en tient compte.

Si votre charge de travail concerne un assistant de codage à fort volume, un rédacteur de tests CI, ou toute autre tâche où vous payez par appel à grande échelle, la ligne K2.7 Code, plus ancienne, est souvent mieux adaptée en termes de coût. Commencez par le guide de l'API Kimi K2.7 Code et l'aperçu Qu'est-ce que Kimi K2.7 Code pour voir si ce niveau correspond à votre cas. Pour une comparaison côte à côte des capacités et du prix, la comparaison Kimi K3 vs Kimi K2.7 Code expose les avantages de chacun. Optez pour kimi-k3 lorsque vous avez besoin d'une profondeur de raisonnement supplémentaire, du contexte complet de 1M, ou de l'orchestration d'outils agendiques ; passez à K2.7 lorsque la tâche est routinière et que le volume est élevé. Si vous souhaitez d'abord un aperçu complet des capacités, l'explication Qu'est-ce que Kimi K3 couvre l'architecture et le positionnement du modèle.

Obtenir une clé API sur la plateforme Kimi

Rendez-vous sur platform.kimi.ai et connectez-vous. La nouvelle console est l'endroit où vous créez des clés, surveillez l'utilisation et confirmez l'URL de base de votre compte.

Ouvrez la section des clés API de la console et créez une nouvelle clé.
Copiez-la une seule fois et stockez-la en lieu sûr. Vous ne reverrez plus sa valeur complète.
Ajoutez du crédit ou confirmez votre niveau de facturation afin que les appels à kimi-k3 ne soient pas rejetés pour solde insuffisant.
Notez l'URL de base affichée dans la console. Kimi a historiquement utilisé https://api.moonshot.ai/v1 ; la console est la source de vérité pour votre compte.

export KIMI_API_KEY="sk-your-key-here"

Cette seule habitude permet de garder les secrets hors de l'historique Git et des captures d'écran. Plus tard, lorsque vous effectuerez des tests dans Apidog, vous stockerez également la même valeur en tant que variable d'environnement, de sorte que la clé se trouvera exactement à deux endroits que vous contrôlez.

Pour une explication complète des calculs "cache-hit" versus "cache-miss" et de leur impact sur les factures mensuelles réelles, consultez le guide de tarification de Kimi K3.

Démarrage rapide : votre premier appel à kimi-k3

L'API de Kimi suit le contrat des complétions de chat d'OpenAI, de sorte que les SDK officiels d'OpenAI fonctionnent avec deux modifications : l'base_url et le model. Installez le SDK de votre choix, puis exécutez l'un des extraits ci-dessous.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Kimi est compatible avec l'OpenAI-SDK. Confirmez l'URL de base exacte dans la
    # console sur platform.kimi.ai ; Kimi a historiquement utilisé la valeur ci-dessous.
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Vous êtes un assistant de codage précis."},
        {"role": "user", "content": "Expliquez en un paragraphe ce qu'est un limiteur de débit à seau à jetons."},
    ],
)

print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Confirmez l'URL de base dans la console platform.kimi.ai.
  baseURL: "https://api.moonshot.ai/v1",
});

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "system", content: "Vous êtes un assistant de codage précis." },
    { role: "user", content: "Expliquez en un paragraphe ce qu'est un limiteur de débit à seau à jetons." },
  ],
});

console.log(response.choices[0].message.content);

cURL

curl "$KIMI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Expliquez en un paragraphe ce qu'est un limiteur de débit à seau à jetons."}
    ]
  }'

Définissez KIMI_BASE_URL à ce que la console indique (par exemple https://api.moonshot.ai/v1). Si l'une de ces requêtes renvoie un 401, la clé est incorrecte ou non définie. Un 404 sur le chemin signifie généralement que l'URL de base est erronée, et non que le modèle est manquant. La documentation du SDK OpenAI Python couvre les options du client plus en détail, et chaque option s'applique ici car le format de communication est le même.

Réponses en streaming

Pour les interfaces utilisateur de chat et les longues séquences d'agent, vous souhaitez recevoir les tokens au fur et à mesure de leur arrivée au lieu d'attendre l'achèvement complet. Définissez stream=True et itérez sur les deltas.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Écrivez un poème de 6 lignes sur les tests instables."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

En coulisses, il s'agit d'un flux d'événements envoyés par le serveur (SSE) : chaque ligne est une trame data: transportant un petit morceau de JSON, et le flux se termine par data: [DONE]. Le SDK vous masque ce cadrage, ce qui est pratique jusqu'à ce que quelque chose se casse en cours de flux et que vous ayez besoin de voir les trames brutes. C'est l'un des points où la section Apidog ci-dessous se justifie pleinement.

const stream = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Écrivez un poème de 6 lignes sur les tests instables." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Appels d'outils (appel de fonction)

Kimi K3 prend en charge les appels d'outils, les contraintes de choix d'outils et le chargement dynamique d'outils, ce qui vous permet de l'intégrer à des agents qui lisent des fichiers, appellent des API ou exécutent des commandes de terminal. Vous décrivez vos fonctions avec JSON Schema, le modèle décide quand en appeler une, et vous renvoyez le résultat via un message tool.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle pour une ville.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Nom de la ville, ex. Singapour"},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Quel temps fait-il à Singapour en ce moment ?"}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = first.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # get_weather
print(tool_call.function.arguments)  # {"city": "Singapore"}

Le modèle n'exécute pas votre fonction ; il vous transmet un nom et des arguments JSON. Vous exécutez le travail réel, puis renvoyez la sortie afin que le modèle puisse rédiger une réponse finale :

import json

# Ajoutez le tour de l'assistant qui a demandé l'outil, puis le résultat de l'outil.
messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps({"city": "Singapore", "temp_c": 31, "sky": "humid"}),
})

final = client.chat.completions.create(model="kimi-k3", messages=messages, tools=tools)
print(final.choices[0].message.content)

Définissez tool_choice="required" pour forcer un appel d'outil, ou passez un objet spécifique {"type": "function", "function": {"name": "get_weather"}} pour épingler une fonction. Ces contraintes maintiennent un agent sur la bonne voie lorsque vous savez déjà quel outil doit être déclenché.

Un piège spécifique à K3 qu'il est bon de connaître tôt : le modèle a été entraîné en mode "historique de pensée préservé". Si votre harnais d'agent supprime le raisonnement antérieur du modèle entre les tours, la qualité de la génération peut devenir instable. Lorsque vous construisez une boucle d'agent multi-tours, transmettez l'historique complet des messages plutôt que de tronquer les tours internes de l'assistant.

Mode JSON et sortie structurée

Lorsque vous avez besoin d'une sortie lisible par machine, demandez directement du JSON au lieu d'analyser du texte. Définissez response_format sur json_object et indiquez au modèle de renvoyer du JSON.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Ne renvoyez que du JSON valide. Pas de prose, pas de markdown."},
        {"role": "user", "content": "Extrayez le nom et le rôle de : 'Ada Lovelace, mathematician'."},
    ],
    response_format={"type": "json_object"},
)

print(response.choices[0].message.content)  # {"name": "Ada Lovelace", "role": "mathematician"}

Pour des garanties plus strictes, Kimi prend en charge la sortie structurée selon un schéma. Si votre version du SDK l'accepte, passez un format de réponse json_schema afin que le modèle se conforme à votre structure :

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Extrayez le nom et le rôle de : 'Ada Lovelace, mathematician'."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "personne",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"},
                },
                "required": ["name", "role"],
            },
        },
    },
)

Confirmez la prise en charge de json_schema pour votre compte dans la console avant de le déployer ; en cas de doute, json_object plus une étape de validation de votre côté est la solution de repli sûre. Kimi expose également un mode partiel et une recherche Internet, ce qui est utile lorsque vous souhaitez préremplir une réponse d'assistant ou fonder des réponses sur des données récentes.

Effort de raisonnement configurable

Kimi K3 expose un paramètre reasoning_effort qui contrôle l'intensité de la réflexion du modèle avant qu'il ne réponde. Aujourd'hui, le niveau disponible est max, qui est également la valeur par default ; Moonshot a indiqué que des niveaux inférieurs et supérieurs sont prévus. Une réflexion plus approfondie coûte plus de tokens de sortie et ajoute de la latence, c'est donc un levier à ajuster par tâche.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Planifiez une migration de REST vers GraphQL pour une API à 40 endpoints."}],
    reasoning_effort="max",
)

Si votre version du SDK OpenAI rejette le champ comme inconnu, passez-le plutôt par le "mécanisme d'échappement" (escape hatch) :

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Planifiez une migration de REST vers GraphQL."}],
    extra_body={"reasoning_effort": "max"},
)

Le modèle extra_body est la manière d'envoyer tout champ spécifique au fournisseur que le SDK de base ne modélise pas encore, ce qui est courant lorsqu'un endpoint compatible évolue plus rapidement que la bibliothèque cliente.

Tester et déboguer kimi-k3 dans Apidog

Le code du SDK masque le format de transmission, ce qui est bien jusqu'à ce qu'un appel d'outil renvoie une forme incorrecte ou qu'un flux soit interrompu et que vous ne puissiez pas déterminer si la faute vient de vous ou du endpoint. C'est là qu'un client API qui communique en HTTP brut est utile. Apidog vous permet d'envoyer la requête kimi-k3 exacte, de visualiser le flux SSE trame par trame, et de garder votre clé hors du corps de la requête. Si vous préférez tester les appels API sans vivre dans un terminal, c'est une boucle plus propre que de taper des commandes curl à l'aveugle ; le tutoriel Tester les API sans Postman couvre le flux de travail général.

Voici une boucle ciblée pour kimi-k3 :

Créez une nouvelle requête HTTP dans Apidog. Définissez la méthode sur POST et l'URL sur votre URL de base plus /chat/completions.
Stockez votre clé comme variable d'environnement. Dans les paramètres d'environnement d'Apidog, ajoutez KIMI_API_KEY, puis définissez l'en-tête Authorization sur Bearer {{KIMI_API_KEY}}. Désormais, le secret est référencé, et non collé, et vous pouvez basculer entre les clés de test et de production en changeant d'environnement.
Collez un corps JSON avec "model": "kimi-k3" et votre tableau de messages. Envoyez-le et lisez la réponse complète, y compris l'utilisation des tokens, afin de pouvoir voir les décomptes "cache-hit" versus "cache-miss" sur les appels réels.
Passez "stream": true et observez les événements envoyés par le serveur arriver sous forme de trames distinctes. Voir les fragments data: bruts rend les bogues de streaming évidents d'une manière que l'itérateur ordonné du SDK ne permet pas.
Déboguez les appels d'outils en inspectant le tableau tool_calls dans la réponse. Lorsque les arguments reviennent mal formés, vous pouvez voir si le modèle a produit du mauvais JSON ou si votre schéma était ambigu, et corriger la description sur-le-champ.
Comparez A/B avec kimi-k2-7-code. Dupliquez la requête, ne modifiez que le champ model, et comparez la latence, la qualité de la sortie et le coût sur la même requête (prompt). C'est le moyen le plus rapide et le plus honnête de décider si le raisonnement supplémentaire de K3 vaut le coût supplémentaire pour votre tâche.

Étant donné qu'Apidog importe directement les requêtes compatibles OpenAI, vous pouvez coller une commande cURL et obtenir une requête enregistrée et rejouable avec les en-têtes et le corps déjà remplis. À partir de là, cela devient un cas de test partagé que votre équipe peut réexécuter chaque fois que Kimi publie une mise à jour. Si votre agent communique avec le modèle via MCP, le guide de débogage visuel avec le client Apidog MCP explique également comment tracer ces appels. Téléchargez Apidog si vous souhaitez suivre ce processus avec votre propre clé.

Cas d'utilisation réels

Quelques modèles correspondent parfaitement à l'objectif de kimi-k3 :

Agents de codage à l'échelle du dépôt. Le contexte de 1M et l'orchestration d'outils agendiques permettent au modèle de gérer une grande base de code, d'exécuter des tests, de lire des journaux et d'itérer. Mettez en cache le condensat de la base de code comme préfixe stable et vous maintiendrez le coût par tour raisonnable.
Travail de connaissance sur des documents longs. Alimentez une spécification complète, un contrat ou un corpus de recherche et demandez une extraction structurée avec json_schema. Gardez le document au début de la requête (prompt) afin que les requêtes répétées bénéficient de la mise en cache.
Planification de migration et de refactorisation. Définissez reasoning_effort sur max pour la phase de planification, où une réflexion plus approfondie est rentable, puis revenez à un modèle moins cher pour les modifications mécaniques.
Réponses de recherche fondées. Avec la recherche Internet et les appels d'outils, K3 peut extraire des données récentes et les citer, ce qui convient aux assistants qui ne peuvent pas se fier à des connaissances d'entraînement obsolètes.

Dans chacun de ces cas, le flux de travail est le même : construisez la requête avec le SDK, vérifiez le comportement brut dans Apidog, puis intégrez-le à votre application une fois que vous faites confiance à sa structure.

En résumé

Appeler Kimi K3 se résume à trois réglages sur un client compatible OpenAI : l'URL de base de votre console, votre clé API, et model="kimi-k3". À partir de là, le streaming, les appels d'outils, le mode JSON, la sortie structurée et le reasoning_effort suivent tous le contrat de "chat-completions" que vous connaissez déjà. Les deux points à bien comprendre sont l'économie de la mise en cache, où conserver un préfixe stable transforme une entrée de 3,00 $ en une entrée de 0,30 $, et le compromis honnête selon lequel K3 offre une profondeur de raisonnement à un coût réel, il est donc préférable de diriger les tâches routinières à fort volume vers la ligne K2.7. Construisez la requête dans le code, validez-la dans Apidog, et vous déploierez avec kimi-k3 sans surprises.

FAQ

Quel est l'ID du modèle API pour Kimi K3 ? C'est kimi-k3 sur la propre plateforme de Kimi. Si vous l'appelez via OpenRouter, le slug est moonshotai/kimi-k3. Vous pouvez consulter la fiche du modèle sur OpenRouter à l'adresse openrouter.ai/moonshotai/kimi-k3.

Quelle URL de base dois-je utiliser ? Confirmez-la dans la console à l'adresse platform.kimi.ai, car c'est la source de vérité pour votre compte. Kimi a historiquement utilisé https://api.moonshot.ai/v1. Dans le code, gardez-la comme une variable base_url que vous définissez depuis la console plutôt que de la coder en dur.

Kimi K3 est-il compatible avec le SDK OpenAI ? Oui. L'API suit le format des complétions de chat d'OpenAI, de sorte que les SDK officiels Python et JavaScript d'OpenAI fonctionnent après avoir modifié base_url et model. Les champs spécifiques au fournisseur passent par extra_body.

Combien coûte l'API Kimi K3 ? 0,30 $ par million de tokens d'entrée "cache-hit", 3,00 $ par million de tokens d'entrée "cache-miss", et 15,00 $ par million de tokens de sortie. La structuration des requêtes pour la réutilisation du cache est le levier le plus important pour réduire votre facture. Le guide de tarification de Kimi K3 explique les chiffres.

Que fait réellement la mise en cache de contexte ? Lorsque les tokens de début de votre requête correspondent à une requête précédente, le endpoint réutilise un état calculé au lieu de le recalculer, ce qui réduit le coût d'entrée de 3,00 $ à 0,30 $ par million sur cette partie. Gardez votre "prompt" système et votre contexte partagé au début et identiques d'un appel à l'autre pour maximiser les "cache-hits".

Puis-je contrôler l'intensité de la réflexion du modèle ? Oui, via reasoning_effort. Le niveau disponible aujourd'hui est max, qui est également la valeur par défaut ; Moonshot a indiqué que d'autres niveaux sont prévus. Un effort plus élevé coûte plus de tokens de sortie et ajoute de la latence.

Dois-je utiliser Kimi K3 ou Kimi K2.7 Code ? Utilisez kimi-k3 lorsque vous avez besoin d'un raisonnement profond, du contexte complet de 1M, ou de l'orchestration d'outils agendiques. Pour les tâches de codage routinières à fort volume, la ligne K2.7, moins chère, est souvent un meilleur choix. La comparaison Kimi K3 vs Kimi K2.7 Code et le guide de l'API Kimi K2.7 Code vous aideront à décider.

Comment déboguer une réponse de streaming ou d'appel d'outil défectueuse ? Envoyez la requête brute dans Apidog avec "stream": true et lisez les événements envoyés par le serveur trame par trame, ou inspectez le tableau tool_calls pour voir si le modèle a renvoyé du JSON mal formé. Le stockage de votre clé en tant que variable d'environnement la maintient hors du corps de la requête pendant que vous testez.