Un relay de la API de Moonshot consiste, en esencia, en una capa entre tu aplicación y la plataforma abierta del proveedor. Puede aportar un punto de entrada unificado, facturación en moneda local, cambio entre varios modelos y conmutación por error; también puede introducir modelos sustituidos, criterios de facturación poco claros, fugas de claves y un punto de falla adicional. En 2026 Moonshot cambió sus modelos principales a la serie Kimi K3 y K2.7 y retiró moonshot-v1. Si la capa de relay no actualizó su tabla de modelos, aparece un problema silencioso: la interfaz responde, pero el resultado no corresponde.

Este artículo no recomienda proveedores concretos; solo explica cómo evaluar, cómo conciliar la factura y cómo migrar. Los modelos y precios vigentes se consultan en la página de precios de modelos.

Nota: Moonshot, Kimi y Yuezhi Anmian son marcas o marcas registradas de Beijing Yuezhi Anmian Technology Co., Ltd. Este artículo solo tiene fines técnicos y no implica relación de subordinación con el titular. Las credenciales, condiciones y reglas de facturación de cada servicio de relay las proporciona su operador; verifícalas antes de firmar.

1. Distingue primero los cuatro tipos de relay

La palabra "relay" se usa para cosas distintas, y la responsabilidad cambia por completo:

  • Gateway administrado: el proveedor mantiene un punto de entrada unificado y ofrece subclaves, estadísticas de uso, enrutamiento de modelos y facturas. Compras servicio técnico más cuota.
  • Reventa o distribución: el proveedor revende cuota desde su propia cuenta upstream y puede cobrar por multiplicador o paquete. Quién es la cuenta upstream y qué nivel tiene afecta directamente la estabilidad.
  • Gateway autoalojado: despliegas software como one-api o new-api y conservas tus propias claves upstream. Da el mayor control, pero la operación, las actualizaciones y la recuperación ante desastres quedan de tu lado.
  • Marketplace de nube o plataforma agregadora: se contrata dentro de un proveedor de nube o una plataforma agregadora, la factura sigue a la plataforma y la variedad de modelos puede ser mayor, pero también hay que confirmar el upstream y las condiciones de datos.

Antes de hablar de precio, aclara si compras "servicio técnico" o "cuota de modelos". El responsable cambia cuando algo falla.

2. Claves y mapeo de modelos: el riesgo más ignorado

El relay ve la solicitud y la respuesta completas por su posición en la cadena; eso lo define la arquitectura, no es una cuestión de confianza. Si las solicitudes contienen datos personales, contratos o código interno, confirma primero si se almacenan en disco, cuánto tiempo se conservan y si se usan para entrenamiento. Si hace falta, anonimiza o usa una conexión directa.

Más silencioso que el tratamiento de datos es el mapeo de modelos. Riesgos habituales:

  • Un nombre de modelo antiguo se mapea en silencio a un modelo más barato o de menor contexto; la interfaz no falla, pero la calidad baja.
  • En horas de alta demanda, la solicitud se degrada a un canal de menor capacidad mientras el campo model de la respuesta no cambia.
  • Se mezclan claves del sitio para China y del sitio internacional; normalmente funciona, pero al activarse la validación regional aparece un 401.
  • Varios clientes comparten una misma cuenta upstream; si otro satura la concurrencia, tú recibes 429.
  • La cuenta upstream activa un límite por comportamiento anómalo, y ese tipo de restricción puede no ser reversible.

Por eso, el contrato debe incluir la tabla de mapeo de modelos, las reglas de degradación y el mecanismo de notificación. Como mínimo, exige que el relay conserve en la respuesta el model, el usage y el request_id reales, y que permita exportar los registros de solicitudes.

3. Transparencia de facturación: convierte el criterio en una tabla de conciliación

El K3 actual de Moonshot cobra por separado la entrada con acierto de caché, la entrada sin acierto, la escritura de caché y la salida; la escritura de caché además distingue distintos TTL. Si el relay solo informa un "total de tokens", no puedes saber si la caché funcionó ni verificar el multiplicador.

Partida Qué revisar Diferencia habitual
Escritura de caché Si se cobra aparte y qué TTL tiene Se cuenta como entrada normal
Entrada con acierto de caché Si la parte acertada usa precio con descuento Se cobra todo como fallo de caché
Entrada sin acierto Si coincide con el criterio del proveedor Se declaran tokens de entrada inflados
Tokens de salida Si incluyen el contenido de razonamiento Criterio de tokens de razonamiento poco claro
Solicitudes reintentadas Si se cobran dos veces Un timeout reintentado cuenta doble
Solicitudes fallidas Cómo se tratan 429, 5xx y desconexiones Se descuenta aunque fallen
Búsqueda y lotes Si tienen precio aparte Se mezclan en la factura de chat

Antes de firmar, aclara cuatro puntos: si la unidad de cobro es token, paquete o multiplicador; si hay consumo mínimo y aviso de cambio de precio; si los fallos y reintentos se cobran; y quién emite la factura y con qué concepto. Si el precio es muy inferior al del proveedor, pregunta si viene de compra por volumen, subsidio o cuota compartida; no mires solo el número.

4. Latencia y errores: qué indicadores monitorear

Una medición puntual no sirve; observa al menos una semana continua. Fija un conjunto de solicitudes y registra por separado:

  • TTFT: tiempo hasta el primer token; en streaming refleja mejor la experiencia que el tiempo total.
  • Latencia p50 / p95: mira la cola, no el promedio.
  • Tasa de error: sepárala por 401, 403, 404, 429, 499, 5xx y error.type.
  • Dimensión de modelo: el mismo request debe observarse por separado en cada modelo y canal.
  • Coherencia de uso: si el usage de la respuesta coincide con la factura.

El siguiente es un script mínimo de sondeo, solo para validar la cadena y registrar indicadores:

import os, time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RELAY_KEY"],
    base_url=os.environ["RELAY_BASE"],
    max_retries=0,
)

start = time.time()
try:
    resp = client.chat.completions.create(
        model=os.environ["MODEL"],
        messages=[{"role": "user", "content": "Responde solo OK"}],
        max_completion_tokens=16,
    )
    elapsed = time.time() - start
    print({
        "ok": True,
        "latency_ms": round(elapsed * 1000),
        "model": resp.model,
        "usage": resp.usage.model_dump() if resp.usage else None,
        "request_id": resp.id,
    })
except Exception as exc:
    print({"ok": False, "latency_ms": round((time.time() - start) * 1000),
           "error": type(exc).__name__, "detail": str(exc)[:200]})

En producción, guarda los resultados en una base de series temporales y agrega p50, p95, tasa de error y distribución de modelos por hora. Alertar solo por "fallo", sin distinguir el tipo de 429, no permite decidir en guardia si hay que bajar el ritmo, recargar o cambiar de canal.

5. Lista de migración: de la conexión directa al relay

  1. Inventaría los nombres de modelo actuales y confirma si todavía usas moonshot-v1, ya retirado; migra primero a kimi-k3, kimi-k2.7 o kimi-k2.6.
  2. Fija un conjunto de solicitudes de regresión que cubra preguntas cortas, documentos largos, streaming, llamadas a herramientas y entrada de imágenes.
  3. Envía el mismo conjunto por conexión directa y por relay, y compara model, usage, request_id y calidad de salida.
  4. Valida los formatos de API que realmente usa el proyecto: Chat Completions, Responses o Anthropic Messages; no pruebes solo uno.
  5. Comprueba si el streaming devuelve bloque por bloque, si el cierre llega completo y si el proxy intermedio desactivó el búfer.
  6. Provoca a propósito 401, 404 y 429; confirma que el tipo y el mensaje sean legibles y que el cliente los mapee bien.
  7. Concilia la factura real con el usage, incluyendo caché, reintentos y solicitudes fallidas.
  8. Despliega primero en tráfico de bajo riesgo, conserva un interruptor para volver a la conexión directa y observa al menos una semana antes de mover el tráfico principal.

Migrar no es solo cambiar la Base URL y la clave. Los nombres de modelo, los parámetros, los tipos de error, las estadísticas de uso y la ruta de facturación son los puntos que más fallan después del cambio.

6. Cómo validar un relay

La validación combina varias señales; un solo indicador no demuestra el origen:

  • Si el model de la respuesta coincide con la solicitud y no aparecen degradaciones no declaradas.
  • Si la estructura de usage está completa y los campos de caché siguen el criterio del proveedor.
  • Si el request_id es trazable y se puede cruzar con los registros del relay.
  • Si un conjunto de evaluación fijo mantiene calidad y latencia frente a la conexión directa.
  • Si soporta los tres formatos de API y transmite las extensiones de parámetros como indica el proveedor.
  • Si las respuestas de error conservan error.type, en lugar de envolver todo como "servicio no disponible".
  • Si la entidad de la factura, del contrato y del cobro coinciden.
  • Si hay página de estado, SLA, avisos de incidentes e historial de disponibilidad.

Si el relay no puede entregar esta información, no es adecuado para cargas críticas. El periodo de prueba debe cubrir al menos un ciclo de facturación completo para evitar que todo funcione a principio de mes y aparezcan límites a fin de mes.

7. Diseña la salida desde el principio

El mayor costo oculto de un relay es el bloqueo. Antes de firmar, confirma: si la clave se puede revocar en cualquier momento, si las subclaves se aíslan por proyecto, si los registros se pueden exportar, si el saldo no consumido es reembolsable, cuánto tiempo se conservan los datos y con cuánta antelación avisan los cambios de precio. Un costo de migración bajo te da margen de negociación.

El gateway autoalojado también tiene problema de salida: la versión del software, los complementos, la base de datos y las claves upstream están en tus manos, pero si nadie lo mantiene, las actualizaciones y los parches de seguridad se retrasan. Si eliges autoalojar, asume ese costo humano a largo plazo.

Preguntas frecuentes

¿Un relay siempre es más estable que la conexión directa?

No necesariamente. Un relay puede reintentar, hacer cola y conmutar por error, pero también añade un punto de falla. La estabilidad depende de la capacidad operativa del proveedor, la calidad de la cuenta upstream y tu configuración de timeouts; hay que validarla con tráfico real durante más de una semana.

¿Es normal que un relay cueste menos que el proveedor?

Puede venir de compra por volumen, subsidios o cuota compartida, o de un criterio de facturación maquillado. Pregunta primero por la unidad de cobro, las reglas de caché y si las solicitudes fallidas se cobran; después compara con la factura.

¿Un proxy autoalojado resuelve los errores 429?

No aumenta la cuota upstream por sí solo. Un proxy solo puede hacer cola, bajar el ritmo, reintentar y cambiar de canal; si la concurrencia o el TPD de la cuenta upstream llegaron al tope, habrá que esperar el reinicio o subir de nivel.

¿Cómo saber si un relay usa Moonshot real?

Revisa el model, el usage y el request_id de la respuesta, y compara con la conexión directa usando un conjunto de evaluación fijo. La validación combinada es más fiable que cualquier indicador aislado; si hay dudas sobre el origen, prioriza la conexión directa.

¿Cuánto código hay que cambiar para migrar a un relay?

En proyectos compatibles con OpenAI suele bastar cambiar la Base URL, la clave y el nombre del modelo. Pero el streaming, los timeouts, el mapeo de errores y las estadísticas de uso deben probarse de nuevo; ahí es donde más fallan los cambios.

Próximos pasos

Crea una clave de prueba en ZSQH AI Gateway, ejecuta el script de sondeo y la lista de migración de este artículo, y luego decide qué cargas van por conexión directa y cuáles por el gateway. Los modelos, criterios de facturación y disponibilidad se rigen por la página de precios de modelos.

Lecturas relacionadas: