¿Cómo usar la API de Kimi K3?

Moonshot AI lanzó Kimi K3 el 16 de julio de 2026, y lo denominó su modelo más capaz hasta la fecha: el primer modelo abierto de clase 3T del mundo, con un diseño de Mezcla de Expertos de 2.8T parámetros y una ventana de contexto de 1,048,576 tokens. La parte interesante para los desarrolladores no es el tamaño, sino la API. Kimi K3 habla el dialecto del SDK de OpenAI, así que si ya utilizas GPT o cualquier endpoint compatible con OpenAI, puedes apuntar el mismo cliente a kimi-k3 y empezar a recibir respuestas en streaming en pocos minutos. Esta guía te explica cómo obtener una clave, la guía de inicio rápido en Python, JavaScript y cURL, el streaming, las llamadas a herramientas, el modo JSON, el parámetro de esfuerzo de razonamiento configurable y el almacenamiento en caché de contexto que hace que las entradas con acierto de caché sean aproximadamente diez veces más baratas que las entradas con fallo de caché. Luego probarás y depurarás esas llamadas en Apidog para que puedas ver la solicitud en bruto y los eventos enviados por el servidor en lugar de adivinar.

En resumen

El ID del modelo de API es kimi-k3. En OpenRouter, el slug es moonshotai/kimi-k3.
El endpoint es compatible con el SDK de OpenAI. Configura base_url, configura api_key, configura model="kimi-k3", listo. Confirma la URL base exacta en la consola en platform.kimi.ai; Kimi ha utilizado históricamente https://api.moonshot.ai/v1.
La ventana de contexto es de 1M de tokens. El precio es de $0.30 por millón de tokens de entrada con acierto de caché, $3.00 por millón de tokens de entrada con fallo de caché y $15.00 por millón de tokens de salida.
Streaming, llamadas a herramientas, modo JSON, salida estructurada y un parámetro reasoning_effort (max está disponible hoy) funcionan a través del formato estándar de chat-completions.
Las cargas de trabajo de codificación más antiguas o de bajo presupuesto aún pueden ajustarse mejor a la línea K2.7; a continuación se incluye una nota sobre la elección.
Importa la solicitud a Apidog para inspeccionar el streaming, depurar las llamadas a herramientas, almacenar tu clave como variable de entorno y realizar pruebas A/B de kimi-k3 contra kimi-k2-7-code.

Qué modelo Kimi deberías usar

Antes de escribir cualquier código, elige el objetivo correcto. Kimi K3 es el modelo de vanguardia de la familia: un MoE grande diseñado para codificación compleja, trabajo de agente de largo alcance y tareas de conocimiento sobre contextos largos. Tiene el costo de salida por token más alto de la línea, y la propia publicación de lanzamiento de Moonshot es sincera al decir que K3 está por detrás de Claude Fable 5 y GPT-5.6 Sol en sus comparaciones internas. Es fuerte, no un ganador claro en la vanguardia, y su precio es acorde.

Si tu carga de trabajo es un asistente de codificación de alto volumen, un escritor de pruebas de CI o cualquier cosa en la que pagues por llamada a escala, la línea K2.7 Code más antigua suele ser la más adecuada en cuanto a costo. Comienza con la guía de API de Kimi K2.7 Code y el resumen de qué es Kimi K2.7 Code para ver si ese nivel cubre tu caso. Para una comparación lado a lado de capacidad y precio, la comparación Kimi K3 vs Kimi K2.7 Code expone dónde gana cada uno. Utiliza kimi-k3 cuando necesites una mayor profundidad de razonamiento, el contexto completo de 1M o la orquestación de herramientas de agente; baja a K2.7 cuando la tarea es rutinaria y el volumen es alto. Si quieres un resumen completo de las capacidades primero, la explicación qué es Kimi K3 cubre la arquitectura y la posición del modelo.

Obtén una clave API en la plataforma Kimi

Dirígete a platform.kimi.ai e inicia sesión. La nueva consola es donde creas claves, monitoreas el uso y confirmas la URL base para tu cuenta.

Abre la sección de claves API de la consola y crea una nueva clave.
Cópiala una vez y guárdala en un lugar seguro. No volverás a ver el valor completo.
Agrega crédito o confirma tu nivel de facturación para que las llamadas a kimi-k3 no sean rechazadas por saldo insuficiente.
Toma nota de la URL base que se muestra en la consola. Kimi ha utilizado históricamente https://api.moonshot.ai/v1; la consola es la fuente de verdad para tu cuenta.

Exporta la clave como una variable de entorno para que nunca termine en tu código fuente:

export KIMI_API_KEY="sk-tu-clave-aqui"

Ese simple hábito mantiene los secretos fuera del historial de git y de las capturas de pantalla. Más tarde, cuando pruebes en Apidog, almacenarás el mismo valor como variable de entorno allí también, de modo que la clave resida exactamente en dos lugares que tú controlas.

Para un desglose completo de los cálculos de aciertos y fallos de caché y cómo se traducen en facturas mensuales reales, consulta la guía de precios de Kimi K3.

Inicio rápido: tu primera llamada a kimi-k3

La API de Kimi sigue el contrato de chat-completions de OpenAI, por lo que los SDK oficiales de OpenAI funcionan con dos cambios: la base_url y el model. Instala el SDK que prefieras y luego ejecuta uno de los fragmentos a continuación.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Kimi es compatible con OpenAI-SDK. Confirma la URL base exacta en la
    # consola en platform.kimi.ai; Kimi ha utilizado históricamente el valor a continuación.
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Eres un asistente de codificación preciso."},
        {"role": "user", "content": "Explica qué hace un limitador de velocidad de cubo de tokens en un párrafo."},
    ],
)

print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Confirma la URL base en la consola de platform.kimi.ai.
  baseURL: "https://api.moonshot.ai/v1",
});

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "system", content: "Eres un asistente de codificación preciso." },
    { role: "user", content: "Explica qué hace un limitador de velocidad de cubo de tokens en un párrafo." },
  ],
});

console.log(response.choices[0].message.content);

cURL

curl "$KIMI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explica qué hace un limitador de velocidad de cubo de tokens en un párrafo."}
    ]
  }'

Establece KIMI_BASE_URL a lo que te muestre la consola (por ejemplo, https://api.moonshot.ai/v1). Si alguna de estas devuelve un 401, la clave es incorrecta o no está configurada. Un 404 en la ruta generalmente significa que la URL base es incorrecta, no que el modelo falta. La documentación del SDK de OpenAI para Python cubre las opciones del cliente con más detalle, y cada opción se aplica aquí porque el formato de comunicación es el mismo.

Respuestas en streaming

Para las interfaces de usuario de chat y las interacciones largas de los agentes, querrás los tokens a medida que llegan en lugar de esperar la finalización completa. Configura stream=True e itera sobre los deltas.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Escribe un poema de 6 líneas sobre pruebas inestables."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

Por debajo, esto es un flujo de eventos enviados por el servidor (SSE): cada línea es un marco data: que transporta un pequeño fragmento JSON, y el flujo termina con data: [DONE]. El SDK te oculta este formato, lo cual es conveniente hasta que algo se rompe a mitad del flujo y necesitas ver los marcos en bruto. Ese es un lugar donde la sección de Apidog a continuación se justifica.

La misma bandera funciona en JavaScript:

const stream = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Escribe un poema de 6 líneas sobre pruebas inestables." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Llamadas a herramientas (llamada a funciones)

Kimi K3 admite llamadas a herramientas, restricciones de elección de herramientas y carga dinámica de herramientas, para que puedas conectarlo a agentes que leen archivos, acceden a API o ejecutan comandos de terminal. Describes tus funciones con JSON Schema, el modelo decide cuándo llamar a una, y tú devuelves el resultado en un mensaje de tool.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtener el clima actual de una ciudad.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Nombre de la ciudad, por ejemplo, Singapur"},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "¿Qué tiempo hace en Singapur ahora mismo?"}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = first.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # get_weather
print(tool_call.function.arguments)  # {"city": "Singapur"}

El modelo no ejecuta tu función; te entrega un nombre y argumentos JSON. Tú ejecutas el trabajo real, luego retroalimentas la salida para que el modelo pueda escribir una respuesta final:

import json

# Agrega la respuesta del asistente que solicitó la herramienta, luego el resultado de la herramienta.
messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps({"city": "Singapur", "temp_c": 31, "sky": "húmedo"}),
})

final = client.chat.completions.create(model="kimi-k3", messages=messages, tools=tools)
print(final.choices[0].message.content)

Establece tool_choice="required" para forzar una llamada a una herramienta, o pasa un objeto {"type": "function", "function": {"name": "get_weather"}} específico para fijar una función. Esas restricciones mantienen a un agente en el camino correcto cuando ya sabes qué herramienta debe activarse.

Una peculiaridad específica de K3 que vale la pena conocer de antemano: el modelo fue entrenado en modo de historial de pensamiento preservado. Si el arnés de tu agente elimina el razonamiento anterior del modelo entre turnos, la calidad de la generación puede volverse inestable. Cuando construyas un bucle de agente multiturno, pasa el historial completo de mensajes en lugar de recortar los turnos internos del asistente.

Modo JSON y salida estructurada

Cuando necesites una salida legible por máquina, solicita JSON directamente en lugar de analizar prosa. Configura response_format a json_object e instruye al modelo para que devuelva JSON.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Devuelve solo JSON válido. Sin prosa, sin markdown."},
        {"role": "user", "content": "Extrae el nombre y el rol de: 'Ada Lovelace, matemática'."},
    ],
    response_format={"type": "json_object"},
)

print(response.choices[0].message.content)  # {"name": "Ada Lovelace", "role": "mathematician"}

Para garantías más estrictas, Kimi admite la salida estructurada según un esquema. Si tu versión del SDK lo acepta, pasa un formato de respuesta json_schema para que el modelo se ajuste a tu forma:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Extrae el nombre y el rol de: 'Ada Lovelace, matemática'."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"},
                },
                "required": ["name", "role"],
            },
        },
    },
)

Confirma el soporte de json_schema para tu cuenta en la consola antes de implementarlo; en caso de duda, json_object más un paso de validación de tu parte es el respaldo seguro. Kimi también expone un modo parcial y búsqueda en internet, lo que ayuda cuando deseas precargar una respuesta del asistente o fundamentar respuestas con datos frescos.

Esfuerzo de razonamiento configurable

Kimi K3 expone un parámetro reasoning_effort que controla cuánto piensa el modelo antes de responder. Hoy el nivel disponible es max, que también es el predeterminado; Moonshot ha dicho que se planean niveles más bajos y más altos. Pensar más profundamente cuesta más tokens de salida y añade latencia, por lo que es una palanca que se ajusta por tarea.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Planifica una migración de REST a GraphQL para una API de 40 endpoints."}],
    reasoning_effort="max",
)

Si tu versión del SDK de OpenAI rechaza el campo por desconocido, pásalo a través del escape en su lugar:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Planifica una migración de REST a GraphQL."}],
    extra_body={"reasoning_effort": "max"},
)

El patrón extra_body es la forma de enviar cualquier campo específico del proveedor que el SDK base aún no modele, lo cual es común cuando un endpoint compatible avanza más rápido que la biblioteca cliente.

Prueba y depura kimi-k3 en Apidog

El código SDK oculta el formato de comunicación, lo cual está bien hasta que una llamada a una herramienta devuelve una forma incorrecta o una transmisión se interrumpe y no puedes saber si el error es tuyo o del endpoint. Aquí es donde un cliente API que habla HTTP puro rinde frutos. Apidog te permite enviar la solicitud exacta de kimi-k3, observar la transmisión SSE cuadro por cuadro y mantener tu clave fuera del cuerpo de la solicitud. Si prefieres probar llamadas API sin vivir en una terminal, este es un bucle más limpio que "cURL-y-entrecerrar los ojos"; el tutorial pruebas de APIs sin Postman cubre el flujo de trabajo general.

Aquí tienes un bucle enfocado para kimi-k3:

Crea una nueva solicitud HTTP en Apidog. Establece el método en POST y la URL en tu URL base más /chat/completions.
Almacena tu clave como una variable de entorno. En la configuración del entorno de Apidog, agrega KIMI_API_KEY, luego establece el encabezado Authorization en Bearer {{KIMI_API_KEY}}. Ahora la clave secreta se referencia, no se pega, y puedes cambiar entre claves de prueba y producción cambiando de entorno.
Pega un cuerpo JSON con "model": "kimi-k3" y tu array de messages. Envíalo y lee la respuesta completa, incluido el uso de tokens, para que puedas ver los recuentos de aciertos y fallos de caché en llamadas reales.
Activa "stream": true y observa cómo llegan los eventos enviados por el servidor como cuadros discretos. Ver los fragmentos brutos de data: hace que los errores de transmisión sean obvios de una manera que el iterador ordenado del SDK no lo hace.
Depura las llamadas a herramientas inspeccionando el array tool_calls en la respuesta. Cuando los argumentos regresan mal formados, puedes ver si el modelo produjo un JSON defectuoso o si tu esquema era ambiguo, y corregir la descripción allí mismo.
Realiza pruebas A/B contra kimi-k2-7-code. Duplica la solicitud, cambia solo el campo model y compara la latencia, la calidad de la salida y el costo en el mismo prompt. Esa es la forma más honesta y rápida de decidir si la profundidad de razonamiento adicional de K3 justifica el salto de precio para tu tarea.

Debido a que Apidog importa solicitudes compatibles con OpenAI directamente, puedes pegar un comando cURL y obtener una solicitud guardada y reproducible con los encabezados y el cuerpo ya rellenados. A partir de ahí, se convierte en un caso de prueba compartido que tu equipo puede volver a ejecutar cada vez que Kimi lance una actualización. Si tu agente se comunica con el modelo a través de MCP, la guía depuración visual con el cliente MCP de Apidog muestra cómo rastrear esas llamadas también. Descarga Apidog si quieres seguir este bucle con tu propia clave.

Casos de uso en el mundo real

Algunos patrones se adaptan perfectamente a lo que kimi-k3 está diseñado para:

Agentes de codificación a escala de repositorio. El contexto de 1M y la orquestación de herramientas de agente permiten al modelo manejar una gran base de código, ejecutar pruebas, leer registros e iterar. Almacena el resumen del código base como un prefijo estable y mantendrás el costo por turno razonable.
Trabajo de conocimiento con documentos largos. Alimenta una especificación completa, un contrato o un corpus de investigación y solicita una extracción estructurada con json_schema. Mantén el documento al principio del prompt para que las consultas repetidas acierten en la caché.
Planificación de migraciones y refactorizaciones. Ajusta reasoning_effort a max para la fase de planificación, donde un pensamiento más profundo rinde frutos, luego vuelve a un modelo más económico para las ediciones mecánicas.
Respuestas de investigación fundamentadas. Con la búsqueda en internet y las llamadas a herramientas, K3 puede obtener datos frescos y citarlos, lo que es adecuado para asistentes que no pueden depender de conocimientos de entrenamiento obsoletos.

En cada uno de estos, el flujo de trabajo es el mismo: construye la solicitud con el SDK, verifica el comportamiento bruto en Apidog y luego incorpóralo a tu aplicación una vez que confíes en la forma.

Conclusión

Llamar a Kimi K3 se reduce a tres configuraciones en un cliente compatible con OpenAI: la URL base de tu consola, tu clave API y model="kimi-k3". A partir de ahí, el streaming, las llamadas a herramientas, el modo JSON, la salida estructurada y el reasoning_effort siguen el contrato de chat-completions que ya conoces. Las dos cosas que vale la pena internalizar son la economía del almacenamiento en caché, donde mantener un prefijo estable convierte una entrada de $3.00 en una entrada de $0.30, y la honesta compensación de que K3 compra profundidad de razonamiento a un precio real, así que dirige el trabajo rutinario de alto volumen a la línea K2.7. Construye la solicitud en código, pruébala en Apidog y desplegarás contra kimi-k3 sin sorpresas.

Preguntas frecuentes

¿Cuál es el ID del modelo de API para Kimi K3? Es kimi-k3 en la propia plataforma de Kimi. Si lo llamas a través de OpenRouter, el slug es moonshotai/kimi-k3. Puedes leer el listado del modelo en OpenRouter en openrouter.ai/moonshotai/kimi-k3.

¿Qué URL base debo usar? Confírmala en la consola en platform.kimi.ai, ya que esa es la fuente de verdad para tu cuenta. Kimi ha utilizado históricamente https://api.moonshot.ai/v1. En el código, mantenla como una variable base_url que configures desde la consola en lugar de codificarla directamente.

¿Es Kimi K3 compatible con el SDK de OpenAI? Sí. La API sigue el formato de chat-completions de OpenAI, por lo que los SDK oficiales de OpenAI para Python y JavaScript funcionan después de cambiar base_url y model. Los campos específicos del proveedor se pasan a través de extra_body.

¿Cuánto cuesta la API de Kimi K3? $0.30 por millón de tokens de entrada con acierto de caché, $3.00 por millón de tokens de entrada con fallo de caché y $15.00 por millón de tokens de salida. Estructurar los prompts para la reutilización de la caché es la mayor palanca para tu factura. La guía de precios de Kimi K3 detalla los números.

¿Qué hace realmente el almacenamiento en caché de contexto? Cuando los tokens iniciales de tu solicitud coinciden con una anterior, el endpoint reutiliza el estado calculado en lugar de volver a calcularlo, lo que reduce el costo de entrada de $3.00 a $0.30 por millón en esa porción. Mantén tu prompt del sistema y el contexto compartido al principio e idénticos en todas las llamadas para maximizar los aciertos.

¿Puedo controlar cuánto piensa el modelo? Sí, a través de reasoning_effort. El nivel disponible hoy es max, que también es el predeterminado; Moonshot ha dicho que se planean otros niveles. Un mayor esfuerzo cuesta más tokens de salida y añade latencia.

¿Debería usar Kimi K3 o Kimi K2.7 Code? Usa kimi-k3 cuando necesites un razonamiento profundo, el contexto completo de 1M o la orquestación de herramientas de agente. Para trabajo de codificación rutinario de alto volumen, la línea K2.7 más económica suele ser la mejor opción. La comparación Kimi K3 vs Kimi K2.7 Code y la guía de API de Kimi K2.7 Code te ayudarán a decidir.

¿Cómo depuro una respuesta de streaming o de llamada a herramientas rota? Envía la solicitud en bruto en Apidog con "stream": true y lee los eventos enviados por el servidor cuadro por cuadro, o inspecciona el array tool_calls para ver si el modelo devolvió un JSON mal formado. Almacenar tu clave como una variable de entorno la mantiene fuera del cuerpo de la solicitud mientras pruebas.