Guía práctica de Kimi K3: nuevos parámetros y matriz de compatibilidad de API

Este artículo cubre los nuevos parámetros y las notas de uso de Kimi K3. En AIHubMix, K3 está disponible a través de las APIs Chat Completions, Responses y Messages compatible con Claude. Consulte también: documentación oficial de la plataforma Moonshot.

Las conclusiones "Verificado" y las respuestas de ejemplo de cada sección proceden de llamadas reales realizadas el 17/07/2026 a través de las APIs de AIHubMix (Chat Completions / Responses / Messages).

1. Especificaciones del modelo de un vistazo

Verificado: ambos límites de stop se validan, y superarlos devuelve un 400; la API de Messages aplica la misma validación a stop_sequences.

❗ Cuando se alcanza una secuencia de parada, la API de Messages no sigue la semántica de Anthropic: en las pruebas, stop_reason es "end_turn" (en lugar de "stop_sequence"), stop_sequence es null, y el texto visible anterior a la palabra de parada puede estar vacío. Los clientes que dependan de estos dos campos para detectar truncamientos deben tenerlo en cuenta.

# 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 admite max

El razonamiento de K3 está activado por defecto, y reasoning_effort solo admite un único nivel: "max".

Las conversaciones de varios turnos deben devolver el historial de razonamiento tal cual: según la documentación oficial de Moonshot, K3 se entrena con razonamiento preservado, por lo que en conversaciones de varios turnos el mensaje anterior del asistente debe enviarse de vuelta completo y sin modificar (incluido el contenido de razonamiento). La falta de historial de razonamiento provoca una calidad de salida inestable. Si utiliza un framework de gestión de sesiones o una capa de proxy, confirme que el contenido de razonamiento se devuelve sin recortar.
Chat Completions

El contenido de razonamiento se devuelve en el campo reasoning_content de la respuesta; en conversaciones de varios turnos, devuelva tal cual el mensaje anterior del asistente (incluido reasoning_content).

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?"},
]

Verificado: la respuesta devuelve reasoning_content; tras devolver tal cual el mensaje anterior del asistente (incluido reasoning_content), los turnos siguientes responden con normalidad.
Responses

El contenido de razonamiento se devuelve como un elemento de salida reasoning; en conversaciones de varios turnos, añada los elementos de salida del turno anterior (reasoning + message) de vuelta en input tal cual.

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

El contenido de razonamiento se devuelve como bloques de contenido thinking nativos; en conversaciones de varios turnos, devuelva tal cual los bloques de contenido del asistente anterior (incluidos los bloques de thinking).

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. Los parámetros de muestreo son fijos

Los parámetros de muestreo de K3 están fijados por el proveedor del modelo: temperature 1.0, top_p 0.95, n 1, y presence_penalty / frequency_penalty 0. La recomendación oficial es omitir estos parámetros en las solicitudes.

Nota: los valores de muestreo fijos forman parte de la especificación oficial y no pueden verificarse a partir de las señales de respuesta; siga la recomendación oficial y omita estos parámetros.

4. Llamadas a herramientas y carga dinámica de herramientas

tools admite hasta 128 herramientas; tool_choice permite forzar y desactivar las llamadas a herramientas. K3 también admite la carga dinámica de herramientas: inyectar nuevas herramientas durante la conversación mediante el campo tools de un mensaje de sistema (una forma de mensaje específica de la API de Chat).
Chat Completions

tool_choice admite auto / none / required; required obliga al modelo a llamar a una herramienta. Carga dinámica de herramientas: el mensaje de sistema que inyecta herramientas no lleva content, las herramientas inyectadas surten efecto en los turnos siguientes, y el mensaje debe incluirse de nuevo en cada solicitud.

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\"}"}}]

Verificado: tool_choice: "required" fuerza una llamada a herramienta incluso para indicaciones no relacionadas; "none" suprime las llamadas a herramientas; las herramientas inyectadas durante la conversación mediante un mensaje de sistema sin content pueden invocarse con normalidad.
Responses

Las definiciones de herramientas usan una estructura plana (name en el nivel superior); forzar una llamada también se hace con tool_choice: "required", y las llamadas se devuelven como elementos de salida function_call. El soporte de carga dinámica de herramientas está en desarrollo; por ahora, declare todas las herramientas en el parámetro tools de nivel superior.

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

Las herramientas usan el formato de Anthropic (input_schema); fuerce una llamada con tool_choice: {"type": "any"} y desactive las llamadas con {"type": "none"}. ❗ El endpoint oficial de Messages (compatible con Anthropic) de Kimi K3 no admite la carga dinámica de herramientas: en las pruebas, el mensaje que realiza la inyección devuelve 200, pero la herramienta inyectada no tiene efecto (el modelo no puede llamarla). Declare todas las herramientas en el parámetro tools de nivel superior.

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 hace que el modelo devuelva contenido que se ajusta estrictamente a un JSON Schema dado.
Chat Completions

response_format admite json_schema con el modo 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"}

Verificado: la salida es un JSON válido que se ajusta al esquema.
Responses

La salida estructurada se declara mediante 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

❗ El endpoint oficial de 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 error ni aviso de reserva, y el análisis de JSON posterior fallará. Cuando necesite salida estructurada, utilice la API de Chat Completions o Responses.

6. La caché de contexto es automática

La caché de contexto de K3 se activa automáticamente, sin necesidad de parámetros. Cuando un prefijo largo repetido acierta en la caché, la cantidad acertada se informa en usage (el nombre del campo varía según la API). Los precios de la caché figuran en la página del modelo.
Chat Completions

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

Verificado: la segunda solicitud con un prefijo largo idéntico informa del acierto en 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. Completado de prefijo con partial

El completado de prefijo hace que el modelo continúe la generación a partir de un prefijo dado, ideal para el autocompletado de código y para salidas con formato controlado.
Chat Completions

Pase "partial": true en el último mensaje del asistente.

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 a partir del prefijo dado sin repetirlo.
Responses

Pase el prefijo como un mensaje del asistente al final del array input; no se necesita el parámetro partial.

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 misma capacidad se logra con el prefill nativo del asistente del protocolo, sin el parámetro partial: pase el prefijo como último mensaje del asistente.

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 de visión

Las imágenes se pasan en base64; el formato de los bloques de contenido varía según la 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)

Verificado: la entrada de imágenes en base64 funciona, y el modelo describe correctamente la imagen de prueba.
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. Referencia verificada: latencia y uso de una tarea larga en una sola llamada

El razonamiento de K3 está fijado en el nivel max, por lo que las solicitudes únicas de tareas complejas tardan considerablemente más que en los modelos habituales. Datos medidos de una tarea de generación de un juego HTML en un solo archivo (un prompt con una imagen de referencia, generado de una vez sin iteraciones): la solicitud única tardó 2,541 segundos (unos 42 minutos), con 74,994 tokens de completado, de los cuales 54,486 (73%) fueron tokens de razonamiento; la salida final fueron 1,275 líneas de código directamente ejecutable, con finish_reason stop.

Recomendaciones del lado del cliente:

• Configure los tiempos de espera del cliente en minutos o más, y prefiera el streaming para las tareas largas;
• Deje un margen amplio en max_completion_tokens: en este caso, el razonamiento por sí solo consumió 54,486 tokens.

10. Matriz de compatibilidad capacidad × API

Cada celda de la tabla siguiente se verificó el 17/07/2026 mediante llamadas reales a las APIs de producción de AIHubMix; cada celda muestra la sintaxis del parámetro o campo para la API correspondiente.

Preguntas frecuentes

¿Qué APIs admite K3 en AIHubMix?
Chat Completions (/v1/chat/completions), Responses (/v1/responses) y la API de Messages compatible con Claude (/v1/messages).

¿Se puede desactivar el razonamiento o reducirlo?
No. El razonamiento de K3 está activado por defecto, y reasoning_effort solo admite el único nivel "max".

¿Por qué hay que devolver reasoning_content en conversaciones de varios turnos?
K3 se entrena con pensamiento preservado; Moonshot exige que el mensaje previo del asistente se devuelva completo y sin modificaciones. Si falta el historial de razonamiento, la calidad de la salida se vuelve inestable.

¿Cuáles son los límites del parámetro stop?
Como máximo 5 secuencias de parada, cada una de no más de 32 bytes; si se supera cualquiera de los dos límites, se devuelve un error 400.

¿Admite la API de Messages salida estructurada?
❗ No. El endpoint oficial de Messages de Kimi K3 (compatible con Anthropic) ignora silenciosamente los campos de salida estructurada (devuelve 200 con texto libre y sin error). Para salida estructurada, use response_format en Chat Completions o text.format en Responses.

¿Por qué tardan tanto las solicitudes individuales de K3?
El razonamiento de K3 está fijado en el nivel máximo, y los tokens de razonamiento representan una gran parte en las tareas complejas (el 73% de los tokens de completado en el caso medido). Configure los tiempos de espera del cliente en minutos o más y use streaming.

Para consultar los precios y el estado en tiempo real, vea la página del modelo Kimi K3; para más modelos, visite la galería de modelos.

Última actualización: 2026-07-17