Una Kimi API Key es la credencial que permite llamar a la plataforma abierta. No equivale a una membresía de la versión web ni a un saldo de recarga. Muchos equipos se atascan en la primera integración no porque no sepan usar el modelo, sino porque eligieron el sitio equivocado, guardaron mal la clave o trataron una cuenta de membresía como si fuera una cuenta de API.

Este artículo sigue el orden real de operación: primero aclara los sistemas de cuenta, luego recorre el registro, la verificación y la creación de la clave, después presenta métodos de almacenamiento, rotación y diagnóstico de errores 401, y al final compara cuándo conviene una clave oficial y cuándo una clave de gateway. Los modelos y los 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 entrada de la plataforma, los requisitos de verificación y las reglas de gestión de claves pueden cambiar; consulta siempre la página vigente de la consola oficial.

1. Distingue primero tres tipos de «cuenta Kimi»

Tipo Entrada Uso Saldo y clave
Membresía web y app de Kimi kimi.com Producto de chat Independiente de la API
Plataforma abierta de Kimi (sitio chino) platform.kimi.com Llamadas API en China Cuenta, saldo y clave propios
Plataforma abierta de Kimi (sitio internacional) platform.kimi.ai Llamadas API desde el exterior Totalmente independiente del sitio chino

Las claves del sitio chino y del sitio internacional no se pueden mezclar. Si configuras una clave del sitio chino contra la dirección internacional, o al revés, el resultado habitual es un 401. Existe una tercera vía: crear una clave de gateway en ZSQH AI Gateway y usarla para llamar a varios modelos, incluido Kimi; la clave la administra el gateway y el saldo también vive en la cuenta del gateway.

Primero define por qué sitio circulará tu operación y después registra la cuenta. No busques claves con una cuenta de membresía mientras recargas en la plataforma abierta: son dos productos distintos.

2. Registro y verificación de identidad

  1. Abre platform.kimi.com y completa el registro y el inicio de sesión según las indicaciones de la página.
  2. Entra al centro de usuario y completa la verificación de identidad personal; si la llamada es empresarial, completa la verificación de empresa.
  3. La verificación empresarial suele requerir el nombre de la empresa, una cuenta bancaria a nombre del mismo titular y el código unificado de crédito social.
  4. La plataforma deposita un importe aleatorio en la cuenta corporativa de la empresa; confírmalo con finanzas y vuelve a introducirlo. Si el importe coincide, la verificación se aprueba.
  5. Recarga solo después de aprobar la verificación. Los usuarios individuales pueden pagar en línea; las empresas también pueden usar transferencia corporativa.
  6. Vuelve a la consola y confirma el estado de la cuenta, el saldo y los modelos disponibles.

El titular de la verificación solo puede pasar de persona a empresa; no se admite el cambio inverso. Conviene decidir desde el registro qué titular se usará. La facturación, los contratos y las compras también suelen quedar vinculados a ese titular, y cambiarlo después resulta engorroso.

3. Pasos para crear una API Key

  1. Inicia sesión y entra a https://platform.kimi.com/console/api-keys.
  2. Haz clic en crear API Key y nómbrala según el esquema «proyecto-entorno-uso», por ejemplo crm-prod-chat.
  3. Copia la clave generada. Si la página solo la muestra una vez, guárdala de inmediato en el gestor de secretos; no la dejes en el historial de chat.
  4. Envía una solicitud mínima desde el entorno de pruebas para confirmar que la clave, el sitio y el nombre del modelo son correctos.
  5. Registra la fecha de creación, el responsable, el proyecto asociado y la fecha prevista de rotación.
  6. Usa claves independientes para producción, pruebas y depuración personal; no compartas una sola clave entre varias personas.

El alcance de permisos de la clave y la posibilidad de segmentarla por proyecto o por miembro dependen de las opciones que ofrezca realmente la consola. No supongas que existe un permiso que la consola no muestra; si necesitas aislamiento, usa varias cuentas o varias claves con cuotas en la capa de aplicación.

4. Rotación, revocación y reducción de permisos

Conviene tratar la clave como una credencial con ciclo de vida, no como algo que se crea una vez y se usa para siempre.

  • Rotación periódica: cada 90 días en proyectos normales; en negocios críticos, con mayor frecuencia.
  • Rotación inmediata ante cambios de personal: al salir de la empresa, cambiar de puesto o terminar un contrato externo, revoca primero y emite después.
  • Revocación inmediata ante una filtración: no observes primero el consumo; desactiva y luego investiga.
  • Despliegue solapado: crea la clave nueva, despliega y valida, y solo después revoca la anterior para evitar cortes durante el cambio.
  • Mínimo privilegio: una clave debe servir a un solo proyecto o entorno, de modo que el impacto de un incidente quede acotado.
  • Trazabilidad: los registros deben guardar solo el prefijo y el nombre de la clave, nunca el valor completo.

La rotación no es un trámite. Muchos incidentes de «saldo consumido de repente» se originan en claves antiguas olvidadas en scripts, repositorios o historiales de chat.

5. Almacenamiento seguro: las variables de entorno son solo el inicio

Lo mínimo es no escribir la clave dentro del código. En desarrollo local usa .env y asegúrate de que Git lo ignore; en producción, usa el servicio de gestión de secretos de la plataforma o la inyección de variables de entorno.

# .env solo en local, no se envía al repositorio
MOONSHOT_API_KEY=tu_clave

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

Después hay tres medidas adicionales:

  1. La clave nunca debe aparecer en el frontend, en aplicaciones móviles ni en extensiones del navegador; todas las llamadas deben pasar por el servidor.
  2. Filtra la cabecera Authorization en registros, reportes de errores y APM para evitar que la clave se imprima completa.
  3. Usa un gestor de secretos independiente en CI/CD y no muestres la clave en texto plano dentro de los scripts de compilación.

Si varias personas comparten una misma máquina de desarrollo, las variables de entorno no bastan para aislarlas. Es más seguro que cada persona tenga su propia clave de desarrollo y que el consumo se registre por usuario, de modo que un incidente pueda atribuirse a alguien concreto.

6. Orden de diagnóstico de errores 401

Un 401 no siempre significa que la clave sea incorrecta. Revisa en este orden; normalmente la causa se localiza en pocos minutos.

Síntoma Causa habitual Acción
invalid_authentication_error Clave con formato incorrecto, eliminada o copiada de forma incompleta Crear de nuevo y copiar completa
incorrect_api_key_error Falta la clave o la cabecera está mal escrita Revisar Authorization: Bearer
401 recién cambiado el entorno Clave del sitio chino usada en el internacional, o viceversa Unificar sitio y Base URL
403 permission_denied_error Lista blanca de IP o interfaz no habilitada Revisar permisos y salida de red
404 Base URL o nombre de modelo incorrecto Consultar la lista de modelos y la ruta

Revisión punto por punto:

  1. A qué sitio pertenece la clave y si la Base URL corresponde.
  2. Si la clave tiene espacios, saltos de línea o comillas antes o después.
  3. Si la variable de entorno se carga realmente; puedes imprimir solo los primeros caracteres para confirmarlo.
  4. Si la clave fue eliminada, deshabilitada o rotada.
  5. Si la cabecera es Authorization: Bearer <key>.
  6. Si la ruta es /v1/chat/completions y no falta ni sobra /v1.
  7. Probar con una clave nueva para separar un problema de clave de uno de configuración del gateway.

7. Clave oficial o clave de gateway: cómo elegir

Criterio Conexión directa oficial ZSQH AI Gateway
Entrada de creación Consola de la plataforma Kimi Consola del gateway
Sistema de cuenta Sitio chino o internacional Cuenta del gateway
Facturación Recarga en la plataforma, factura según sus reglas Recarga en RMB, factura según las reglas del gateway
Alcance de modelos Serie Kimi Entrada unificada para varios modelos
Escenario adecuado Solo Kimi y necesidad de conexión directa oficial Varios modelos, factura y clave unificadas

Si solo usas Kimi, el equipo está en China y el acceso oficial funciona bien, la conexión directa es la opción más simple. Si necesitas usar también DeepSeek, GLM o Claude, o prefieres una sola clave para varios modelos y una factura única en RMB, el gateway encaja mejor. Las dos vías no son excluyentes: puedes empezar con el gateway para pruebas y luego decidir la ruta de producción.

8. Lista de implementación para el equipo

  • Define el titular de uso de la API y completa la verificación correspondiente.
  • Una cuenta por sitio; no mezcles el sitio chino con el internacional.
  • Una clave por proyecto y una por entorno.
  • La clave solo entra al gestor de secretos, nunca al repositorio.
  • Establece un ciclo de rotación y un responsable.
  • Activa alertas de saldo para evitar que la falta de fondos provoque rechazos o respuestas 429.
  • Distingue 401, 403 y 429 en el monitoreo; no los trates todos como «clave inválida».

Preguntas frecuentes

¿Qué hago si se filtra la clave?

Revoca o elimina la clave en la consola de inmediato, crea una nueva, despliégala y luego revisa el consumo y la facturación. No basta con cambiar la cadena en el código: la clave antigua sigue siendo válida mientras no se revoque.

¿Puedo usar una clave en varios proyectos?

Técnicamente suele ser posible, pero no es recomendable. Compartir una clave entre proyectos impide atribuir consumo, límites y fallas. Separar claves por proyecto y añadir cuotas en la capa de aplicación reduce el costo de diagnóstico.

¿Una Kimi API Key caduca?

Si se establece una fecha de expiración depende de las reglas vigentes de la consola. Aunque la plataforma no obligue a caducar las claves, conviene rotarlas de forma proactiva, sobre todo tras cambios de personal o en claves sin uso prolongado.

Recargué y sigo recibiendo 401, ¿qué hago?

Confirma primero que la recarga y la clave pertenecen al mismo sitio y al mismo titular. Después prueba con una clave nueva para descartar que la anterior se haya eliminado, que la variable de entorno no se haya actualizado o que el código conserve un valor antiguo.

¿Se pueden mezclar la clave oficial y la clave de gateway?

No. La Base URL, el sistema de autenticación y la cuenta de saldo son distintos. El síntoma típico de mezclarlas es un 401 o un 404; al cambiar de ruta hay que actualizar la clave, la Base URL y el nombre del modelo a la vez.

Siguiente paso

Crea primero una clave de prueba en ZSQH AI Gateway, valida la conexión con una solicitud mínima y 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: