La API de Moonshot sigue siendo compatible con la interfaz de OpenAI, pero en 2026 cambiaron dos cosas: la consola se trasladó a la plataforma de API de Kimi y toda la serie moonshot-v1 dejó de funcionar el 31 de agosto. Cuando un proyecto antiguo copia la configuración anterior, el resultado habitual no es un 401, sino un 404 model_not_found. Este artículo sigue el orden «elige el sitio, elige el modelo, haz la primera llamada y migra»; los modelos y los precios se rigen por los 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 los parámetros pueden cambiar; toma como referencia la versión actual de la documentación oficial.

1. La entrada cambió, el dominio de la API no

platform.moonshot.cn ahora redirige a platform.kimi.com, y el sitio internacional platform.moonshot.ai redirige a platform.kimi.ai. La consola, las cuentas, el saldo y las claves se gestionan en la plataforma de API de Kimi.

El dominio de las solicitudes API no cambió: el sitio chino usa https://api.moonshot.cn y el internacional, https://api.moonshot.ai. Una clave del sitio chino solo funciona con el dominio chino, y lo mismo vale para el sitio internacional. Si el base_url del código no está definido, la solicitud puede terminar en OpenAI u otro proveedor; el error típico es model_not_found. Anota por separado «dirección de la consola» y «dirección de la API» para no confundirlas durante una migración.

2. Tres protocolos compatibles y sus Base URL

  • OpenAI Chat Completions: Base URL https://api.moonshot.cn/v1, ruta /chat/completions.
  • OpenAI Responses: la misma Base URL, ruta /responses.
  • Anthropic Messages: Base URL https://api.moonshot.cn/anthropic, ruta /v1/messages.
  • Lista de modelos: GET https://api.moonshot.cn/v1/models.

En el sitio internacional se cambia el dominio por api.moonshot.ai y las rutas se mantienen. En el SDK de OpenAI, base_url se completa hasta /v1, y el SDK agrega la ruta de la interfaz; con curl hay que escribir la ruta completa. La entrada de Anthropic no lleva el sufijo /v1, a diferencia de la de OpenAI. La documentación oficial exige el SDK de OpenAI 1.0.0 o superior y Python 3.8+ o Node.js 18+.

3. Cómo elegir la familia de modelos actual

Modelo Contexto Tareas adecuadas Observaciones
kimi-k3 1M Razonamiento complejo, documentos largos, agentes, trabajo con conocimiento reasoning_effort vale max por defecto
kimi-k2.7-code 256K Generación de código, preguntas sobre repositorios, agentes de programación El modo de pensamiento suele estar activo; no admite reasoning_effort
kimi-k2.7-code-highspeed 256K Autocompletado de baja latencia, programación interactiva Versión rápida del mismo modelo, con salida más ágil
kimi-k2.6 256K Conversación general, extracción, multimodalidad Admite modo de pensamiento y modo normal

Si dudas, empieza con kimi-k3; para clasificaciones simples y extracción con formato fijo suele encajar mejor kimi-k2.6; para tareas de código, considera la serie K2.7 Code.

El punto más delicado son los parámetros de muestreo. La temperatura de los modelos actuales es fija: 1.0 en K3 y K2.7 Code, y en K2.6 es 1.0 con pensamiento y 0.6 sin pensamiento. No envíes temperature de forma explícita, porque un valor distinto del fijo produce error; top_p también está fijado en 0.95 y no debe ajustarse.

4. Primera llamada con 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: conexión correcta"}
    ],
    "max_completion_tokens": 64
  }'

Si devuelve 200 y el contenido es el esperado, significa que la clave, el sitio, el nombre del modelo y la ruta están bien. Si devuelve 401, revisa primero si la clave corresponde al sitio; si devuelve 404, revisa el nombre del modelo, el /v1 y si el modelo fue retirado; si devuelve 400, mira si el mensaje de error menciona el contexto o el límite de salida. Algunas integraciones exigen variantes del nombre, por ejemplo Claude Code puede necesitar kimi-k3[1m]; consulta la documentación de cada integración.

5. SDK de Python y salida en streaming

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é equipos se benefician 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 empieza con data: y el flujo termina con data: [DONE]. Al activar include_usage, antes del final llega un bloque adicional con choices vacío y solo el campo usage; si la conexión se interrumpe, ese bloque puede no recibirse, así que en producción conviene llevar una contabilidad aparte en el servidor.

En conversaciones de varios turnos y llamadas a herramientas hay que cuidar el contenido de razonamiento. En K3, el resultado del razonamiento viaja en reasoning_content, y K2.x tiene un campo similar; al devolver el mensaje del asistente, hay que incluirlo tal cual. K3 controla la intensidad con reasoning_effort en el nivel superior; en K2.x, el parámetro thinking se envía dentro de extra_body. No envíes ambos a la vez.

6. Migración desde moonshot-v1

Los modelos antiguos ya están retirados y seguir llamándolos devuelve model_not_found. Estas son las sustituciones habituales, sujetas a la lista oficial de modelos.

Modelo antiguo Sustituto sugerido Nota de migración
moonshot-v1-8k/32k/128k/auto kimi-k2.6 o kimi-k3 Ya no se distinguen por 8K, 32K o 128K
moonshot-v1-*-vision-preview kimi-k3 o kimi-k2.6 Las imágenes pasan a bloques image_url
Serie kimi-k2 kimi-k3 Retirada el 2026-05-25
kimi-k2.5 kimi-k3 Retirada el 2026-08-31
kimi-latest kimi-k3 Retirada el 2026-01-28

Pasos de migración:

  1. Busca en todo el código y la configuración los nombres de modelo antiguos y el base_url, y prepara una tabla de reemplazos.
  2. Cambia el base_url y confirma si usas el sitio chino o el internacional; si cruzas de sitio, cambia también la clave.
  3. Sustituye los nombres de modelo; usa kimi-k3 por defecto y evalúa kimi-k2.6 para tareas cortas sensibles al costo.
  4. Cambia max_tokens por max_completion_tokens. En K3 el valor por defecto es 131072 y el límite de salida es 1048576 menos la longitud de entrada; en la serie K2, el límite ronda 256K menos la entrada.
  5. Elimina temperature y top_p personalizados y usa los valores fijos del modelo.
  6. Reemplaza la configuración antigua de thinking: en K3 usa reasoning_effort; en K2.x envía thinking mediante extra_body.
  7. Convierte el contenido multimodal a bloques text, image_url y video_url.
  8. Agrega stream_options={"include_usage": True} a las solicitudes en streaming.
  9. Ejecuta una regresión con el mismo lote de tareas reales, registra calidad, latencia, finish_reason y consumo, y despliega por etapas con una opción de reversión.

No migres todo de una vez. Empieza por el entorno de pruebas, sigue con los procesos de bajo riesgo y deja para el final la ruta crítica; cada paso debe poder revertirse.

7. Lista de validación antes de salir a producción

  • Llama a GET /v1/models con la misma clave y confirma que el modelo objetivo aparece en la lista.
  • Envía una solicitud mínima sin streaming y comprueba el 200 y el contenido.
  • Envía una solicitud en streaming y confirma que llegan los fragmentos y el usage final.
  • Revisa finish_reason: stop indica un final normal y length, que se alcanzó el límite de salida.
  • Compara calidad, latencia y consumo de tokens antes y después de la migración con un conjunto fijo de evaluación.
  • Verifica el retroceso ante 429, los tiempos de espera y el límite de reintentos para que el reintento automático del SDK no multiplique la concurrencia.
  • Registra hora de la solicitud, nombre del modelo, código de estado y consumo para facilitar el diagnóstico y la conciliación.

8. Tabla de errores comunes

  • 401 invalid_authentication_error: la clave no es válida, fue eliminada o se mezclaron claves del sitio chino y del internacional. Las claves de la plataforma abierta tampoco son intercambiables con las de Kimi Code.
  • 403 permission_denied_error: la lista de IP no incluye la IP de salida actual o faltan permisos en el proyecto.
  • 404 model_not_found: el base_url no apunta a Moonshot, el nombre del modelo está mal, se llama a un modelo retirado o falta el /v1 en la ruta.
  • 400 invalid_request_error: la entrada más el límite de salida superan el contexto, o se envió un parámetro no admitido, como una temperatura personalizada.
  • 400 content_filter: la entrada o la salida activaron la política de seguridad de contenido; hay que ajustar el prompt o el material.
  • 429: engine_overloaded_error indica saturación del servidor; rate_limit_reached_error, límites de la organización; exceeded_current_quota_error suele deberse a saldo insuficiente.
  • 504 o tiempo de espera agotado: una solicitud larga sin streaming esperó demasiado; para textos largos y agentes conviene usar streaming.

El SDK de OpenAI reintenta dos veces las solicitudes fallidas, así que una llamada puede generar tres. Si tu cuenta tiene cuota baja y recibes 429, reduce primero los reintentos y la concurrencia, y después investiga la cuota.

Preguntas frecuentes

¿Todavía puedo usar moonshot-v1?

No. Toda la serie moonshot-v1 dejó de funcionar el 31 de agosto de 2026 y las llamadas devuelven model_not_found. Migra a kimi-k3 o a kimi-k2.6.

¿Hasta qué nivel se completa la Base URL?

En el SDK de OpenAI, usa https://api.moonshot.cn/v1, sin /chat/completions; con curl escribe la ruta completa /v1/chat/completions; en el SDK de Anthropic, usa https://api.moonshot.cn/anthropic.

¿Por qué da error enviar temperature?

La temperatura de los modelos actuales es fija: 1.0 en K3 y K2.7 Code, y un valor fijo según el modo en K2.6. No envíes valores personalizados; top_p también está fijado en 0.95.

¿Una clave del sitio chino puede llamar al sitio internacional?

No. Las cuentas, el saldo y las claves de ambos sitios están aislados por región, y mezclarlos suele devolver 401. Al cambiar de sitio hay que modificar la clave, la Base URL y el nombre del modelo.

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

Hay que configurar explícitamente stream_options={"include_usage": True}. Aun así, una conexión interrumpida puede impedir que llegue el último bloque; en producción, cuenta el consumo también en el servidor.

Próximos pasos

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

Lecturas relacionadas: