La API de Moonshot es la interfaz de la familia de modelos Kimi, conocida por su contexto largo, su comprensión del chino y su buena relación entre precio y rendimiento. Se usa habitualmente para lectura de documentos largos, bases de conocimiento, atención al cliente y generación de contenido.
Esta guía cubre cómo obtener acceso, llamar a la API y evitar los problemas de integración que aparecen cuando las solicitudes de contexto largo se encuentran con el tráfico de producción.
Nota: Moonshot y Kimi son marcas registradas de sus propietarios. Este artículo refleja las versiones comunes a octubre de 2026; los nombres de modelo y los precios siguen la página de precios de modelos.
1. Para qué sirve la API de Moonshot
- Resúmenes de documentos largos y lectura de contratos o informes.
- Preguntas y respuestas y atención al cliente en chino.
- Bases de conocimiento y RAG.
- Creación y reescritura de contenido.
- Explicación de código.
Los modelos de contexto largo son el principal atractivo, pero no siempre son la opción correcta. Una respuesta breve de soporte no necesita una ventana de contexto muy grande, y usarla de todos modos aumenta la latencia y el costo sin mejorar la respuesta.
2. Cómo obtener una clave
Moonshot oficial
Regístrate en la plataforma abierta de Moonshot, crea una clave y recarga tu cuenta.
ZSQH AI Gateway
- Regístrate en ZSQH AI Gateway.
- Crea una clave y fija una cuota.
- Recarga la cuenta.
- Llama a la API con el SDK de OpenAI.
Un gateway resulta útil cuando la misma aplicación también usa otras familias de modelos. Una clave y una Base URL pueden cubrir varios proveedores, lo que simplifica la facturación y la rotación de claves. Fija una cuota por clave desde el principio; es mucho más fácil subir un límite que explicar una factura inesperada.
3. Base URL
El endpoint oficial de Moonshot suele ser:
https://api.moonshot.cn/v1
El endpoint del gateway es:
https://ai.zhongshangqihang.com/v1
Usa la Base URL que corresponda a la clave. Una clave emitida por una plataforma no se autenticará en la otra, y este desajuste es una de las causas más comunes de un error 401.
4. Llamada en Python
from openai import OpenAI
client = OpenAI(
api_key="sk-your-key",
base_url="https://ai.zhongshangqihang.com/v1",
)
resp = client.chat.completions.create(
model="moonshot-v1-8k",
messages=[{"role": "user", "content": "Summarize this text in three sentences: ..."}],
)
print(resp.choices[0].message.content)
Los nombres de modelo siguen la página de precios, y los modelos de contexto largo suelen costar más por token. Confirma el nombre exacto del modelo antes del despliegue; un nombre obsoleto puede devolver un 404 incluso cuando la clave y la Base URL son correctas. Guarda el endpoint y el nombre del modelo en la configuración del entorno para que cambiar entre una cuenta de prueba y una de producción no requiera modificar el código.
5. Cómo trabajar con texto largo
- Divide o resume primero; no llenes toda la ventana de contexto de una vez.
- Conserva citas a la fuente para que las respuestas se puedan comprobar.
- Las solicitudes de contexto largo son más lentas y caras, así que define tiempos de espera.
- Usa el modo JSON o la llamada a herramientas para salidas estructuradas cuando el modelo lo admita.
- Verifica el contenido importante con una segunda pasada.
Un patrón útil es un pipeline de dos etapas: primero resume cada sección y luego pide al modelo que responda usando los resúmenes más algunos pasajes originales relevantes. Esto mantiene el prompt más pequeño y facilita rastrear qué parte del documento sustentó la respuesta. Registra los conteos de tokens que devuelve la API en cada etapa; muestran si el paso de resumen realmente reduce el prompt final o solo añade otra llamada.
6. Errores comunes
| Error | Causa | Acción |
|---|---|---|
| 401 | Clave o endpoint desajustados | Comprueba la clave y la Base URL |
| 404 | Nombre de modelo o ruta incorrectos | Consulta la página de precios y confirma /v1 |
| 429 | Límite de tasa | Reduce la concurrencia y reintenta |
| Límite de contexto excedido | Entrada demasiado larga | Divide o resume |
| Saldo insuficiente | Sin crédito | Recarga |
7. Control de costos
- El contexto largo es el principal factor de costo, así que resume antes de preguntar.
- Usa un modelo de contexto corto para tareas simples.
- Procesa trabajos por lotes de forma asíncrona.
- Supervisa los reintentos y las solicitudes fallidas.
Mide la distribución de tokens de entrada del tráfico real. Unas pocas solicitudes muy grandes pueden dominar la factura mensual, y a menudo son las más fáciles de optimizar recortando texto repetitivo o almacenando en caché el resumen de un documento. Guarda en caché los resúmenes de documentos que se leen repetidamente y reutilízalos entre usuarios cuando la fuente y los permisos sean los mismos.
Preguntas frecuentes
¿La API de Moonshot es lo mismo que la aplicación web Kimi?
No. La aplicación web es un producto, mientras que la API es una interfaz para programas. La facturación y los límites son distintos.
¿Admite el SDK de OpenAI?
Normalmente admite Chat Completions compatible con OpenAI. Consulta la documentación oficial o del gateway para conocer los parámetros exactos.
¿El acceso es estable desde China continental?
Moonshot es una plataforma nacional, así que suele ser más estable que los modelos extranjeros. Los resultados aún dependen de tu red y tu región.
Próximos pasos
Si necesitas un punto de entrada unificado o cambio entre varios modelos, puedes registrarte en ZSQH AI Gateway y probar un flujo de documentos largos con un presupuesto pequeño. Los nombres de modelo y los precios aparecen en la página de precios de modelos.
Lecturas relacionadas:
