Kimi API es compatible con la interfaz de OpenAI, así que una migración suele requerir solo tres cambios: Base URL, API Key y nombre del modelo. Sin embargo, en 2026 hay varios detalles de la interfaz que se prestan a error: los modelos antiguos ya fueron retirados, max_tokens está en desuso, K3 usa por defecto la intensidad de razonamiento máxima y el consumo de las solicitudes en streaming solo llega en el último bloque.

Este artículo recorre la integración desde cero: primero confirma el sitio y el protocolo, luego ayuda a elegir el modelo, después completa la primera llamada con curl y Python, y al final entrega una lista de migración y una tabla de errores. Los modelos y precios se rigen por la página de precios de modelos.

Nota: Moonshot y Kimi son marcas de sus respectivos titulares; este artículo solo describe la integración técnica. La lista de modelos, la longitud de contexto y las reglas de parámetros pueden cambiar; consulta siempre la versión vigente de la documentación oficial.

1. Confirma tres cosas antes de integrar

  1. Sitio: el sitio chino usa platform.kimi.com; el internacional, platform.kimi.ai. Las cuentas, el saldo y las claves de ambos sitios son totalmente independientes.
  2. Protocolo: la mayoría de los proyectos usa Chat Completions compatible con OpenAI; los proyectos que ya tienen el SDK de Anthropic pueden usar la entrada compatible con Messages.
  3. Modelo: confirma primero qué modelos ve tu cuenta y luego escríbelos en el código. No copies tutoriales de hace varios meses.

El dominio de solicitudes del sitio chino es https://api.moonshot.cn; el del internacional, https://api.moonshot.ai. El dominio y la clave deben corresponder; esta es una de las causas más frecuentes de un 401.

2. Base URL y rutas de la interfaz

Protocolo Base URL Ruta de la interfaz
OpenAI Chat Completions https://api.moonshot.cn/v1 /chat/completions
OpenAI Responses https://api.moonshot.cn/v1 /responses
Anthropic Messages https://api.moonshot.cn/anthropic /v1/messages
Lista de modelos https://api.moonshot.cn/v1 /models
Consulta de saldo https://api.moonshot.cn/v1 /users/me/balance

En el sitio internacional se cambia el dominio por api.moonshot.ai y las rutas no varían. En el SDK de OpenAI, base_url se completa hasta /v1 y el SDK añade /chat/completions por su cuenta; con curl hay que escribir la ruta completa. Mezclar ambos estilos produce una capa de /v1 de más o de menos, que se manifiesta como un 404.

La Base URL de la entrada compatible con Anthropic no lleva /v1, a diferencia de la entrada de OpenAI. Al integrar con Claude Code u otro SDK de Anthropic, usa https://api.moonshot.cn/anthropic según el ejemplo oficial.

3. Cómo elegir el nombre del modelo

Nombre del modelo Contexto Tareas adecuadas Observaciones
kimi-k3 1M Razonamiento complejo, ingeniería de software, trabajo con conocimiento, documentos muy largos reasoning_effort es max por defecto
kimi-k2.7-code 256K Generación de código, preguntas sobre repositorios, agentes Mejor seguimiento de instrucciones en contexto largo
kimi-k2.7-code-highspeed 256K Autocompletado de baja latencia, programación interactiva Mismo modelo que la versión estándar, pero más rápido
kimi-k2.6 256K Conversación general, extracción, entrada visual y de texto Admite modo de pensamiento y modo sin pensamiento

Los modelos antiguos ya fueron retirados: toda la familia moonshot-v1 y kimi-k2.5 dejaron de recibir soporte el 31 de agosto de 2026; la familia kimi-k2, el 25 de mayo de 2026, y kimi-latest, antes aún. Los proyectos que todavía usan esos nombres deben migrar directamente a kimi-k3 o a la serie K2 en lugar de seguir buscando documentación antigua.

Para tareas generales no conviene usar K3 por defecto. K3 es potente, pero su intensidad de razonamiento predeterminada es alta, lo que aumenta la latencia y los tokens de salida; para clasificación simple o extracción con formato fijo, kimi-k2.6 suele ser más adecuado. Para tareas de código, considera después la serie K2.7 Code.

4. Primera llamada: curl

export MOONSHOT_API_KEY="tu_clave"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Responde solo: integración correcta"}
    ],
    "max_completion_tokens": 64
  }'

Si devuelve 200 y el contenido es el esperado, la clave, el sitio, el nombre del modelo y la ruta son correctos. Si devuelve 401, revisa primero si el sitio y la clave corresponden; si devuelve 404, revisa el nombre del modelo y /v1; si devuelve 400, busca en el mensaje de error si menciona el contexto o el límite de salida.

5. SDK de Python y salida en streaming

Instala el SDK de OpenAI 1.0 o superior y cambia base_url y la clave:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explica en tres puntos qué tipo de equipos se beneficia de un gateway de API"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nUso:", chunk.usage)

La respuesta en streaming es SSE, cada línea comienza con data: y termina con data: [DONE]. Al activar include_usage, antes del final llega un bloque adicional con choices vacío que solo contiene usage. Si la conexión se interrumpe a mitad de camino, ese bloque puede no recibirse, así que no conviene depender por completo del cliente para contabilizar el consumo.

6. max_completion_tokens e intensidad de razonamiento

max_tokens está en desuso; el código nuevo debe usar max_completion_tokens. Este valor representa la longitud de salida esperada, no la suma de entrada y salida. En K3 el valor predeterminado es 131072 y el máximo configurable es 1048576; si la entrada más ese valor supera la ventana de contexto, la solicitud devuelve invalid_request_error.

Dos reglas prácticas:

  • En pruebas y tareas de formato fijo, usa valores pequeños, por ejemplo de 256 a 1024, para evitar respuestas largas.
  • Al alcanzar el límite, finish_reason es length; en una finalización normal es stop. Si ves length, no reintentes de inmediato: primero decide si la salida realmente necesita más espacio o si el prompt es demasiado abierto.

K3 tiene además un parámetro de nivel superior, reasoning_effort, con valores low, high y max, y valor predeterminado max. En tareas simples, low reduce la latencia y el consumo de tokens; en razonamiento complejo conviene subir el nivel. Con el SDK de OpenAI, si tu versión no incluye este parámetro, pásalo mediante extra_body. El contenido de pensamiento de K3 aparece en reasoning_content y debe devolverse tal cual en conversaciones de varios turnos y en llamadas a herramientas.

7. Migración desde OpenAI o desde versiones antiguas de Moonshot

  1. Inventaría todos los nombres de modelo antiguos en el código y la configuración, y prepara una tabla de reemplazo.
  2. Modifica base_url: sitio chino https://api.moonshot.cn/v1; sitio internacional https://api.moonshot.ai/v1.
  3. Cambia a la clave del sitio correspondiente; no reutilices una clave entre sitios.
  4. Sustituye los nombres de modelo, preferentemente por kimi-k3 o por el modelo vigente de la serie K2.
  5. Cambia max_tokens por max_completion_tokens.
  6. Sustituye la configuración thinking de K2.x por reasoning_effort de K3, sin enviar ambos a la vez.
  7. Añade stream_options={"include_usage": True} a las solicitudes en streaming.
  8. Ejecuta una regresión con el mismo lote de tareas reales y registra calidad, latencia, finish_reason y consumo.
  9. Conserva la configuración anterior durante un ciclo de despliegue y elimínala solo cuando todo esté confirmado.

No hagas la migración completa de una sola vez. Pasa primero al entorno de pruebas, luego a negocios de bajo riesgo y al final a la ruta crítica, dejando en cada paso un interruptor de reversión.

8. Tabla de errores comunes

Código Tipo de error Causa habitual Acción
400 invalid_request_error Parámetros incorrectos, contexto demasiado largo, límite de salida excedido Corregir la solicitud
400 content_filter La entrada o la salida activó la seguridad de contenido Ajustar el prompt
401 invalid_authentication_error Clave inválida o sitio que no corresponde Cambiar la clave o el dominio
404 resource_not_found_error Nombre de modelo o ruta incorrectos Consultar la lista de modelos
429 rate_limit_reached_error Límite de concurrencia, RPM, TPM o TPD excedido Reducir el ritmo o subir de nivel
429 exceeded_current_quota_error Falta de pago o saldo insuficiente Recargar
504 Gateway Time-out Espera demasiado larga en una solicitud larga sin streaming Usar streaming

Una solicitud sin streaming que espere más de 900 segundos en el servidor puede devolver 504. Para generación de textos largos, análisis de documentos extensos y agentes de código conviene usar streaming: el cliente recibe datos de forma continua y se evita el desperdicio de «esperar al timeout y reintentar».

Preguntas frecuentes

¿Hasta qué nivel se completa la Base URL?

En el SDK de OpenAI, usa https://api.moonshot.cn/v1, sin /chat/completions. Con curl hay que escribir la ruta completa https://api.moonshot.cn/v1/chat/completions. En el SDK de Anthropic, usa https://api.moonshot.cn/anthropic.

¿Por qué max_tokens no tiene efecto?

El parámetro está en desuso; algunos modelos lo ignoran o devuelven error. Usa max_completion_tokens y recuerda que es un límite de salida, no un límite de entrada más salida.

¿Por qué K3 responde más lento de lo esperado?

K3 usa reasoning_effort en max por defecto y razona con mayor profundidad. En tareas simples, bajar a low o high y limitar la longitud de salida suele mejorar la latencia de forma notable.

¿Por qué no hay usage al terminar el streaming?

Debes configurar explícitamente stream_options={"include_usage": True}. Incluso así, si la conexión se interrumpe puede no recibirse el último bloque; en producción, contabiliza el consumo también en el servidor.

¿Qué más hay que cambiar al migrar desde OpenAI?

La mayoría del código solo requiere cambiar la Base URL, la clave y el nombre del modelo. Revisa además max_tokens, el consumo en streaming, la equivalencia de tipos de error y la estrategia de reintentos, en especial el tratamiento de los 429.

Siguiente paso

Crea una clave de prueba en ZSQH AI Gateway, ejecuta una tarea real con kimi-k3 y otra con kimi-k2.6, y conecta producción solo después de validar la ruta. Los modelos disponibles y la facturación se rigen por los precios de modelos.

Lecturas relacionadas: