La API de Moonshot es la interfaz de la plataforma abierta de Moonshot AI. En 2026 la plataforma cambió bastante: la consola para desarrolladores se trasladó a platform.kimi.com, la línea principal de modelos pasó a Kimi K3 y a la serie K2.7, y la antigua serie moonshot-v1 dejó de funcionar el 31 de agosto de 2026. Muchos equipos describen el problema como «no se puede acceder desde China», cuando en realidad lo que falla es la dirección de entrada, el nombre del modelo o la región de la cuenta, no la red.

Este artículo compara tres rutas —conexión directa, proxy propio y gateway de IA nacional— y añade métodos de validación para red, pagos y facturas, límites de tasa y conmutación por error. Los modelos y los precios se rigen por los precios de modelos.

Nota: Moonshot, Kimi y Moonshot AI son marcas o marcas registradas de Beijing Moonshot Technology Co., Ltd. Este artículo solo ofrece una discusión técnica y no implica relación de dependencia con los titulares; las interfaces, los modelos y las reglas de facturación se rigen por la documentación oficial.

1. Confirma a qué plataforma estás accediendo

La API de Moonshot tiene hoy tres capas que se confunden con facilidad, y equivocarse en cualquiera de ellas produce errores:

  • Capa de marca: Moonshot AI es el nombre de la empresa y Kimi es el nombre de los modelos y productos; no son dos servicios independientes.
  • Capa de plataforma: el sitio chino es platform.kimi.com y el internacional, platform.kimi.ai. Las cuentas, el saldo y las claves de ambos sitios son completamente independientes; mezclarlos devuelve 401.
  • Capa de interfaz: el sitio chino suele usar https://api.moonshot.cn/v1; el internacional emplea otro dominio, según la documentación oficial.

Además, las credenciales de la plataforma abierta, la membresía del cliente Kimi y productos como Kimi Code no son intercambiables. Si usas la clave de un producto de cliente para llamar a la plataforma abierta, también fallará la autenticación. Antes de optimizar la red, confirma en qué plataforma te registraste y a qué línea de producto pertenece la clave.

2. Tres rutas en una sola tabla

Dimensión Conexión directa oficial Proxy propio Gateway de IA nacional
Entrada Direcciones oficiales como api.moonshot.cn Proxy inverso con dominio propio Dirección compatible con OpenAI del gateway
Cuenta y facturación Cuenta oficial, recarga en yuanes Factura oficial más costo del servidor Cuenta del gateway, factura unificada en yuanes
Catálogo de modelos Solo Moonshot/Kimi Depende de la configuración del proxy Varios proveedores, según disponibilidad
Responsabilidad operativa Plataforma oficial y red local Toda a cargo del equipo Compartida entre proveedor y equipo local
Equipos adecuados Un solo modelo, acceso estable, capacidad para gestionar límites Con capacidad de operación y necesidad de salida y auditoría unificadas Varios modelos, facturas y menos operación

Ninguna ruta sirve para todos. El orden de decisión sugerido es: si el negocio tolera interrupciones, si necesita varios modelos y factura unificada, y si el equipo tiene a alguien que mantenga reintentos y monitoreo. Si los tres puntos son simples, la conexión directa basta; si cualquiera se complica, considera añadir una capa.

3. Red: las cuatro cosas que de verdad hay que revisar

El acceso a la API de Moonshot desde China normalmente no requiere herramientas de red adicionales, pero estos cuatro problemas suelen diagnosticarse mal como «la red no funciona»:

  1. Región y clave que no coinciden: una clave del sitio chino con la dirección internacional, o al revés, devuelve 401 directamente. No es un problema de DNS.
  2. Proxy corporativo e interceptación TLS: los proxies empresariales que reescriben certificados o resuelven mal el DNS producen errores de certificado, timeouts o 499.
  3. Timeouts en solicitudes largas: si una solicitud sin streaming pasa mucho tiempo sin respuesta, el gateway puede devolver 504; la documentación oficial menciona escenarios de 900 segundos. Para generar textos largos conviene activar streaming por defecto.
  4. Lista de IP del sitio internacional: el sitio internacional puede restringir las IP de llamada y devolver 403 si la IP no está en la lista de la organización. Cambiar de red no sirve; hay que configurarlo en la consola.

En producción también conviene activar la reutilización de conexiones para evitar un handshake en cada solicitud; en streaming, configura un tiempo de espera por inactividad y un heartbeat para que un proxy intermedio no corte una conexión que pasa mucho tiempo sin datos.

4. Pagos y facturas: donde suelen atascarse las empresas

Que la parte técnica funcione no significa que el servicio pueda salir a producción; las compras y las finanzas suelen ser el cuello de botella. Según la información oficial de 2026, la verificación empresarial exige el nombre de la empresa, una cuenta bancaria corporativa a nombre de esa misma empresa y el código unificado de crédito social; la plataforma deposita un importe aleatorio para verificar la titularidad de la cuenta. Una cuenta personal puede ascenderse a empresarial, pero una cuenta empresarial no puede cambiar de tipo en sentido inverso.

En la recarga, las personas pueden usar WeChat o Alipay; las empresas pueden recargar en línea o por transferencia corporativa. La transferencia debe salir de la cuenta de la entidad ya verificada; la acreditación suele tardar de 1 a 5 días hábiles y, una vez recibida, unos 10 minutos más en registrarse. La factura se solicita en línea, por importe consumido o por importe recargado, y la entidad emisora es Beijing Moonshot Technology Co., Ltd.; el concepto es servicios técnicos. En cuentas empresariales, el título de la factura solo puede ser la entidad verificada; solo las cuentas personales pueden elegir entre persona o empresa.

Si la empresa exige contrato, plazo de pago o factura especial, conviene confirmarlo primero por el canal comercial y no descubrir después de recargar que el proceso no encaja. Cada gateway tiene reglas de pago y facturación distintas; antes de firmar, confírmalas también por escrito.

5. Límites de tasa: un 429 no es un solo error

Los límites de velocidad de Moonshot se asignan por niveles según la recarga acumulada de la cuenta: cuanto mayor es el nivel, más amplios son la concurrencia, el RPM, el TPM y el TPD. Los cupones normalmente no cuentan para la recarga acumulada, así que «recargar con cupones» no necesariamente sube el nivel. El QPS de la búsqueda web es una cuota independiente y se calcula aparte del RPM y el TPM de la interfaz de conversación.

Un mismo 429 se trata de formas completamente distintas:

  • engine_overloaded_error: sobrecarga del servidor; aplica retroceso según Retry-After. Recargar o subir de nivel no sirve.
  • rate_limit_reached_error: se superó la concurrencia, el RPM, el TPM o el TPD de la organización; reduce la velocidad, haz cola o espera el reinicio.
  • exceeded_current_quota_error: deuda o cuota insuficiente; no reintentes, resuelve primero el saldo.

Además, la plataforma puede aplicar límites de control de riesgo a cuentas anómalas, y la documentación oficial advierte que ese tipo de restricción puede no ser reversible. Los proyectos también pueden fijar un presupuesto diario: al alcanzarlo se rechazan todas sus solicitudes, con un posible retraso de unos 10 minutos por la facturación. También conviene activar las alertas de saldo por SMS para no descubrir una deuda solo cuando aparece el 429.

6. Conmutación por error: solo para errores transitorios

La conmutación por error no significa «cambiar de ruta ante cualquier error». El saldo insuficiente, una clave incorrecta, un parámetro inválido y un error de seguridad de contenido no se resuelven cambiando de canal; además, amplifican la factura y complican el diagnóstico. Este es un ejemplo mínimo de estructura:

import os
from openai import OpenAI

clients = [
    OpenAI(api_key=os.environ["PRIMARY_KEY"],
           base_url=os.environ["PRIMARY_BASE"], max_retries=0),
    OpenAI(api_key=os.environ["BACKUP_KEY"],
           base_url=os.environ["BACKUP_BASE"], max_retries=0),
]

def ask(prompt: str) -> str:
    last_error = None
    for client in clients:
        try:
            resp = client.chat.completions.create(
                model=os.environ["MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=512,
                stream=False,
            )
            return resp.choices[0].message.content
        except Exception as exc:  # en producción, clasifica por error.type
            last_error = exc
            if "quota" in str(exc).lower() or "content_filter" in str(exc).lower():
                raise
    raise RuntimeError("Ningún canal principal ni de respaldo está disponible") from last_error

Atención: las cuentas del sitio chino y del internacional son independientes, así que una supuesta «recuperación ante desastres entre regiones» no consiste solo en cambiar la Base URL; el canal de respaldo debe registrarse, recargarse y validarse por separado de antemano. Después de una conmutación, registra request_id, nombre del modelo, usage y latencia; de lo contrario, no podrás saber si el canal de respaldo está funcionando de verdad.

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

  1. Envía una solicitud mínima con un modelo vigente, como kimi-k3 o kimi-k2.6, y confirma que devuelve 200.
  2. Valida por separado los formatos Chat Completions, Responses y Anthropic Messages, y comprueba que funcionan todos los protocolos que usa el proyecto.
  3. Revisa que model, usage y request_id existan en la respuesta y puedan registrarse.
  4. Prueba el streaming con una salida larga y confirma que llega bloque por bloque, que el final está completo y que el proxy intermedio no acumula datos.
  5. Provoca a propósito 401, 404 y 429 para comprobar que el cliente distingue bien los tipos de error.
  6. Configura timeouts de conexión y de lectura, activa Keep-Alive y define el presupuesto diario del proyecto y las alertas de saldo.
  7. Observa durante una semana la latencia p50 y p95 y la proporción de 429 y 5xx, en lugar de mirar una sola prueba de carga.
  8. Recorre el proceso de transferencia corporativa y facturación, y confirma el contrato, la factura y las reglas de reembolso.
  9. Mantén una ruta directa con posibilidad de reversión y deja escritas las condiciones para cambiar de canal.

Si la validación no pasa, no muevas a ella los procesos críticos. Un gateway añade un salto y puede aumentar ligeramente la latencia; su valor está en la entrada unificada, la conmutación por error, la facturación y el aislamiento de claves, no en «acelerar».

Preguntas frecuentes

¿La API de Moonshot y la versión web de Kimi son lo mismo?

No. La versión web es un producto para usuarios y la API de Moonshot es la interfaz de la plataforma abierta para desarrolladores; el sistema de cuentas, la facturación y las claves son distintos.

¿Hace falta alguna herramienta de red adicional para conectarse desde China?

Normalmente no. Moonshot es un proveedor chino y la interfaz del sitio chino se puede acceder directamente desde el país. Lo habitual son errores de región, clave, nombre de modelo o configuración del proxy.

¿El código antiguo de moonshot-v1 sigue funcionando?

La serie moonshot-v1 dejó de funcionar el 31 de agosto de 2026 y las llamadas devuelven 404. Hay que migrar a kimi-k3, kimi-k2.7 o kimi-k2.6 según la lista oficial de modelos y revisar de nuevo los parámetros.

¿El pago empresarial debe hacerse por transferencia corporativa?

No es la única vía. Tras la verificación empresarial se puede elegir entre recarga en línea con WeChat o Alipay y transferencia corporativa; la transferencia tarda más y encaja con equipos que tienen un proceso financiero formal.

¿Qué hago si el 429 no se recupera?

Revisa primero error.type. Si es cuota insuficiente, recarga; si se superó la concurrencia o el TPD, reduce la velocidad y espera el reinicio; si es sobrecarga del servidor, aplica retroceso según Retry-After. Si no se recupera, conserva el request_id y contacta al soporte de la plataforma.

Próximos pasos

Si usas varios modelos, necesitas una factura unificada o quieres un canal de respaldo, crea primero una clave de prueba en ZSQH AI Gateway y compara con el mismo lote de solicitudes la latencia, la tasa de error y la facturación de la conexión directa y del gateway antes de decidir la ruta de producción. Los modelos y el criterio de facturación se rigen por los precios de modelos.

Lecturas relacionadas: