Guía Práctica de Kimi K3: Nuevos Parámetros y Matriz de Soporte de API

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

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

1. Especificaciones del Modelo a Simple Vista

Verificado: ambos límites de stop están validados, y exceder cualquiera devuelve 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 antes de la palabra de parada puede estar vacío. Los clientes que dependen de estos dos campos para detectar truncamientos deben tener en cuenta esto.

# detener con 6 entradas / una entrada de 33 bytes -> HTTP 400
"Solicitud inválida: la matriz de parada es demasiado larga. Se esperaba una matriz con longitud máxima 5, pero se obtuvo una matriz con longitud 6 en su lugar"
"Solicitud inválida: la secuencia de parada no debe ser más larga de 32, pero se obtuvo 33 en su lugar"

2. Modo de Pensamiento: reasoning_effort Solo Admite max

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

Las conversaciones de múltiples turnos deben devolver el historial de pensamiento de forma veraz: según la documentación oficial de Moonshot, K3 está entrenado con pensamiento preservado, por lo que en conversaciones de múltiples turnos el mensaje anterior del asistente debe ser devuelto completo y sin modificar (incluido el contenido del pensamiento). La falta de historial de pensamiento conduce a una calidad de salida inestable. Si utilizas un marco de gestión de sesiones o una capa de proxy, confirma que el contenido del pensamiento se devuelva sin recortes.
Chat Completions

El contenido del pensamiento se devuelve en el campo reasoning_content de la respuesta; en conversaciones de múltiples turnos, pasa el mensaje anterior del asistente (incluido reasoning_content) de forma veraz.

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": "Un caracol está en el fondo de un pozo de 10 metros. Cada día sube 3 metros, pero cada noche resbala 2 metros. ¿Cuántos días tarda en llegar a la cima?"}
    ],
)

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

# Múltiples turnos: devolver el mensaje anterior del asistente de forma veraz
messages = [
    {"role": "user", "content": "¿Cuál es la capital de Francia?"},
    {"role": "assistant", "content": "París.", "reasoning_content": "<reasoning_content de la respuesta anterior>"},
    {"role": "user", "content": "¿Y su población?"},
]

Verificado: la respuesta devuelve reasoning_content; después de devolver el mensaje anterior del asistente (incluido reasoning_content) de forma veraz, los turnos subsiguientes responden normalmente.
Respuestas

El contenido del pensamiento se devuelve como un ítem de salida reasoning; en conversaciones de múltiples turnos, añade los ítems de salida del turno anterior (reasoning + message) de nuevo en input de forma veraz.

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="Responde en una palabra: capital de Francia",
)

# Tipos de ítems de respuesta.output observados: ["reasoning", "message"]; texto: "París"
# Múltiples turnos: input = [primer mensaje del usuario] + response.output + [siguiente mensaje del usuario]
# Respuesta del segundo turno observada con ítems de salida devueltos: "Berlín"

Mensajes

El contenido del pensamiento se devuelve como bloques de contenido thinking nativos; en conversaciones de múltiples turnos, pasa los bloques de contenido anteriores del asistente (incluidos los bloques de pensamiento) de forma veraz.

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": "Responde en una palabra: capital de Francia"}
    ],
)

# Tipos de bloques de respuesta.content observados: ["thinking", "text"]; texto: "París"
# Múltiples turnos: pasa response.content de forma veraz como el mensaje del asistente

3. Los Parámetros de Muestreo Son Fijos

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

Nota: los valores de muestreo fijos son parte de la especificación oficial y no pueden ser verificados a partir de señales de respuesta; sigue la recomendación oficial y omite estos parámetros.

4. Llamadas a Herramientas y Carga Dinámica de Herramientas

tools admite hasta 128 herramientas; tool_choice admite forzar y deshabilitar llamadas a herramientas. K3 también admite carga dinámica de herramientas: inyectar nuevas herramientas a mitad de conversación a través del campo tools de un mensaje del sistema (una forma de mensaje específica para 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 del sistema que inyecta la herramienta no lleva content, las herramientas inyectadas entran en efecto para los turnos subsiguientes, y el mensaje debe incluirse nuevamente en cada solicitud.

messages = [
    {"role": "system", "content": "Eres un asistente útil."},
    {"role": "user", "content": "Hola."},
    {"role": "assistant", "content": "Hola, ¿cómo puedo ayudarte?"},
    # Inyectar una nueva herramienta a mitad de conversación: solo campo tools, sin contenido
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Obtener la hora actual",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "¿Qué hora es ahora?"},
]

# tool_choice="required" con el aviso "Hola" -> el modelo está obligado a llamar a la herramienta
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

Verificado: tool_choice: "required" obliga a una llamada a la herramienta incluso para avisos no relacionados; "none" suprime las llamadas a herramientas; las herramientas inyectadas a mitad de conversación a través de un mensaje del sistema sin content pueden ser llamadas normalmente.
Respuestas

Las definiciones de herramientas utilizan una estructura plana (name en el nivel superior); forzar una llamada también utiliza tool_choice: "required", y las llamadas se devuelven como ítems de salida function_call. El soporte para carga dinámica de herramientas está en progreso; por ahora, declara todas las herramientas en el parámetro tools de nivel superior.

response = client.responses.create(
    model="kimi-k3",
    input="Hola",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Obtener el clima para una ciudad",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# La salida observada contiene: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Mensajes

Las herramientas utilizan el formato de Anthropic (input_schema); fuerza una llamada con tool_choice: {"type": "any"} y desactiva llamadas con {"type": "none"}. ❗ El endpoint oficial de Mensajes de Kimi K3 (compatible con Anthropic) no admite carga dinámica de herramientas: en las pruebas, el mensaje de inyección devuelve 200, pero la herramienta inyectada no tiene efecto (el modelo no puede llamarla). Declara 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": "Obtener el clima para una ciudad",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Hola"}],
)

# Observado: stop_reason "tool_use"; el contenido contiene un bloque tool_use llamando a get_weather

5. Salida Estructurada

La salida estructurada hace que el modelo devuelva contenido que se ajusta estrictamente a un esquema JSON dado.
Chat Completions

response_format admite json_schema con modo strict.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "París es la capital de Francia. Extrae el nombre de la ciudad."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Contenido de respuesta observado: {"city":"París"}

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

La salida estructurada se declara a través de text.format.

response = client.responses.create(
    model="kimi-k3",
    input="París es la capital de Francia. Extrae el nombre de la ciudad.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Texto de salida observado: {"city":"París"}

Mensajes

❗ El endpoint oficial de Mensajes de Kimi K3 (compatible con Anthropic) no admite salida estructurada: los campos de salida estructurada son ignorados silenciosamente: la solicitud devuelve HTTP 200 con texto libre, sin error o aviso de retroceso, y el análisis JSON posterior fallará. Cuando necesites salida estructurada, utiliza la API de Chat Completions o Responses.

6. La Caché de Contexto es Automática

La caché de contexto de K3 se habilita automáticamente, sin parámetros requeridos. Cuando un prefijo largo repetido golpea la caché, la cantidad de golpes se informa en el uso (el nombre del campo varía según la API). La fijación de precios de la caché está en la página del modelo.
Chat Completions

# uso de la segunda llamada con un prefijo largo idéntico
"prompt_tokens_details": {"cached_tokens": 1536}

Verificado: la segunda solicitud con un prefijo largo idéntico informa el golpe en usage.prompt_tokens_details.cached_tokens.
Respuestas

# uso de la segunda llamada de Responses con instrucciones largas idénticas
"input_tokens_details": {"cached_tokens": 1536}

Mensajes

# uso de la segunda llamada de Messages con un aviso del sistema largo idéntico
"cache_read_input_tokens": 1536

7. Compleción de Prefijo partial

La completación de prefijo hace que el modelo continúe generando a partir de un prefijo dado, bien adaptado para la completación de código y salida controlada por formato.
Chat Completions

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

messages = [
    {"role": "user", "content": "Escribe un haiku sobre el mar."},
    {"role": "assistant", "content": "Las olas se pliegan en espuma,", "partial": True},
]

# Prefijo: "Las olas se pliegan en espuma,"  ->  continuación devuelta por el modelo
# la sal flota en el aire—
# la luna atrae la marea a casa.

Verificado: la generación continúa a partir del prefijo dado sin repetirlo.
Respuestas

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

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Escribe un haiku sobre el mar."},
        {"role": "assistant", "content": "Las olas se pliegan en espuma,"},
    ],
)

# Continuación observada: "la sal flota en el aire— / la luna atrae la marea a casa."

Mensajes

La misma capacidad se logra con el autocompletado nativo del asistente del protocolo, sin necesidad de un parámetro partial: pasa el prefijo como el último mensaje del asistente.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Escribe un haiku sobre el mar."},
        {"role": "assistant", "content": "Las olas se pliegan en espuma,"},
    ],
)

# Continuación observada: "el viento salado lleva el llanto de las gaviotas— / la marea tira ..."

8. Entrada de Visión

Las imágenes se pasan como base64; el formato del bloque de contenido varía según la API.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "¿Cuál es el color dominante de esta imagen? Una palabra."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Contenido de respuesta observado: "Rojo"  (entrada: un PNG rojo sólido de 64x64)

Verificado: la entrada de imagen en base64 funciona, y el modelo describe correctamente la imagen de prueba.
Respuestas

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "¿Cuál es el color dominante de esta imagen? Una palabra."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Texto de salida observado: "Rojo"

Mensajes

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "¿Cuál es el color dominante de esta imagen? Una palabra."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Texto de respuesta observado: "Rojo"

9. Referencia Verificada: Latencia y Uso de una Tarea Larga de Llamada Única

El pensamiento de K3 está fijado en el nivel máximo, por lo que las solicitudes únicas para tareas complejas tardan significativamente más que en modelos típicos. Datos medidos de una tarea de generación de juego HTML de un solo archivo (un aviso con una imagen de referencia, generado en un solo intento sin iteración): la solicitud única tomó 2,541 segundos (aproximadamente 42 minutos), con 74,994 tokens de completación, de los cuales 54,486 (73%) eran tokens de pensamiento; la salida final fue de 1,275 líneas de código directamente ejecutable, con finish_reason stop.

Recomendaciones del lado del cliente:

• Establecer tiempos de espera del cliente en minutos o más, y preferir el streaming para tareas largas;
• Dejar suficiente margen en max_completion_tokens: en este caso, solo el pensamiento consumió 54,486 tokens.

10. Capacidad × Matriz de Soporte de API

Cada celda en la tabla a continuación fue verificada el 2026-07-17 a través de llamadas reales a las APIs de producción de AIHubMix; cada celda muestra la sintaxis de parámetro / campo para la API correspondiente.

FAQ

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

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

¿Por qué debe devolverse reasoning_content en conversaciones de múltiples turnos?
K3 está entrenado con pensamiento preservado; Moonshot requiere que el mensaje anterior del asistente se devuelva completo y sin modificar. La falta de historial de pensamiento conduce a una calidad de salida inestable.

¿Cuáles son los límites en el parámetro stop?
Como máximo 5 secuencias de parada, cada una no mayor de 32 bytes; exceder cualquiera de los límites devuelve un error 400.

¿La API de Messages admite salida estructurada?
❗ No. El endpoint oficial de Mensajes de Kimi K3 ignora silenciosamente los campos de salida estructurada (devolviendo 200 con texto libre y sin error). Para salida estructurada, utiliza response_format en Chat Completions o text.format en Responses.

¿Por qué las solicitudes únicas de K3 tardan tanto?
El pensamiento de K3 está fijado en el nivel máximo, y los tokens de pensamiento constituyen una gran parte en tareas complejas (73% de los tokens de completación en el caso medido). Establece los tiempos de espera del cliente en minutos o más y utiliza streaming.

Para precios y estado en tiempo real, consulta la página del modelo Kimi K3; para más modelos, visita la galería de modelos.

Última actualización: 2026-07-17