> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Guide pratique Kimi K3 : paramètres et matrice des trois API
> Guide Kimi K3 (juillet 2026) : reasoning_effort max, outils dynamiques, sortie structurée, cache auto, préfixe partial, vision — trois API AIHubMix.
> Cet article présente les nouveaux paramètres de [Kimi K3](https://aihubmix.com/model/kimi-k3) et les points d'attention lors de son appel. Sur AIHubMix, K3 est accessible via les API Chat Completions, Responses et Messages (compatible Claude). Lecture complémentaire : [documentation officielle de la plateforme Moonshot](https://platform.moonshot.ai/docs).
>
> Les conclusions « Vérifié » et les exemples de réponses de chaque section proviennent d'appels réels effectués le 2026-07-17 via les API AIHubMix (Chat Completions / Responses / Messages).
## 1. Aperçu des spécifications du modèle
| Élément | Valeur |
| :------------------ | :---------------------------------------------------------------------------- |
| Fenêtre de contexte | 1M tokens |
| Sortie maximale | `max_completion_tokens` : 131,072 par défaut, 1,048,576 au maximum |
| Modalités d'entrée | Texte, image (pour l'entrée vidéo, voir la documentation officielle Moonshot) |
| Mode de réflexion | Activé par défaut, `reasoning_effort` ne prend en charge que `"max"` |
| Séquences d'arrêt | `stop` : 5 au maximum, 32 octets maximum chacune |
> **Vérifié** : les deux limites de `stop` sont bien contrôlées, tout dépassement renvoie une erreur 400 ; le paramètre `stop_sequences` de l'API Messages applique les mêmes contrôles.
>
> ❗ **L'API Messages ne suit pas la sémantique Anthropic lorsqu'une séquence d'arrêt est atteinte** : en pratique, `stop_reason` vaut `"end_turn"` (et non `"stop_sequence"`), `stop_sequence` vaut `null`, et le texte visible précédant la séquence d'arrêt peut être vide. Les clients qui s'appuient sur ces deux champs pour déterminer la cause de la troncature doivent en tenir compte.
```text theme={null}
# 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` limité au niveau `max`
La réflexion de K3 est activée par défaut, et `reasoning_effort` ne prend en charge que le niveau `"max"`.
**En conversation multi-tours, l'historique de réflexion doit être renvoyé tel quel** : selon les indications officielles de Moonshot, K3 est entraîné avec la méthode preserved thinking ; en conversation multi-tours, le message assistant renvoyé au tour précédent doit être retransmis **intégralement et à l'identique** (contenu de réflexion inclus). 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 n'est pas tronqué avant le renvoi.
Le contenu de réflexion est renvoyé dans le champ `reasoning_content` de la réponse ; en multi-tours, retransmettez tel quel le message assistant du tour précédent (avec `reasoning_content`).
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
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)
```
```text theme={null}
# 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": ""},
{"role": "user", "content": "And its population?"},
]
```
> **Vérifié** : la réponse renvoie `reasoning_content` ; après retransmission telle quelle du message assistant du tour précédent (avec `reasoning_content`), les tours suivants répondent normalement.
Le contenu de réflexion est renvoyé sous forme d'élément de sortie `reasoning` ; en multi-tours, réinjectez tels quels les éléments de sortie du tour précédent (`reasoning` + `message`) dans `input`.
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
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"
```
Le contenu de réflexion est renvoyé sous forme de bloc de contenu natif `thinking` ; en multi-tours, retransmettez tels quels les blocs de contenu assistant du tour précédent (bloc thinking inclus).
```text theme={null}
from anthropic import Anthropic
client = Anthropic(
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. Paramètres d'échantillonnage à valeurs fixes
Les paramètres d'échantillonnage de K3 sont fixés par les valeurs officielles : `temperature` 1.0, `top_p` 0.95, `n` 1, `presence_penalty` / `frequency_penalty` 0. La recommandation officielle est de ne pas transmettre ces paramètres dans les requêtes.
> **Remarque** : les valeurs d'échantillonnage fixes relèvent de la spécification officielle et ne peuvent pas être vérifiées à partir des signaux de réponse ; conformément à la recommandation officielle, omettez ces paramètres.
## 4. Appel d'outils et chargement dynamique d'outils
`tools` prend en charge jusqu'à 128 outils ; `tool_choice` permet de forcer ou de désactiver l'appel d'outils. K3 prend également en charge le chargement dynamique d'outils : injection de nouveaux outils en cours de conversation via le champ `tools` d'un message system (forme de message propre à l'API Chat).
`tool_choice` prend en charge `auto` / `none` / `required` ; `required` force le modèle à appeler un outil. Chargement dynamique d'outils : le message system injectant les outils ne porte pas de `content`, les outils injectés prennent effet aux tours suivants, et chaque requête doit les inclure de nouveau.
```text theme={null}
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?"},
]
```
```text theme={null}
# 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 sur une question sans rapport ; `"none"` supprime l'appel d'outils ; un outil injecté en cours de conversation via un message system sans `content` peut être appelé normalement.
La définition d'outil est une structure aplatie (`name` au niveau supérieur) ; l'appel forcé utilise également `tool_choice: "required"`, et l'appel est renvoyé sous forme d'élément de sortie `function_call`. Le chargement dynamique d'outils est en cours de prise en charge ; pour l'instant, déclarez tous les outils dans le paramètre `tools` de niveau supérieur.
```text theme={null}
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\"}"}
```
Les outils utilisent le format Anthropic (`input_schema`) ; l'appel forcé s'écrit `tool_choice: {"type": "any"}` et la désactivation `{"type": "none"}`. ❗ **Le point de terminaison officiel Messages (compatible Anthropic) de Kimi K3 ne prend pas en charge le chargement dynamique d'outils** : en pratique, le message d'injection renvoie 200, mais l'outil injecté ne prend pas effet (le modèle ne peut pas l'appeler) ; déclarez tous les outils dans le paramètre `tools` de niveau supérieur.
```text theme={null}
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 permet au modèle de renvoyer un contenu strictement conforme au JSON Schema fourni.
`response_format` prend en charge `json_schema` et le mode `strict`.
```text theme={null}
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 schema.
La sortie structurée se déclare via `text.format`.
```text theme={null}
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"}
```
❗ **Le point de terminaison officiel Messages (compatible Anthropic) de Kimi K3 ne prend pas en charge la sortie structurée** : les champs de sortie structurée sont ignorés silencieusement — la requête renvoie HTTP 200 avec du texte libre, sans aucune erreur ni indication de repli, et l'analyse JSON en aval échoue. Si vous avez besoin d'une sortie structurée, utilisez l'API Chat Completions ou Responses.
## 6. Cache de contexte activé automatiquement
Le cache de contexte de K3 est activé automatiquement, sans aucun paramètre à transmettre. Lorsqu'un long préfixe répété touche le cache, le volume touché est rapporté dans `usage` (le nom du champ varie selon l'API). Le tarif du cache est indiqué sur la [page du modèle](https://aihubmix.com/model/kimi-k3).
```text theme={null}
# 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 rapporte le hit de cache dans `usage.prompt_tokens_details.cached_tokens`.
```text theme={null}
# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}
```
```text theme={null}
# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536
```
## 7. Continuation de préfixe avec `partial`
La continuation de préfixe fait poursuivre la génération du modèle à partir d'un préfixe donné, ce qui convient à la complétion de code et aux sorties au format contrôlé.
Passez `"partial": true` dans le dernier message assistant.
```text theme={null}
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 répéter le préfixe.
Passez le préfixe comme message assistant en fin de tableau `input`, sans paramètre `partial`.
```text theme={null}
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."
```
La même capacité s'obtient via le préremplissage assistant natif du protocole, sans paramètre `partial` — passez simplement le préfixe comme dernier message assistant.
```text theme={null}
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 ; l'écriture du bloc de contenu varie selon l'API.
```text theme={null}
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,"}},
],
}
]
# Observed response content: "Red" (input: a 64x64 solid red PNG)
```
> **Vérifié** : l'entrée d'image en base64 fonctionne, le modèle décrit correctement le contenu de l'image de test.
```text theme={null}
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,"},
],
}
]
# Observed output text: "Red"
```
```text theme={null}
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": ""}},
],
}
]
# Observed response text: "Red"
```
## 9. Référence mesurée : durée et consommation d'un appel unique sur une tâche longue
La réflexion de K3 est fixée au niveau max ; sur les tâches complexes, la durée d'une requête unique est nettement plus longue que celle des modèles classiques. Données mesurées sur une tâche de génération d'un jeu HTML en fichier unique (un seul prompt avec image de référence, génération en une passe, sans itération) : durée de la requête unique 2,541 secondes (environ 42 minutes), 74,994 completion tokens dont 54,486 de réflexion (73 %), pour un résultat final de 1,275 lignes de code directement exécutable, avec `finish_reason` à `stop`.
Recommandations côté appelant :
* réglez le délai d'expiration du client à l'échelle de la minute au minimum, et privilégiez le streaming pour les tâches longues ;
* prévoyez une marge suffisante pour `max_completion_tokens` : dans cet exemple, la réflexion seule consomme 54,486 tokens.
## 10. Matrice de prise en charge capacités × API
Chaque cellule du tableau ci-dessous correspond à un résultat vérifié le 2026-07-17 par appel réel des API AIHubMix en production ; la cellule indique l'écriture du paramètre / champ pour l'API correspondante.
| Capacité | Chat Completions | Responses | Messages |
| :------------------------------------------ | :--------------------------------------------- | :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retour du contenu de réflexion | ✅ champ `reasoning_content` | ✅ élément de sortie `reasoning` | ✅ bloc de contenu `thinking` |
| Retransmission de l'historique de réflexion | ✅ message assistant retransmis tel quel | ✅ éléments de sortie retransmis tels quels | ✅ blocs de contenu retransmis tels quels |
| Appel d'outils forcé / désactivé | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` |
| Chargement dynamique d'outils | ✅ message system avec `tools` (sans `content`) | ➖ en cours de prise en charge | ❗ non pris en charge par le point de terminaison officiel Messages (compatible Anthropic) |
| Sortie structurée | ✅ `response_format` (json\_schema + strict) | ✅ `text.format` (json\_schema) | ❗ non prise en charge par le point de terminaison officiel, champs **ignorés silencieusement** (200 + texte libre), utilisez Chat / Responses |
| Comptage des hits du cache automatique | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` |
| Continuation de préfixe | ✅ `"partial": true` | ✅ préremplissage assistant | ✅ préremplissage assistant (natif du protocole) |
| Entrée visuelle | ✅ `image_url` (base64) | ✅ `input_image` (base64) | ✅ bloc de contenu `image` (base64) |
| Séquences d'arrêt | ✅ `stop` (limites contrôlées) | ➖ en cours de prise en charge | ❗ `stop_sequences` applique les mêmes limites, mais en cas de correspondance ne renvoie ni `stop_reason: "stop_sequence"` ni la valeur `stop_sequence` |
## FAQ
**Quelles API K3 prend-il en charge sur AIHubMix ?**
Chat Completions (`/v1/chat/completions`), Responses (`/v1/responses`) et Messages compatible Claude (`/v1/messages`).
**Peut-on désactiver la réflexion ou en réduire l'intensité ?**
Non. La réflexion de K3 est activée par défaut et `reasoning_effort` ne prend en charge que le niveau `"max"`.
**Pourquoi faut-il retransmettre `reasoning_content` en conversation multi-tours ?**
K3 est entraîné avec la méthode preserved thinking ; la consigne officielle est de retransmettre intégralement et à l'identique le message assistant du tour précédent. Un historique de réflexion manquant entraîne une qualité de sortie instable.
**Quelles sont les limites du paramètre `stop` ?**
Au plus 5 séquences d'arrêt, chacune de 32 octets maximum ; tout dépassement renvoie une erreur 400.
**L'API Messages prend-elle en charge la sortie structurée ?**
❗ Non. Le point de terminaison officiel Messages (compatible Anthropic) de Kimi K3 ignore silencieusement les champs de sortie structurée (retour 200 avec du texte libre, sans erreur). Pour une sortie structurée, utilisez `response_format` de Chat Completions ou `text.format` de Responses.
**Pourquoi une requête unique K3 prend-elle autant de temps ?**
La réflexion de K3 est fixée au niveau max ; sur les tâches complexes, la part des tokens de réflexion est élevée (73 % des completion tokens dans le cas mesuré). Il est recommandé de régler le délai d'expiration du client à l'échelle de la minute au minimum et d'utiliser le streaming.
***
Les tarifs et l'état en temps réel du modèle sont disponibles sur la [page du modèle Kimi K3](https://aihubmix.com/model/kimi-k3) ; retrouvez plus de modèles sur la [place des modèles](https://aihubmix.com/models).
Dernière mise à jour : 2026-07-17