DEV Community

Cover image for Comment utiliser l'API Kimi K3 ?
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API Kimi K3 ?

Moonshot AI a lancé Kimi K3 le 16 juillet 2026 comme son modèle le plus performant à ce jour : un modèle ouvert de classe 3T, basé sur une architecture Mixture-of-Experts de 2,8 T de paramètres, avec une fenêtre contextuelle de 1 048 576 tokens. Pour les développeurs, l’essentiel est son API compatible avec le SDK OpenAI : si votre application appelle déjà GPT ou un endpoint compatible OpenAI, remplacez l’URL de base, utilisez model="kimi-k3" et commencez à générer des réponses. Ce guide couvre l’obtention d’une clé, les premiers appels en Python, JavaScript et cURL, le streaming, les outils, le JSON, reasoning_effort, la mise en cache de contexte et le débogage des requêtes brutes dans Apidog.

Essayez Apidog dès aujourd’hui

En bref

  • L’ID du modèle est kimi-k3. Sur OpenRouter, utilisez moonshotai/kimi-k3.
  • L’API utilise le format OpenAI Chat Completions. Configurez base_url, api_key et model="kimi-k3".
  • Confirmez l’URL de base dans platform.kimi.ai. Kimi a historiquement utilisé https://api.moonshot.ai/v1.
  • La fenêtre contextuelle atteint 1 million de tokens.
  • La tarification indiquée est de 0,30 $ par million de tokens d’entrée en cache-hit, 3,00 $ en cache-miss et 15,00 $ par million de tokens de sortie.
  • Le streaming, les appels d’outils, le mode JSON, la sortie structurée et reasoning_effort fonctionnent avec le format Chat Completions.
  • Pour les charges de travail de code répétitives ou à fort volume, K2.7 Code peut être plus économique.
  • Utilisez Apidog pour inspecter les requêtes HTTP, les trames SSE et comparer kimi-k3 à kimi-k2-7-code.

Quel modèle Kimi appeler ?

Choisissez le modèle avant d’intégrer l’API.

Kimi K3 cible les tâches de codage complexes, les agents sur plusieurs étapes et le travail de connaissance sur un contexte très long. Son coût de sortie est le plus élevé de la gamme. Le billet de lancement de Kimi K3 précise également que, dans les comparaisons internes de Moonshot, K3 reste derrière Claude Fable 5 et GPT-5.6 Sol sur certains scénarios.

Comparaison de modèles Kimi

Utilisez kimi-k3 lorsque votre tâche nécessite :

  • un raisonnement plus approfondi ;
  • le contexte complet de 1M tokens ;
  • l’orchestration d’outils dans un agent ;
  • l’analyse de documents ou de dépôts volumineux.

Pour un assistant de code à fort volume, un générateur de tests CI ou des transformations mécaniques, K2.7 Code peut offrir un meilleur rapport coût/qualité. Consultez :

Obtenir une clé API sur la plateforme Kimi

Connectez-vous à platform.kimi.ai. La console permet de créer des clés, de suivre l’utilisation et de vérifier l’URL de base associée à votre compte.

Console Kimi

  1. Ouvrez la section des clés API.
  2. Créez une clé.
  3. Copiez-la immédiatement : sa valeur complète ne sera plus affichée.
  4. Vérifiez votre crédit ou votre configuration de facturation.
  5. Relevez l’URL de base affichée dans la console.

Exportez la clé dans votre environnement local :

export KIMI_API_KEY="sk-your-key-here"
Enter fullscreen mode Exit fullscreen mode

Évitez de placer une clé dans le code source, les fichiers commités, les captures d’écran ou les commandes partagées. Lors des tests dans Apidog, stockez aussi cette valeur dans une variable d’environnement.

Pour comprendre l’impact financier des entrées cache-hit et cache-miss, consultez le guide de tarification de Kimi K3.

Démarrage rapide : premier appel à kimi-k3

Kimi utilise le contrat OpenAI Chat Completions. Dans un client OpenAI existant, les changements principaux sont :

  1. définir l’URL de base Kimi ;
  2. fournir KIMI_API_KEY ;
  3. sélectionner model="kimi-k3".

Python

Installez le SDK :

pip install openai
Enter fullscreen mode Exit fullscreen mode

Puis envoyez une requête :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Confirmez cette URL dans platform.kimi.ai.
    # Kimi a historiquement utilisé cette valeur.
    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)
Enter fullscreen mode Exit fullscreen mode

JavaScript / TypeScript

Installez le SDK :

npm install openai
Enter fullscreen mode Exit fullscreen mode

Envoyez ensuite la requête :

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);
Enter fullscreen mode Exit fullscreen mode

cURL

Gardez l’URL de base dans une variable :

export KIMI_BASE_URL="https://api.moonshot.ai/v1"
Enter fullscreen mode Exit fullscreen mode

Puis appelez l’endpoint :

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Diagnostiquer les erreurs courantes

Erreur Cause probable Action
401 Unauthorized Clé absente, invalide ou expirée Vérifiez KIMI_API_KEY et la configuration du compte
404 Not Found URL de base ou chemin incorrect Vérifiez l’URL affichée dans la console Kimi
Requête refusée pour solde insuffisant Crédit ou facturation non configurés Ajoutez du crédit ou confirmez votre niveau de facturation

La documentation du SDK OpenAI Python couvre les options de client applicables à cette intégration compatible.

Réponses en streaming

Pour un chat ou un agent, activez le streaming afin d’afficher les tokens dès leur génération au lieu d’attendre la réponse complète.

Streaming en Python 

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)
Enter fullscreen mode Exit fullscreen mode

Streaming en JavaScript 

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 ?? "");
}
Enter fullscreen mode Exit fullscreen mode

Sous le capot, la réponse est un flux SSE (Server-Sent Events). Chaque trame contient une ligne data: avec un fragment JSON et le flux se termine généralement par :

data: [DONE]
Enter fullscreen mode Exit fullscreen mode

Le SDK masque ces détails. C’est pratique en production, mais moins utile lorsqu’un flux est interrompu ou mal formé. Dans ce cas, inspectez les trames HTTP brutes dans Apidog.

Appels d’outils

Kimi K3 prend en charge les appels d’outils. Vous décrivez les fonctions disponibles avec JSON Schema, le modèle demande un outil, votre application exécute l’action puis renvoie le résultat dans un message tool.

Le modèle ne lance pas votre fonction lui-même.

1. Déclarer un outil 

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)
print(tool_call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

Exemple de sortie attendue :

get_weather
{"city": "Singapore"}
Enter fullscreen mode Exit fullscreen mode

2. Exécuter l’outil et retourner son résultat

Votre application doit valider les arguments, appeler le service réel et envoyer le résultat au modèle.

import json

# Conservez le message assistant qui contient la demande d'outil.
messages.append(first.choices[0].message)

# Ajoutez le résultat produit par votre application.
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)
Enter fullscreen mode Exit fullscreen mode

Forcer ou sélectionner un outil

Forcez l’utilisation d’un outil :

tool_choice="required"
Enter fullscreen mode Exit fullscreen mode

Forcez une fonction précise :

tool_choice={
    "type": "function",
    "function": {
        "name": "get_weather"
    }
}
Enter fullscreen mode Exit fullscreen mode

Utilisez ces contraintes lorsqu’une étape de votre agent doit obligatoirement appeler une fonction connue.

K3 a été entraîné avec un historique de pensée préservé. Dans une boucle d’agent multi-tours, conservez l’historique complet des messages plutôt que de supprimer les tours internes de l’assistant. Supprimer ce contexte peut rendre la qualité de génération instable.

Mode JSON et sortie structurée

Lorsque votre application doit consommer la réponse, demandez du JSON plutôt que d’analyser une réponse en prose.

JSON simple avec json_object 

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"}
Enter fullscreen mode Exit fullscreen mode

Validez toujours le JSON côté application avant de l’utiliser :

import json

data = json.loads(response.choices[0].message.content)

assert isinstance(data["name"], str)
assert isinstance(data["role"], str)
Enter fullscreen mode Exit fullscreen mode

Sortie structurée avec json_schema

Si votre version du SDK et votre compte prennent en charge json_schema, imposez une 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"],
            },
        },
    },
)
Enter fullscreen mode Exit fullscreen mode

Confirmez la disponibilité de json_schema dans votre console avant le déploiement. En solution de repli, utilisez json_object et une validation applicative stricte.

Kimi expose également un mode partiel et une recherche Internet, utiles pour préremplir une réponse ou traiter des données récentes.

Configurer l’effort de raisonnement

Kimi K3 expose reasoning_effort, qui contrôle l’intensité de réflexion avant la réponse.

Le niveau actuellement disponible est max, qui est également la valeur par défaut. Moonshot a indiqué que d’autres niveaux sont prévus. Un raisonnement plus intensif augmente la latence et le nombre de tokens de sortie : utilisez-le surtout pour les tâches où cette profondeur apporte une vraie valeur.

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",
)
Enter fullscreen mode Exit fullscreen mode

Si votre SDK OpenAI rejette ce champ, passez-le via extra_body :

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

extra_body permet d’envoyer des champs spécifiques au fournisseur avant leur prise en charge native dans le SDK.

Tester et déboguer Kimi K3 dans Apidog

Les SDK simplifient les appels, mais masquent aussi le détail HTTP. Si un appel d’outil renvoie une structure inattendue ou si un flux SSE s’interrompt, inspecter la requête brute accélère le diagnostic.

Apidog permet d’envoyer la requête exacte vers kimi-k3, de visualiser les événements SSE trame par trame et de stocker la clé dans un environnement plutôt que dans le corps de la requête. Pour le workflow général, consultez le tutoriel Tester les API sans Postman.

Débogage d’une requête dans Apidog

Workflow de test

  1. Créez une requête HTTP POST.
  2. Définissez son URL sur : 
   {{KIMI_BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. Ajoutez les en-têtes : 
   Authorization: Bearer {{KIMI_API_KEY}}
   Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Placez KIMI_API_KEY et KIMI_BASE_URL dans un environnement Apidog.
  2. Envoyez une requête minimale : 
   {
     "model": "kimi-k3",
     "messages": [
       {
         "role": "user",
         "content": "Résumez le fonctionnement d'un rate limiter."
       }
     ]
   }
Enter fullscreen mode Exit fullscreen mode
  1. Inspectez la réponse et les métriques d’utilisation afin de comparer les entrées cache-hit et cache-miss.
  2. Ajoutez "stream": true pour afficher les trames SSE distinctes.
  3. Ajoutez tools pour inspecter directement le tableau tool_calls.
  4. Dupliquez la requête, remplacez uniquement "model": "kimi-k3" par "model": "kimi-k2-7-code" et comparez qualité, latence et coût.

Apidog peut importer directement une requête cURL compatible OpenAI. Collez une commande, enregistrez la requête et transformez-la en test rejouable par toute l’équipe.

Si votre agent utilise MCP, consultez le guide de débogage visuel avec le client Apidog MCP. Vous pouvez également télécharger Apidog pour reproduire ces tests avec votre propre clé.

Cas d’utilisation adaptés à Kimi K3

Agents de codage à l’échelle d’un dépôt

Le contexte de 1M tokens et les appels d’outils permettent à un agent de lire une base de code importante, lancer des tests, consulter des journaux et itérer sur des correctifs.

Pour contenir le coût :

  • placez le contexte stable du dépôt au début des messages ;
  • conservez ce préfixe identique entre les requêtes ;
  • tirez parti des cache-hits ;
  • utilisez K3 pour la planification et les décisions complexes, puis un modèle moins coûteux pour les modifications mécaniques.

Analyse de documents longs

Envoyez une spécification, un contrat ou un corpus de recherche, puis extrayez des données structurées avec json_schema.

Pour maximiser le cache :

  • placez le document partagé au début du prompt ;
  • ajoutez la question variable après ce préfixe ;
  • évitez de reformater inutilement le contexte entre les appels.

Planification de migration ou de refactorisation

Utilisez reasoning_effort="max" pour produire un plan de migration REST vers GraphQL, une stratégie de découpage de monolithe ou une analyse de dépendances. Réservez ensuite les opérations répétitives à un modèle plus économique.

Réponses fondées sur des données récentes

Avec la recherche Internet et les appels d’outils, K3 peut intégrer des données externes récentes dans une réponse. Ce workflow convient aux assistants qui ne peuvent pas s’appuyer uniquement sur des connaissances d’entraînement potentiellement obsolètes.

En résumé

L’intégration de Kimi K3 repose sur trois réglages :

  1. récupérez l’URL de base dans la console Kimi ;
  2. fournissez votre clé API ;
  3. utilisez model="kimi-k3".

Le streaming, les outils, le JSON, les sorties structurées et reasoning_effort suivent ensuite le contrat OpenAI Chat Completions.

Les deux optimisations importantes sont :

  • conserver un préfixe de prompt stable pour profiter du cache et faire passer l’entrée de 3,00 $ à 0,30 $ par million de tokens sur la partie concernée ;
  • router les tâches routinières à fort volume vers K2.7 lorsque le raisonnement supplémentaire de K3 ne justifie pas son coût.

Construisez l’appel avec le SDK, validez le comportement HTTP brut dans Apidog, puis industrialisez l’intégration.

FAQ

Quel est l’ID API de Kimi K3 ?

L’ID est kimi-k3 sur la plateforme Kimi. Sur OpenRouter, utilisez moonshotai/kimi-k3. La fiche est disponible sur openrouter.ai/moonshotai/kimi-k3.

Quelle URL de base utiliser ?

Vérifiez l’URL de base affichée dans platform.kimi.ai, qui reste la source de vérité pour votre compte. Kimi a historiquement utilisé https://api.moonshot.ai/v1. Gardez cette valeur dans une variable de configuration plutôt que de la coder en dur.

Kimi K3 est-il compatible avec le SDK OpenAI ?

Oui. L’API suit le format OpenAI Chat Completions. Les SDK OpenAI Python et JavaScript fonctionnent après la modification de base_url et model. Les champs spécifiques au fournisseur peuvent être transmis avec extra_body.

Combien coûte l’API Kimi K3 ?

La tarification indiquée est de 0,30 $ par million de tokens d’entrée en cache-hit, 3,00 $ par million de tokens d’entrée en cache-miss et 15,00 $ par million de tokens de sortie. Consultez le guide de tarification Kimi K3 pour le détail.

Que fait la mise en cache de contexte ?

Lorsque le début d’une requête correspond à celui d’une requête précédente, l’endpoint peut réutiliser un état déjà calculé. Le coût d’entrée de cette partie peut alors passer de 3,00 $ à 0,30 $ par million de tokens. Gardez le prompt système et le contexte partagé au début des messages, sans les modifier entre les appels.

Puis-je contrôler l’intensité de réflexion ?

Oui, avec reasoning_effort. Le niveau actuellement disponible est max, également utilisé par défaut. Un effort plus élevé augmente le nombre de tokens de sortie et la latence.

Faut-il choisir Kimi K3 ou Kimi K2.7 Code ?

Choisissez kimi-k3 pour le raisonnement profond, le contexte de 1M tokens et l’orchestration d’outils. Pour le code routinier à fort volume, K2.7 est souvent plus rentable. Consultez Kimi K3 vs Kimi K2.7 Code et le guide de l’API Kimi K2.7 Code.

Comment déboguer un streaming ou un appel d’outil défectueux ?

Envoyez la requête brute dans Apidog avec "stream": true pour inspecter les trames SSE. Pour les outils, examinez tool_calls afin de déterminer si le problème provient des arguments JSON générés ou d’un schéma ambigu. Stockez la clé dans une variable d’environnement pour éviter de l’exposer pendant les tests.

Top comments (0)