Guide de l’API Kimi K3 : Python, vision, outils et contexte de 1M tokens

Guide développeur de l’API Kimi K3

Kimi K3 est disponible via l’API Chat Completions compatible OpenAI de Moonshot AI avec l’identifiant de modèle kimi-k3. L’API prend en charge le raisonnement activé en permanence, le streaming, les images, les vidéos importées, le schéma JSON strict, les outils personnalisés, le chargement dynamique d’outils et une fenêtre de contexte d’1 million de tokens.

La compatibilité ne signifie pas un comportement identique. K3 utilise des valeurs d’échantillonnage fixes, exige de conserver l’état complet de l’assistant lors des tours suivants avec outils ou conversations, et gère le raisonnement séparément du contenu final. Ce guide se concentre sur ces points spécifiques.

Disponibilité et tarifs mis à jour le 22 juillet 2026. Kimi K3 est disponible sur Poyo.ai sous l’identifiant kimi-k3 via l’API Chat Completions compatible OpenAI. Le tarif est de $2.28 par million de tokens d’entrée et $11.40 par million de tokens de sortie, soit 24 % moins cher que le tarif officiel.

Prérequis

Vous avez besoin de :

Python 3.9 ou version ultérieure ;
du package Python openai version 1.0 ou ultérieure ;
d’une clé API Moonshot stockée en dehors du contrôle de version ;
de l’URL de base https://api.moonshot.ai/v1 ;
de l’identifiant de modèle kimi-k3.

Installez le SDK :

python -m pip install --upgrade "openai>=1.0"

Définissez la clé dans votre shell :

export MOONSHOT_API_KEY="your-key"

Dans PowerShell :

$env:MOONSHOT_API_KEY="your-key"

Ne placez jamais une clé de production dans un exemple de code, un bundle côté client, un journal ou un dépôt.

Effectuez votre première requête Kimi K3

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Review this migration plan and list its three highest risks."}
    ],
)

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

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
    ]
  }'

Configurez l’effort de raisonnement

K3 utilise toujours le mode réflexion. Configurez son effort via le champ de premier niveau reasoning_effort :

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[
        {"role": "user", "content": "Find the flaw in this distributed lock design."}
    ],
)

Les valeurs prises en charge sont :

Valeur	Utilisation
`low`	Tâches plus simples où la latence et la sortie sont importantes
`high`	Développement complexe, analyse et planification d’outils
`max`	Tâches les plus difficiles et évaluations de type benchmark

La valeur par défaut documentée est max. Ne supposez pas qu’il s’agit du réglage de production le moins coûteux. Évaluez le taux de réussite, la latence et les tokens générés pour chaque niveau d’effort.

Diffusez le raisonnement et le contenu final en streaming

Les réponses en streaming exposent le raisonnement et le texte final via des champs delta différents.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Store or process according to your product and provider policies.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)

Conservez séparément le contenu final destiné aux utilisateurs et le traitement interne. N’analysez pas les sorties structurées depuis reasoning_content.

Envoyez une image à Kimi K3

Les messages de vision de K3 utilisent un tableau d’objets de contenu. Les URL d’images publiques ne sont pas prises en charge dans ce flux ; encodez une image locale en base64.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {
                    "type": "text",
                    "text": "Identify the three largest accessibility problems in this interface.",
                },
            ],
        }
    ],
)

Vérifiez le type et la taille des fichiers avant d’encoder les importations utilisateur. Évitez de journaliser les charges utiles base64.

Envoyez une vidéo à Kimi K3

Importez la vidéo via l’API Files, référencez l’identifiant retourné avec le schéma ms://, puis supprimez le fichier lorsqu’il n’est plus nécessaire.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")

try:
    response = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize the workflow and identify failed steps."},
                ],
            }
        ],
    )
finally:
    client.files.delete(video.id)

Retournez une sortie avec schéma JSON strict

Utilisez strict: true lorsque le code en aval a besoin d’une structure prévisible.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "incident_risk",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "risk": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "owner": {"type": ["string", "null"]},
                },
                "required": ["risk", "severity", "owner"],
                "additionalProperties": False,
            },
        },
    },
)

result = json.loads(response.choices[0].message.content or "{}")

Analysez uniquement le message.content final, puis validez-le à nouveau dans le code applicatif.

Appelez des outils personnalisés

La première réponse peut demander un ou plusieurs outils. Exécutez chaque appel autorisé, ajoutez le message complet de l’assistant, puis ajoutez un résultat d’outil correspondant pour chaque tool_call_id.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_build_status",
            "description": "Return the current build status for an allowed project.",
            "parameters": {
                "type": "object",
                "properties": {"project": {"type": "string"}},
                "required": ["project"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]

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

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)
    # Authorize and validate before executing a real tool.
    tool_result = {"project": arguments["project"], "status": "passed"}
    messages.append(
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(tool_result),
        }
    )

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

N’exécutez jamais de commandes shell générées arbitrairement par le modèle sans limite d’autorisation, validation des entrées, environnement restreint et journal d’audit.

Chargez des outils dynamiquement

K3 permet de placer une définition complète d’outil dans un message system au moment où celui-ci devient disponible. Conservez ce message dans l’historique ultérieur, car le serveur ne le conserve pas pour vous.

Le chargement dynamique aide les grands systèmes d’agents à éviter d’envoyer tous les schémas d’outils à chaque tour. Il introduit également de nouvelles exigences de gestion d’état : le modèle doit voir la déclaration exacte lorsqu’il interprète des résultats d’outils ultérieurs.

Utilisez la fenêtre de contexte de 1M tokens

Les grands contextes sont particulièrement utiles lorsque des éléments éloignés doivent être analysés ensemble. Utilisez-les intentionnellement :

Placez les dépôts stables ou corpus documentaires au début.
Ajoutez les questions et résultats au lieu de réécrire le préfixe.
Suivez séparément les entrées mises en cache et non mises en cache.
Récupérez un sous-ensemble plus petit lorsque le corpus complet n’est pas nécessaire.
Définissez des identifiants de source afin que la réponse finale puisse être vérifiée.
Effectuez une compression uniquement lorsque votre client conserve tout l’état requis par K3.

La mise en cache automatique ne possède ni identifiant de cache ni paramètre TTL classique. Les préfixes stables donnent au service les meilleures chances d’utiliser le cache.

Préservez l’état complet des conversations multi-tours

C’est la règle d’intégration K3 la plus importante.

Lorsque vous poursuivez une conversation ou retournez des résultats d’outils, ajoutez le message complet de l’assistant renvoyé par l’API. Ne conservez pas uniquement content. Moonshot indique que K3 a été entraîné avec un historique de réflexion préservé et peut devenir instable si l’environnement d’exécution supprime l’historique requis ou bascule vers K3 au milieu d’une session.

Stockez l’état des conversations de manière sécurisée, appliquez des limites de conservation et évitez d’exposer un état caché aux utilisateurs qui ne devraient pas y avoir accès.

Limites importantes de l’API Kimi K3

K3 garde toujours la réflexion activée.
reasoning_effort prend en charge low, high et max.
max_completion_tokens est défini par défaut à 131,072 et peut être configuré jusqu’à 1,048,576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 et frequency_penalty=0 sont fixes ; ne les indiquez pas.
Les URL d’images publiques ne sont pas prises en charge pour les messages de vision.
Les requêtes multi-tours et avec outils doivent conserver le message complet de l’assistant.
Moonshot indique que son outil de recherche web est en cours de mise à jour et n’est actuellement pas recommandé en production.

Checklist de production

Conservez les clés API côté serveur.
Ajoutez des délais d’expiration de requêtes et des nouvelles tentatives limitées.
Validez les arguments des outils et autorisez chaque action.
Limitez les tours d’outils et la longueur des complétions.
Préservez l’état complet de l’assistant K3.
Validez le JSON strict après génération.
Enregistrez les entrées, les entrées mises en cache, les sorties, la latence et les erreurs.
Évitez de changer de modèle au milieu d’une session K3.
Ajoutez des limites comportementales explicites pour réduire une proactivité excessive.
Testez avec des outils défaillants, des réponses partielles et de longs historiques.

Consultez Tarification de l’API Kimi K3 avant de choisir les limites de contexte et de sortie. Suivez la page du modèle Kimi K3 pour connaître la disponibilité de Poyo.ai.

Questions fréquentes

L’API Kimi K3 est-elle compatible avec OpenAI ?

Oui. Moonshot expose un endpoint Chat Completions compatible avec OpenAI. Les règles spécifiques à K3 concernant l’état, le raisonnement, l’échantillonnage et les médias restent applicables.

Quel est l’identifiant du modèle Kimi K3 ?

L’identifiant officiel du modèle dans l’API Moonshot est kimi-k3.

Kimi K3 prend-il en charge l’appel de fonctions ?

Oui. Il prend en charge les outils personnalisés, le choix d’outils obligatoire, les résultats d’outils correspondants et le chargement dynamique d’outils.

Kimi K3 peut-il traiter des vidéos ?

Oui. Importez la vidéo via l’API Files et référencez son identifiant de fichier ms:// dans un objet de contenu vidéo.

Comment utiliser la fenêtre de contexte de 1M tokens ?

Envoyez les messages et contenus nécessaires via la requête standard du modèle, conservez les préfixes stables inchangés pour la mise en cache automatique et définissez des limites de complétion adaptées.