Guide pratique Kimi K3 : nouveaux paramètres et matrice de prise en charge des API

Cet article présente les nouveaux paramètres et les remarques d'utilisation pour Kimi K3. Sur AIHubMix, K3 est disponible via les API Chat Completions, Responses et Messages compatibles Claude. Voir aussi : documentation officielle de la plateforme Moonshot.

Les conclusions « Vérifié » et les exemples de réponses de chaque section proviennent d'appels réels effectués le 17/07/2026 via les API AIHubMix (Chat Completions / Responses / Messages).

1. Caractéristiques du modèle en un coup d'œil

Vérifié : les deux limites de stop sont validées, et tout dépassement renvoie une erreur 400 ; l'API Messages applique la même validation à stop_sequences.

❗ Lorsqu'une séquence d'arrêt est atteinte, l'API Messages ne suit pas la sémantique d'Anthropic : lors des tests, stop_reason vaut "end_turn" (au lieu de "stop_sequence"), stop_sequence vaut null, et le texte visible avant le mot d'arrêt peut être vide. Les clients qui s'appuient sur ces deux champs pour détecter une troncature doivent en tenir compte.

# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"

2. Mode de réflexion : reasoning_effort ne prend en charge que max

La réflexion de K3 est activée par défaut, et reasoning_effort ne prend en charge qu'un seul niveau : "max".

Dans les conversations multi-tours, l'historique de réflexion doit être renvoyé textuellement : selon la documentation officielle de Moonshot, K3 est entraîné avec une réflexion préservée ; dans les conversations multi-tours, le message assistant précédent doit donc être renvoyé complet et non modifié (y compris le contenu de réflexion). Un historique de réflexion manquant entraîne une qualité de sortie instable. Si vous utilisez un framework de gestion de session ou une couche proxy, vérifiez que le contenu de réflexion est renvoyé sans troncature.
Chat Completions

Le contenu de réflexion est renvoyé dans le champ reasoning_content de la réponse ; dans les conversations multi-tours, renvoyez le message assistant précédent (y compris reasoning_content) textuellement.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# Multi-turn: pass the previous assistant message back verbatim
messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "Paris.", "reasoning_content": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "And its population?"},
]

Vérifié : la réponse renvoie reasoning_content ; après avoir renvoyé textuellement le message assistant précédent (y compris reasoning_content), les tours suivants répondent normalement.
Responses

Le contenu de réflexion est renvoyé sous forme d'élément de sortie reasoning ; dans les conversations multi-tours, ajoutez textuellement les éléments de sortie du tour précédent (reasoning + message) à input.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="Answer in one word: capital of France",
)

# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"

Messages

Le contenu de réflexion est renvoyé sous forme de blocs de contenu natifs thinking ; dans les conversations multi-tours, renvoyez textuellement les blocs de contenu de l'assistant précédent (y compris les blocs de réflexion).

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Answer in one word: capital of France"}
    ],
)

# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message

3. Les paramètres d'échantillonnage sont figés

Les paramètres d'échantillonnage de K3 sont fixés par le fournisseur du modèle : temperature 1.0, top_p 0.95, n 1, et presence_penalty / frequency_penalty 0. La recommandation officielle est de omettre ces paramètres dans les requêtes.

Remarque : les valeurs d'échantillonnage figées font partie de la spécification officielle et ne peuvent pas être vérifiées à partir des signaux de réponse ; suivez la recommandation officielle et omettez ces paramètres.

4. Appel d'outils et chargement dynamique des outils

tools prend en charge jusqu'à 128 outils ; tool_choice permet de forcer ou de désactiver les appels d'outils. K3 prend aussi en charge le chargement dynamique des outils : injection de nouveaux outils en cours de conversation via le champ tools d'un message système (un format de message propre à l'API Chat).
Chat Completions

tool_choice prend en charge auto / none / required ; required oblige le modèle à appeler un outil. Chargement dynamique des outils : le message système qui injecte des outils ne contient pas de content, les outils injectés prennent effet pour les tours suivants, et le message doit être à nouveau inclus dans chaque requête.

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello."},
    {"role": "assistant", "content": "Hi, how can I help you?"},
    # Inject a new tool mid-conversation: tools field only, no content
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Get the current time",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "What time is it now?"},
]

# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

Vérifié : tool_choice: "required" force un appel d'outil même pour des invites sans rapport ; "none" supprime les appels d'outils ; les outils injectés en cours de conversation via un message système sans content peuvent être appelés normalement.
Responses

Les définitions d'outils utilisent une structure plate (name au niveau supérieur) ; pour forcer un appel, on utilise également tool_choice: "required", et les appels sont renvoyés sous forme d'éléments de sortie function_call. La prise en charge du chargement dynamique des outils est en cours ; pour l'instant, déclarez tous les outils dans le paramètre tools de premier niveau.

response = client.responses.create(
    model="kimi-k3",
    input="Hello",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Messages

Les outils utilisent le format Anthropic (input_schema) ; forcez un appel avec tool_choice: {"type": "any"} et désactivez les appels avec {"type": "none"}. ❗ L'endpoint Messages officiel de Kimi K3 (compatible Anthropic) ne prend pas en charge le chargement dynamique des outils : lors des tests, le message d'injection renvoie 200, mais l'outil injecté n'a aucun effet (le modèle ne peut pas l'appeler). Déclarez tous les outils dans le paramètre tools de premier niveau.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Hello"}],
)

# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather

5. Sortie structurée

La sortie structurée oblige le modèle à renvoyer un contenu strictement conforme à un JSON Schema donné.
Chat Completions

response_format prend en charge json_schema avec le mode strict.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Paris is the capital of France. Extract the city name."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Observed response content: {"city":"Paris"}

Vérifié : la sortie est un JSON valide conforme au schéma.
Responses

La sortie structurée est déclarée via text.format.

response = client.responses.create(
    model="kimi-k3",
    input="Paris is the capital of France. Extract the city name.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Observed output text: {"city":"Paris"}

Messages

❗ L'endpoint Messages officiel de Kimi K3 (compatible Anthropic) ne prend pas en charge la sortie structurée : les champs de sortie structurée sont silencieusement ignorés ; la requête renvoie HTTP 200 avec du texte libre, sans erreur ni avis de repli, et l'analyse JSON en aval échouera. Si vous avez besoin d'une sortie structurée, utilisez l'API Chat Completions ou Responses.

6. La mise en cache du contexte est automatique

La mise en cache du contexte de K3 est activée automatiquement, sans paramètre requis. Lorsqu'un long préfixe répété atteint le cache, le volume concerné est indiqué dans usage (le nom du champ varie selon l'API). La tarification du cache figure sur la page du modèle.
Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}

Vérifié : la deuxième requête avec un long préfixe identique signale le cache touché dans usage.prompt_tokens_details.cached_tokens.
Responses

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. Complétion de préfixe avec partial

La complétion de préfixe fait continuer le modèle à partir d'un préfixe donné ; elle convient bien à la complétion de code et aux sorties à format contrôlé.
Chat Completions

Passez "partial": true dans le dernier message assistant.

messages = [
    {"role": "user", "content": "Write a haiku about the sea."},
    {"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]

# Prefix: "Waves fold into foam,"  ->  continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.

Vérifié : la génération se poursuit à partir du préfixe donné sans le répéter.
Responses

Passez le préfixe sous forme de message assistant à la fin du tableau input ; aucun paramètre partial n'est nécessaire.

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt hangs in the air— / moon pulls the tide home."

Messages

La même fonctionnalité est obtenue avec le préremplissage natif de l'assistant du protocole, sans paramètre partial : passez le préfixe comme dernier message assistant.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."

8. Entrée visuelle

Les images sont transmises en base64 ; le format des blocs de contenu varie selon l'API.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Observed response content: "Red"  (input: a 64x64 solid red PNG)

Vérifié : l'entrée d'image en base64 fonctionne, et le modèle décrit correctement l'image de test.
Responses

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What is the dominant color of this image? One word."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

Messages

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Observed response text: "Red"

9. Référence vérifiée : latence et consommation d'une tâche longue en un seul appel

La réflexion de K3 est fixée au niveau max ; les requêtes uniques pour des tâches complexes prennent donc nettement plus de temps que sur les modèles courants. Données mesurées sur une tâche de génération d'un jeu HTML en un seul fichier (une invite avec une image de référence, générée d'un seul coup sans itération) : la requête unique a duré 2 541 secondes (environ 42 minutes), avec 74 994 tokens de complétion, dont 54 486 (73 %) étaient des tokens de réflexion ; la sortie finale comptait 1 275 lignes de code directement exécutable, avec finish_reason stop.

Recommandations côté client :

• Réglez les délais d'attente des clients à plusieurs minutes ou plus, et privilégiez le streaming pour les tâches longues ;
• Prévoyez une marge confortable dans max_completion_tokens : dans ce cas, la seule réflexion a consommé 54 486 tokens.

10. Matrice de prise en charge capacité × API

Chaque cellule du tableau ci-dessous a été vérifiée le 17/07/2026 par des appels réels aux API de production d'AIHubMix ; chaque cellule indique la syntaxe du paramètre / champ pour l'API correspondante.

FAQ

Quelles API K3 prend-il en charge sur AIHubMix ?
Chat Completions (/v1/chat/completions), Responses (/v1/responses) et l'API Messages compatible Claude (/v1/messages).

La réflexion peut-elle être désactivée ou réduite ?
Non. La réflexion de K3 est activée par défaut, et reasoning_effort ne prend en charge que le niveau unique "max".

Pourquoi reasoning_content doit-il être renvoyé dans les conversations multi-tours ?
K3 est entraîné avec une réflexion préservée ; Moonshot exige que le message précédent de l'assistant soit renvoyé complet et non modifié. L'absence de l'historique de réflexion entraîne une qualité de sortie instable.

Quelles sont les limites du paramètre stop ?
Au maximum 5 séquences d'arrêt, chacune ne dépassant pas 32 octets ; tout dépassement de l'une ou l'autre limite renvoie une erreur 400.

L'API Messages prend-elle en charge la sortie structurée ?
❗ Non. L'endpoint officiel Messages de Kimi K3 (compatible Anthropic) ignore silencieusement les champs de sortie structurée (il renvoie un code 200 avec du texte libre, sans erreur). Pour la sortie structurée, utilisez response_format sur Chat Completions ou text.format sur Responses.

Pourquoi les requêtes K3 uniques sont-elles si longues ?
La réflexion de K3 est fixée au niveau maximal, et les tokens de réflexion représentent une grande part des tokens de complétion sur les tâches complexes (73% des tokens de complétion dans le cas mesuré). Réglez les délais d'attente côté client sur plusieurs minutes, voire davantage, et utilisez le streaming.

Pour la tarification et le statut en temps réel, consultez la page du modèle Kimi K3 ; pour davantage de modèles, visitez la galerie de modèles.

Dernière mise à jour : 2026-07-17