> ## 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.
# Guía de Kimi K3: nuevos parámetros y matriz de las tres API
> Guía de Kimi K3 (julio de 2026): reasoning_effort max, carga dinámica de herramientas, salida estructurada, caché automática y ejemplos de las tres API.
> Este artículo presenta los nuevos parámetros de [Kimi K3](https://aihubmix.com/model/kimi-k3) y las consideraciones de uso. En AIHubMix, K3 puede invocarse mediante Chat Completions, Responses y la interfaz Messages compatible con Claude. Lectura adicional: [documentación oficial de la plataforma Moonshot](https://platform.moonshot.ai/docs).
>
> Las conclusiones marcadas como «Verificado» y los ejemplos de respuesta de cada sección provienen de llamadas reales realizadas el 2026-07-17 a través de las interfaces de AIHubMix (Chat Completions / Responses / Messages).
## 1. Resumen de especificaciones del modelo
| Elemento | Valor |
| :--------------------- | :----------------------------------------------------------------------------------- |
| Ventana de contexto | 1M tokens |
| Salida máxima | `max_completion_tokens` predeterminado 131,072, máximo 1,048,576 |
| Modalidades de entrada | Texto, imagen (para entrada de vídeo, consulte la documentación oficial de Moonshot) |
| Modo de razonamiento | Activado por defecto, `reasoning_effort` solo admite `"max"` |
| Secuencias de parada | `stop` admite hasta 5 entradas, cada una de máximo 32 bytes |
> **Verificado**: ambos límites de `stop` se validan y superarlos devuelve 400; el parámetro `stop_sequences` de la interfaz Messages aplica la misma validación.
>
> ❗ **La interfaz Messages no sigue la semántica de Anthropic al activarse una secuencia de parada**: en las pruebas, `stop_reason` es `"end_turn"` (en lugar de `"stop_sequence"`), `stop_sequence` es `null`, y el texto visible previo a la secuencia de parada puede estar vacío. Los clientes que dependen de estos dos campos para determinar la causa del truncamiento deben tenerlo en cuenta.
```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. Modo de razonamiento: `reasoning_effort` solo con nivel `max`
El razonamiento de K3 está activado por defecto y `reasoning_effort` solo admite el nivel `"max"`.
**En conversaciones multiturno es obligatorio reenviar el historial de razonamiento sin modificar**: según la documentación oficial de Moonshot, K3 fue entrenado con preserved thinking, por lo que en conversaciones multiturno debe reenviarse el mensaje assistant devuelto en el turno anterior **de forma completa y sin modificaciones** (incluido el contenido de razonamiento); la ausencia del historial de razonamiento provoca inestabilidad en la calidad de la salida. Si utiliza frameworks de gestión de sesiones o capas proxy, verifique que el contenido de razonamiento no se recorte antes del reenvío.
El contenido de razonamiento se devuelve en el campo `reasoning_content` de la respuesta; en multiturno, reenvíe el mensaje assistant del turno anterior (incluido `reasoning_content`) sin modificar.
```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?"},
]
```
> **Verificado**: la respuesta devuelve `reasoning_content`; tras reenviar el mensaje assistant del turno anterior (incluido `reasoning_content`) sin modificar, los turnos siguientes responden con normalidad.
El contenido de razonamiento se devuelve como elemento de salida `reasoning`; en multiturno, incorpore los elementos de salida del turno anterior (`reasoning` + `message`) sin modificar al `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"
```
El contenido de razonamiento se devuelve como bloque de contenido nativo `thinking`; en multiturno, reenvíe los bloques de contenido del assistant del turno anterior (incluido el bloque thinking) sin modificar.
```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. Parámetros de muestreo con valores fijos
Los parámetros de muestreo de K3 tienen valores fijos oficiales: `temperature` 1.0, `top_p` 0.95, `n` 1, `presence_penalty` / `frequency_penalty` 0. La recomendación oficial es no incluir estos parámetros en las solicitudes.
> **Nota**: los valores fijos de muestreo son la especificación oficial y no pueden verificarse mediante señales de la respuesta; omita estos parámetros según la recomendación oficial.
## 4. Llamadas a herramientas y carga dinámica de herramientas
`tools` admite hasta 128 herramientas; `tool_choice` permite forzar o deshabilitar las llamadas. K3 también admite la carga dinámica de herramientas: inyectar herramientas nuevas a mitad de conversación mediante el campo `tools` de un mensaje system (una forma de mensaje exclusiva de la interfaz Chat).
`tool_choice` admite `auto` / `none` / `required`; `required` fuerza al modelo a llamar a la herramienta. Carga dinámica de herramientas: el mensaje system que inyecta la herramienta no lleva `content`, la herramienta inyectada surte efecto en los turnos posteriores y debe reenviarse en cada solicitud.
```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\"}"}}]
```
> **Verificado**: `tool_choice: "required"` fuerza una llamada a herramienta incluso ante preguntas no relacionadas; `"none"` suprime las llamadas a herramientas; las herramientas inyectadas a mitad de conversación mediante un mensaje system sin `content` pueden invocarse con normalidad.
Las definiciones de herramientas usan estructura plana (`name` en el nivel superior); la llamada forzada usa igualmente `tool_choice: "required"` y la llamada se devuelve como elemento de salida `function_call`. La carga dinámica de herramientas está en proceso de soporte; por ahora, declare todas las herramientas en el parámetro `tools` del nivel superior.
```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\"}"}
```
Las herramientas usan el formato de Anthropic (`input_schema`); la llamada forzada es `tool_choice: {"type": "any"}` y la deshabilitación es `{"type": "none"}`. ❗ **El endpoint oficial Messages (compatible con Anthropic) de Kimi K3 no admite la carga dinámica de herramientas**: en las pruebas, el mensaje de inyección devuelve 200 pero la herramienta inyectada no surte efecto (el modelo no puede llamarla); declare todas las herramientas en el parámetro `tools` del nivel superior.
```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. Salida estructurada
La salida estructurada permite que el modelo devuelva contenido que cumple estrictamente un JSON Schema dado.
`response_format` admite `json_schema` y el modo `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"}
```
> **Verificado**: la salida es JSON válido conforme al schema.
La salida estructurada se declara mediante `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"}
```
❗ **El endpoint oficial Messages (compatible con Anthropic) de Kimi K3 no admite la salida estructurada**: los campos de salida estructurada se ignoran silenciosamente — la solicitud devuelve HTTP 200 con texto libre, sin ningún error ni aviso de degradación, y el análisis JSON posterior fallará. Si necesita salida estructurada, use la interfaz Chat Completions o Responses.
## 6. Caché de contexto activada automáticamente
La caché de contexto de K3 se activa automáticamente, sin necesidad de pasar ningún parámetro. Cuando un prefijo largo repetido acierta en la caché, el volumen acertado se reporta en `usage` (el nombre del campo varía según la interfaz). Consulte el precio de la caché en la [página del modelo](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}
```
> **Verificado**: la segunda solicitud con el mismo prefijo largo reporta el acierto en `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. Continuación por prefijo con `partial`
La continuación por prefijo hace que el modelo continúe generando a partir de un prefijo dado; es adecuada para autocompletado de código y salida con formato controlado.
Pase `"partial": true` en el último mensaje 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.
```
> **Verificado**: la generación continúa desde el prefijo dado, sin repetirlo.
Pase el prefijo como mensaje assistant al final del array `input`, sin necesidad del parámetro `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 misma capacidad se consigue con el prellenado assistant nativo del protocolo, sin necesidad del parámetro `partial`: basta con pasar el prefijo como último mensaje 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. Entrada visual
Las imágenes se pasan en base64; la forma de los bloques de contenido varía según la interfaz.
```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)
```
> **Verificado**: la entrada de imagen en base64 funciona; el modelo describe correctamente el contenido de la imagen de prueba.
```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. Referencia verificada: tiempo y consumo de una llamada única en tareas largas
El razonamiento de K3 está fijado en el nivel max, por lo que las solicitudes únicas de tareas complejas tardan bastante más que en modelos convencionales. Datos verificados de una tarea de generación de un juego HTML en un solo archivo (un único prompt con imagen de referencia, una sola generación, sin iteraciones): la solicitud tardó 2,541 segundos (unos 42 minutos), con 74,994 completion tokens, de los cuales 54,486 corresponden al razonamiento (el 73%); el resultado final fueron 1,275 líneas de código ejecutable directamente, con `finish_reason` igual a `stop`.
Recomendaciones para el lado del cliente:
* Configure los timeouts del cliente en el orden de minutos o más, y priorice el streaming en tareas largas;
* Deje margen suficiente en `max_completion_tokens`: en este ejemplo, solo el razonamiento consumió 54,486 tokens.
## 10. Matriz de compatibilidad capacidad × interfaz
Cada celda de la tabla siguiente refleja el resultado de llamadas reales verificadas el 2026-07-17 a través de las interfaces en producción de AIHubMix; el contenido de cada celda es la sintaxis de parámetro / campo de la interfaz correspondiente.
| Capacidad | Chat Completions | Responses | Messages |
| :-------------------------------------------- | :-------------------------------------------- | :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| Devolución del contenido de razonamiento | ✅ campo `reasoning_content` | ✅ elemento de salida `reasoning` | ✅ bloque de contenido `thinking` |
| Reenvío del historial de razonamiento | ✅ reenvío del mensaje assistant sin modificar | ✅ reenvío de los elementos de salida sin modificar | ✅ reenvío de los bloques de contenido sin modificar |
| Forzar / deshabilitar llamadas a herramientas | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` |
| Carga dinámica de herramientas | ✅ mensaje system con `tools` (sin `content`) | ➖ En proceso de soporte | ❗ El endpoint oficial Messages (compatible con Anthropic) no la admite |
| Salida estructurada | ✅ `response_format` (json\_schema + strict) | ✅ `text.format` (json\_schema) | ❗ El endpoint oficial no la admite; los campos se **ignoran silenciosamente** (200 + texto libre); use Chat / Responses |
| Medición de aciertos de caché automática | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` |
| Continuación por prefijo | ✅ `"partial": true` | ✅ prellenado assistant | ✅ prellenado assistant (nativo del protocolo) |
| Entrada visual | ✅ `image_url` (base64) | ✅ `input_image` (base64) | ✅ bloque de contenido `image` (base64) |
| Secuencias de parada | ✅ `stop` (con validación de límites) | ➖ En proceso de soporte | ❗ `stop_sequences` valida los mismos límites, pero al activarse no devuelve `stop_reason: "stop_sequence"` ni el valor de `stop_sequence` |
## Preguntas frecuentes (FAQ)
**¿Qué interfaces admite K3 en AIHubMix?**
Chat Completions (`/v1/chat/completions`), Responses (`/v1/responses`) y la interfaz Messages compatible con Claude (`/v1/messages`).
**¿Se puede desactivar el razonamiento o reducir su intensidad?**
No. El razonamiento de K3 está activado por defecto y `reasoning_effort` solo admite el nivel `"max"`.
**¿Por qué hay que reenviar `reasoning_content` en conversaciones multiturno?**
K3 fue entrenado con preserved thinking; la documentación oficial exige reenviar el mensaje assistant del turno anterior de forma completa y sin modificaciones. La ausencia del historial de razonamiento provoca inestabilidad en la calidad de la salida.
**¿Qué límites tiene el parámetro `stop`?**
Hasta 5 secuencias de parada, cada una de máximo 32 bytes; superarlos devuelve un error 400.
**¿La interfaz Messages admite salida estructurada?**
❗ No. El endpoint oficial Messages (compatible con Anthropic) de Kimi K3 ignora silenciosamente los campos de salida estructurada (devuelve 200 con texto libre, sin error). Si necesita salida estructurada, use `response_format` de Chat Completions o `text.format` de Responses.
**¿Por qué las solicitudes únicas de K3 tardan tanto?**
El razonamiento de K3 está fijado en el nivel max, y en tareas complejas los tokens de razonamiento representan una proporción alta (el 73% de los completion tokens en el caso verificado). Se recomienda configurar los timeouts del cliente en el orden de minutos o más y usar streaming.
***
Consulte el precio y el estado en tiempo real del modelo en la [página del modelo Kimi K3](https://aihubmix.com/model/kimi-k3), y más modelos en la [galería de modelos](https://aihubmix.com/models).
Última actualización: 2026-07-17