¿Cómo usar la API de Kimi K3?

Moonshot AI lanzó Kimi K3 el 16 de julio de 2026 y lo presentó como su modelo más capaz hasta la fecha: el primer modelo abierto de clase 3T del mundo, con una arquitectura de Mezcla de Expertos (MoE) de 2.8T parámetros y una ventana de contexto de 1,048,576 tokens. Para desarrolladores, lo relevante es su API: Kimi K3 utiliza un formato compatible con el SDK de OpenAI. Si ya consumes GPT u otro endpoint compatible, puedes cambiar la URL base, configurar model="kimi-k3" y recibir respuestas en streaming en minutos. En esta guía verás cómo crear una clave API, hacer llamadas con Python, JavaScript y cURL, activar streaming, usar herramientas, exigir JSON, configurar reasoning_effort y aprovechar la caché de contexto. También probarás las solicitudes en Apidog para inspeccionar solicitudes HTTP y eventos SSE sin depender solo de la abstracción del SDK.

Prueba Apidog hoy

En resumen

• El ID del modelo es kimi-k3. En OpenRouter, el slug es moonshotai/kimi-k3.
• La API es compatible con el SDK de OpenAI. Configura base_url, api_key y model="kimi-k3".
• Confirma la URL base 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 indicado es de $0.30 por millón de tokens de entrada con acierto de caché, $3.00 por millón de tokens de entrada sin acierto de caché y $15.00 por millón de tokens de salida.
• Streaming, llamadas a herramientas, modo JSON, salida estructurada y reasoning_effort funcionan mediante el formato estándar de chat completions.
• Para tareas rutinarias de codificación y alto volumen, K2.7 Code puede resultar más conveniente en coste.
• Puedes importar solicitudes en Apidog, inspeccionar streaming, depurar herramientas y comparar kimi-k3 con kimi-k2-7-code.

Qué modelo Kimi deberías usar

Antes de integrar la API, elige el modelo según la carga de trabajo.

Kimi K3 es el modelo de vanguardia de la familia. Está orientado a codificación compleja, agentes de largo alcance y tareas de conocimiento con contextos extensos. También tiene el mayor coste de salida por token de la línea. La publicación de lanzamiento de Moonshot indica que K3 queda por detrás de Claude Fable 5 y GPT-5.6 Sol en sus comparaciones internas. Es un modelo potente, pero no necesariamente el mejor para cada tarea ni para cada presupuesto.

Para asistentes de codificación de alto volumen, generación de pruebas de CI o flujos donde cada llamada cuenta a escala, K2.7 Code suele ajustarse mejor al coste. Revisa la guía de API de Kimi K2.7 Code y el resumen de qué es Kimi K2.7 Code.

Usa kimi-k3 cuando necesites:

• Más profundidad de razonamiento.
• La ventana completa de contexto de 1M.
• Orquestación de herramientas para agentes.
• Análisis de documentos o repositorios grandes.

Usa K2.7 cuando la tarea sea repetitiva y el volumen sea alto. Para evaluar ambos, consulta la comparación Kimi K3 vs Kimi K2.7 Code. Si necesitas contexto sobre el modelo, revisa qué es Kimi K3.

Obtén una clave API en la plataforma Kimi

Ve a platform.kimi.ai e inicia sesión. Desde la consola puedes crear claves API, revisar el consumo y confirmar la URL base asignada a tu cuenta.

1. Abre la sección de claves API y crea una clave nueva.
2. Copia la clave y guárdala de inmediato. Normalmente no podrás volver a ver el valor completo.
3. Añade crédito o confirma la configuración de facturación para evitar rechazos por saldo insuficiente.
4. Copia la URL base que muestra la consola. Kimi ha utilizado históricamente https://api.moonshot.ai/v1, pero la consola es la fuente de verdad.

Guarda la clave como variable de entorno:

export KIMI_API_KEY="sk-tu-clave-aqui"
export KIMI_BASE_URL="https://api.moonshot.ai/v1"

No incluyas secretos en el código fuente, archivos versionados ni capturas de pantalla. Cuando pruebes la API en Apidog, guarda esa misma clave como variable de entorno del proyecto.

Para cálculos de caché y estimaciones de gasto, consulta la guía de precios de Kimi K3.

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

La API utiliza el contrato de chat completions de OpenAI. En la práctica, basta con cambiar:

• base_url
• api_key
• model

Python

Instala el SDK:

pip install openai

Después, crea el cliente y realiza una llamada:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Confirma la URL base exacta en platform.kimi.ai.
    base_url=os.environ["KIMI_BASE_URL"],
)

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

Instala el paquete:

npm install openai

Luego:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Confirma la URL base en platform.kimi.ai.
  baseURL: process.env.KIMI_BASE_URL,
});

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."
      }
    ]
  }'

Si la respuesta es 401, comprueba la clave API y que la variable de entorno esté cargada. Si recibes 404, revisa la URL base: normalmente indica una ruta incorrecta, no que el modelo no exista.

La documentación del SDK de OpenAI para Python cubre más opciones del cliente. El patrón es aplicable porque Kimi utiliza el mismo formato de comunicación.

Respuestas en streaming

Para interfaces de chat o agentes que ejecutan tareas largas, activa streaming para mostrar tokens a medida que llegan.

Streaming en Python

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)

La respuesta usa Server-Sent Events (SSE). Cada evento llega como una línea data: que contiene un fragmento JSON. El flujo termina con:

data: [DONE]

El SDK abstrae esos detalles, pero inspeccionar los eventos en bruto es útil si un stream se interrumpe o un fragmento no tiene la forma esperada.

Streaming 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

Kimi K3 admite llamadas a herramientas, restricciones de selección de herramientas y carga dinámica de herramientas. El flujo es el habitual:

1. Defines funciones con JSON Schema.
2. El modelo decide si debe llamar una herramienta.
3. Tu aplicación ejecuta la operación real.
4. Devuelves el resultado en un mensaje con rol tool.
5. El modelo genera una respuesta final.

Define una herramienta

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 la función. Solo devuelve el nombre y los argumentos. Debes validar los argumentos, ejecutar la integración real y devolver el resultado.

Devuelve el resultado de la herramienta

import json

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)

Usa estas opciones según el comportamiento que necesites:

tool_choice = "auto"

Permite que el modelo decida si llama una herramienta.

tool_choice = "required"

Obliga al modelo a usar alguna herramienta.

tool_choice = {
    "type": "function",
    "function": {"name": "get_weather"},
}

Fuerza una herramienta específica.

K3 fue entrenado en un modo de historial de pensamiento preservado. En agentes multiturno, evita eliminar turnos internos del asistente si quieres mantener una generación estable. Pasa el historial completo de mensajes cuando sea posible.

Modo JSON y salida estructurada

Para integraciones que consumen resultados de forma programática, solicita JSON en lugar de analizar texto libre.

JSON simple

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

Aunque uses json_object, valida siempre la respuesta antes de procesarla en producción:

import json

data = json.loads(response.choices[0].message.content)

JSON Schema

Si la versión de tu SDK y tu cuenta lo admiten, usa json_schema para exigir una forma concreta:

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 en la consola antes de depender de él. Si no está disponible, utiliza json_object y valida el resultado en tu aplicación.

Kimi también expone un modo parcial y búsqueda en internet, útiles para precargar respuestas o fundamentarlas en información actualizada.

Esfuerzo de razonamiento configurable

Kimi K3 incluye el parámetro reasoning_effort, que controla cuánto razona el modelo antes de responder.

Actualmente, el nivel disponible es max, que también es el valor predeterminado. Un mayor esfuerzo puede aumentar los tokens de salida y la latencia, así que úsalo en tareas donde el razonamiento adicional compense el coste.

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 rechaza el parámetro, envíalo mediante extra_body:

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"},
)

extra_body permite enviar campos específicos del proveedor que el SDK base todavía no modela.

Prueba y depura Kimi K3 en Apidog

El SDK simplifica la integración, pero también oculta detalles útiles durante la depuración: encabezados, cuerpos HTTP, eventos SSE y la estructura completa de tool_calls.

Apidog permite enviar la solicitud HTTP exacta, guardar variables de entorno, inspeccionar streams y comparar respuestas sin depender únicamente de la terminal. Para un flujo de pruebas general, revisa la guía de pruebas de APIs sin Postman.

Sigue este flujo:

1. Crea una solicitud HTTP nueva.
2. Configura el método POST.
3. Usa la URL:

   {{KIMI_BASE_URL}}/chat/completions

1. Añade los encabezados:

   Authorization: Bearer {{KIMI_API_KEY}}
   Content-Type: application/json

1. Guarda KIMI_API_KEY y KIMI_BASE_URL como variables de entorno en Apidog.
2. Usa un cuerpo de solicitud como este:

   {
     "model": "kimi-k3",
     "messages": [
       {
         "role": "user",
         "content": "Explica qué hace un limitador de velocidad de cubo de tokens."
       }
     ]
   }

1. Envía la solicitud e inspecciona la respuesta completa, incluido el uso de tokens.
2. Añade "stream": true para observar los eventos SSE como fragmentos data:.
3. Para herramientas, revisa el array tool_calls y verifica que los argumentos devueltos coincidan con tu esquema.
4. Duplica la solicitud, cambia solo model a kimi-k2-7-code y compara latencia, calidad y coste con el mismo prompt.

Apidog puede importar solicitudes compatibles con OpenAI desde un comando cURL. Esto facilita convertir una prueba manual en una solicitud guardada y reproducible para todo el equipo.

Si tu agente usa MCP, consulta la guía de depuración visual con el cliente MCP de Apidog. Puedes descargar Apidog para probar este flujo con tu propia clave.

Casos de uso en el mundo real

Estos patrones encajan con las capacidades de kimi-k3:

• Agentes de codificación a escala de repositorio. El contexto de 1M y la orquestación de herramientas permiten trabajar sobre bases de código grandes, ejecutar pruebas, leer logs e iterar sobre cambios. Mantén el resumen del repositorio como prefijo estable para aumentar los aciertos de caché.

• Trabajo de conocimiento con documentos extensos. Envía una especificación, contrato o corpus de investigación y solicita una extracción estructurada con json_schema. Coloca el documento compartido al principio del prompt para reutilizar la caché en consultas posteriores.

• Planificación de migraciones y refactorizaciones. Usa reasoning_effort="max" en la fase de planificación. Para ediciones mecánicas posteriores, considera un modelo más económico.

• Respuestas de investigación fundamentadas. Con búsqueda en internet y llamadas a herramientas, K3 puede recuperar información reciente y citarla. Esto resulta útil para asistentes que no pueden depender solo del conocimiento de entrenamiento.

En todos los casos, el flujo recomendado es el mismo:

1. Construye la solicitud en código.
2. Comprueba la solicitud HTTP y la respuesta en Apidog.
3. Añade validaciones para herramientas y JSON.
4. Integra el flujo validado en tu aplicación.

Conclusión

Integrar Kimi K3 requiere tres configuraciones en un cliente compatible con OpenAI:

base_url = "tu URL de la consola"
api_key = "tu clave API"
model = "kimi-k3"

A partir de ahí, streaming, herramientas, modo JSON, salida estructurada y reasoning_effort siguen el contrato de chat completions.

Los dos puntos principales para producción son:

• Optimizar la caché de contexto. Mantén idénticos y al inicio del prompt el sistema y el contexto compartido. Un acierto de caché reduce el coste de entrada indicado de $3.00 a $0.30 por millón de tokens en esa porción.
• Elegir el modelo según la tarea. K3 ofrece más profundidad de razonamiento, pero tiene un coste real. Para cargas rutinarias y de alto volumen, K2.7 puede ser una alternativa más eficiente.

Construye la solicitud con el SDK, valídala en Apidog y despliega una vez que conozcas la forma exacta de las respuestas.

Preguntas frecuentes

¿Cuál es el ID del modelo de API para Kimi K3?

Es kimi-k3 en la plataforma de Kimi. En OpenRouter, el slug es moonshotai/kimi-k3. Consulta el listado en openrouter.ai/moonshotai/kimi-k3.

¿Qué URL base debo usar?

Confírmala en platform.kimi.ai, ya que es la fuente de verdad para tu cuenta. Kimi ha utilizado históricamente:

https://api.moonshot.ai/v1

Configúrala como variable de entorno en lugar de codificarla directamente.

¿Es Kimi K3 compatible con el SDK de OpenAI?

Sí. La API usa el formato de chat completions de OpenAI. Los SDK oficiales de OpenAI para Python y JavaScript funcionan después de cambiar base_url y model. Para campos específicos del proveedor, usa extra_body.

¿Cuánto cuesta la API de Kimi K3?

El precio indicado es:

• $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é.
• $15.00 por millón de tokens de salida.

La reutilización de caché es una de las principales palancas para controlar el gasto. Consulta la guía de precios de Kimi K3.

¿Qué hace el almacenamiento en caché de contexto?

Cuando los tokens iniciales de una solicitud coinciden con una solicitud anterior, el endpoint puede reutilizar el estado calculado. Esto reduce el coste de entrada indicado de $3.00 a $0.30 por millón de tokens en esa parte de la entrada.

Para aumentar los aciertos:

• Mantén el prompt del sistema al principio.
• Mantén el contexto compartido idéntico entre llamadas.
• Añade la parte dinámica del prompt después del prefijo estable.

¿Puedo controlar cuánto piensa el modelo?

Sí, mediante reasoning_effort. El nivel disponible actualmente es max, que también es el predeterminado. Un mayor esfuerzo puede aumentar los tokens de salida y la latencia.

¿Debería usar Kimi K3 o Kimi K2.7 Code?

Usa kimi-k3 cuando necesites razonamiento profundo, contexto de 1M o herramientas de agente. Para trabajo rutinario de codificación a gran escala, K2.7 suele ser más económico.

Consulta la comparación Kimi K3 vs Kimi K2.7 Code y la guía de API de Kimi K2.7 Code.

¿Cómo depuro una respuesta de streaming o una llamada a herramientas rota?

Envía la solicitud HTTP en Apidog con:

{
  "stream": true
}

Después, inspecciona los eventos SSE data: cuadro por cuadro. Para herramientas, revisa tool_calls y valida si el modelo devolvió argumentos JSON incorrectos o si tu esquema necesita una descripción más precisa. Guarda la clave como variable de entorno para no incluirla en el cuerpo de la solicitud.