Muchos desarrolladores buscan «Moonshot API Key», abren platform.moonshot.cn y descubren que el navegador los envía a otro dominio. No es un error: la marca de la plataforma cambió. Moonshot es la empresa y la marca de la plataforma; Kimi es la marca de los modelos, y los dominios de las solicitudes API conservan moonshot. Este artículo explica, con el funcionamiento real de 2026, la jerarquía de cuentas, los permisos de las claves, el almacenamiento seguro, la rotación y la investigación de errores 401.

Nota: Moonshot y Kimi son marcas de sus respectivos titulares. Este artículo solo describe la integración técnica. Las direcciones de entrada, los requisitos de verificación y las reglas de gestión de claves pueden cambiar; toma como referencia la página actual de la consola.

1. Desde dónde se entra hoy a la plataforma Moonshot

platform.moonshot.cn redirige actualmente 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, en cambio, no cambió: en el sitio chino sigue siendo api.moonshot.cn y en el internacional, api.moonshot.ai. Algunos tutoriales antiguos solo actualizaron las capturas de la consola sin explicar esta diferencia, y por eso parece que la plataforma hubiera desaparecido.

Conviene recordar tres capas: Moonshot es la marca de la plataforma, Kimi es la marca de los modelos y api.moonshot.* es el dominio de la interfaz. No son tres sistemas de cuentas. Las cuentas, el saldo y las claves del sitio chino y del internacional están aislados entre sí, y cada clave debe usarse con su sitio correspondiente.

2. Elige primero la entidad: sin verificar, personal o empresa

Estado de verificación Proyectos máximos Claves API máximas Escenario típico
Sin verificar 1 10 Pruebas de corta duración
Verificación personal 20 50 Desarrollo individual, equipos pequeños
Verificación empresarial 50 100 Varios proyectos y miembros

Las cifras provienen de la documentación actual y la consola puede ajustarlas. Con la verificación empresarial se pueden invitar miembros, asignar permisos por proyecto y solicitar facturas; la verificación personal no permite invitar miembros. Las reglas para cambiar de entidad dependen de la consola: define antes de registrarte si usarás una entidad personal o empresarial, porque un cambio posterior suele implicar contratos y facturas.

La capa de organización también ofrece una lista de IP permitidas, disponible para organizaciones con verificación personal o empresarial. Se aplica a toda la organización y restringe a la vez todas sus claves: admite como máximo 20 direcciones IPv4 públicas o rangos CIDR, y no acepta IPv6 ni direcciones privadas. Cada guardado reemplaza la lista completa, así que no la actives sin pensarlo si tu IP de salida no es fija.

3. El orden correcto para crear una clave

  1. Inicia sesión en platform.kimi.com y entra a la consola.
  2. Crea primero el proyecto y nómbralo por línea de negocio o entorno, por ejemplo crm-prod o crm-test.
  3. Abre la página de claves API, crea una clave y usa un nombre que incluya proyecto, entorno y propósito.
  4. Copia la clave; si la página solo la muestra una vez, guárdala de inmediato en tu gestor de secretos.
  5. Valida la clave y el sitio con GET /v1/models o con una solicitud mínima.
  6. Registra el responsable, el proyecto, la fecha de creación y la fecha prevista de rotación.

Las claves pertenecen a un proyecto y el consumo también se contabiliza allí; todos los proyectos comparten el saldo y los límites de tasa de la organización. El administrador de cada proyecto puede fijar presupuestos mensuales o diarios, límites de TPM y alertas por SMS. El corte por presupuesto tarda unos diez minutos, así que no lo trates como una compuerta en tiempo real.

Cada miembro debería crear su propia clave. Cuando alguien sale de un proyecto, las claves que creó dejan de funcionar; eso facilita atribuir responsabilidades mucho más que compartir una clave entre varias personas.

4. Dónde están los límites de permisos de la clave

Una clave API no es la contraseña de la cuenta ni tiene «permisos universales». Puede llamar a las interfaces y los modelos que la organización asignó al proyecto y, al mismo tiempo, queda sujeta al presupuesto del proyecto, a los límites de la organización y a la lista de IP. Si la consola no ofrece claves separadas por modelo o por interfaz, no supongas que existen: cuando necesites aislamiento, usa proyectos distintos, claves distintas y cuotas en la capa de aplicación.

También conviene distinguir los productos: las claves de Kimi Code y las de la plataforma abierta no son intercambiables. Usar una clave de Kimi Code para llamar a la interfaz de la plataforma suele terminar en 401 o 404. Los roles de los miembros y los permisos de recarga o facturación también están separados; asigna el mínimo necesario y no confundas «puede crear claves» con «puede gestionar la facturación».

5. Variables de entorno y almacenamiento en el código

# .env solo en local, nunca en el repositorio
MOONSHOT_API_KEY=tu_clave

# .gitignore debe incluir al menos
.env
.env.*

En producción, usa la gestión de secretos de la plataforma o inyecta variables de entorno. Las claves no deben aparecer en el front-end, en aplicaciones móviles ni en extensiones de navegador: todas las solicitudes deben pasar por el servidor. Filtra el encabezado Authorization en los registros, en el reporte de excepciones y en APM; registra solo el nombre o el prefijo de la clave. En CI/CD, usa secretos independientes y no los muestres en los registros de compilación. Si varias personas comparten una máquina de desarrollo, una clave de desarrollo por persona facilita localizar problemas.

6. Cómo investigar 401, 403 y 429

Ante un 401, revisa primero tres cosas: a qué sitio pertenece la clave, si la Base URL corresponde y si la clave fue eliminada o rotada. Después comprueba que la copia esté completa, que el encabezado sea Authorization: Bearer y que la variable de entorno se haya cargado de verdad. Repetir la prueba con una clave nueva permite distinguir rápidamente entre un problema de clave y uno de configuración.

El 403 suele aparecer cuando la lista de IP no incluye la IP de salida actual o cuando faltan permisos en el proyecto. Las IP de salida de NAT, proxies y funciones en la nube pueden ser distintas de las que imaginas.

En el 429 hay que separar los tipos de error: engine_overloaded_error indica que el servidor está saturado, así que conviene esperar el Retry-After y reducir la concurrencia; rate_limit_reached_error significa que se superó el RPM, TPM, TPD o la concurrencia de la organización; exceeded_current_quota_error suele deberse a saldo insuficiente o a una deuda. El SDK de OpenAI reintenta dos veces por defecto, de modo que un fallo puede convertirse en tres solicitudes; tenlo en cuenta si tu cuenta tiene cuota baja.

7. Rotación, revocación y gestión de filtraciones

  • En proyectos habituales, rota cada 90 días; en los procesos críticos, puedes usar un plazo más corto.
  • Ante un cambio de personal, revoca primero y emite después; no basta con cambiar una cadena en el código.
  • Si hay filtración, revoca de inmediato y luego revisa el consumo y la facturación; no esperes a observar.
  • Publica en forma solapada: despliega y valida la clave nueva antes de revocar la anterior.
  • Limpia periódicamente las claves que llevan mucho tiempo sin usarse para no alcanzar el límite.
  • En los registros, conserva solo el nombre de la clave, nunca su valor completo.

8. Clave de la plataforma o clave de gateway

Las claves de la plataforma tienen su cuenta en la plataforma de API de Kimi; la facturación, las facturas y el catálogo de modelos siguen las reglas de la plataforma. Son adecuadas para equipos que solo usan Kimi y necesitan conectarse directamente a la interfaz.

Las claves de gateway se crean en ZSQH AI Gateway: una sola clave permite llamar a varios modelos y la facturación se unifica en yuanes. Resultan prácticas para equipos que alternan modelos o quieren administrar todas las claves en un solo lugar. Los modelos disponibles y la forma de facturación se rigen por los precios de modelos.

Las dos rutas no se excluyen: puedes probar primero con el gateway y después decidir qué usar en producción. No mezcles ambos tipos de clave, porque la Base URL, el sistema de autenticación y la cuenta de saldo son distintos.

Preguntas frecuentes

¿Una clave API de Moonshot y una clave de Kimi API son lo mismo?

Son credenciales de la misma plataforma, solo cambia el nombre. La plataforma ahora se llama plataforma de API de Kimi, pero el dominio de la interfaz sigue siendo moonshot.

¿Por qué redirige platform.moonshot.cn?

Tras el cambio de marca de la plataforma, el sitio chino redirige a platform.kimi.com y el internacional, a platform.kimi.ai. Los dominios de API api.moonshot.cn y api.moonshot.ai no se ven afectados.

¿Puedo ver el valor completo de una clave después de crearla?

La mayoría de las plataformas solo lo muestra al crearla; después solo se ve el nombre o el prefijo. Si no la guardaste, crea una nueva y no intentes recuperar el valor anterior.

¿Puedo usar una clave en varios proyectos?

Técnicamente suele ser posible, pero no es recomendable. Vincular la clave a un proyecto facilita la facturación y la atribución de los límites; compartirla entre proyectos descontrola el presupuesto y el diagnóstico.

¿Qué hago si las llamadas fallan después de activar la lista de IP?

Confirma primero que la IP de salida actual esté en la lista y luego revisa la salida real de NAT, del proxy o de la función en la nube. Al modificar la lista se reemplaza completa, así que escribe todas las direcciones antes de guardar.

Próximos pasos

Crea primero una clave de prueba en ZSQH AI Gateway y ejecuta una solicitud mínima; después separa las claves de producción por proyecto. Los modelos disponibles y la facturación se rigen por los precios de modelos.

Lecturas relacionadas: