La API de Moonshot es la interfaz de modelos de la plataforma abierta de Moonshot AI, es decir, la plataforma para desarrolladores que está detrás de Kimi. Se factura por consumo de tokens y no ofrece planes de suscripción. Al preparar un presupuesto, muchos equipos fallan en dos puntos: siguen llamando a modelos moonshot-v1 que ya fueron retirados, o mezclan entrada, escritura de caché, salida y reintentos en un único precio promedio. Este artículo desglosa la estructura de facturación según la documentación pública de octubre de 2026; los precios concretos se rigen por los precios de modelos del sitio y por la documentación oficial.

Nota: Moonshot y Kimi son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica relación de dependencia ni representación con los titulares. La lista de modelos, la longitud de contexto y las reglas de facturación pueden cambiar; verifica de nuevo las páginas oficiales antes de comprar.

1. Separa los modelos vigentes de los retirados

A octubre de 2026, la documentación de la plataforma abierta incluye como modelos principales kimi-k3, kimi-k2.6, kimi-k2.7-code y kimi-k2.7-code-highspeed. La antigua serie moonshot-v1 ya salió del catálogo: moonshot-v1-8k, -32k, -128k, -auto y sus versiones de vista previa con visión dejaron de funcionar el 31 de agosto de 2026, el mismo día que kimi-k2.5. Las versiones preliminares de kimi-k2 y kimi-latest también dejaron de dar servicio antes.

Modelo Contexto Estructura de facturación Estado y observaciones
kimi-k3 1,048,576 Entrada, acierto de caché, escritura de caché, salida Modelo principal actual; la documentación lo recomienda como destino de migración
kimi-k2.6 262,144 Entrada, acierto de caché, salida Uso general y multimodal; habitual en escenarios sensibles al costo
kimi-k2.7-code 262,144 Entrada, acierto de caché, salida Generación de código, preguntas sobre repositorios y agentes
kimi-k2.7-code-highspeed 262,144 Entrada, acierto de caché, salida Tareas de código con baja latencia
moonshot-v1-8k/32k/128k Según el nombre Facturación antigua por tramos de longitud Retirados el 2026-08-31

Los nombres de modelo de los tutoriales antiguos no se pueden copiar tal cual. El «8k» de moonshot-v1-8k era en sí un tramo de contexto: cuando la llamada falla, el problema no es la clave, sino que el modelo ya no existe. Al migrar, cambia primero el nombre del modelo y después revisa el contexto y los conceptos de facturación; no hagas solo un reemplazo de cadenas.

2. Unidad de facturación: una solicitud se divide en cuatro partes

La factura actual suele componerse de cuatro tipos de tokens: entrada sin acierto de caché, entrada con acierto de caché, escritura de caché y salida. En K3, la escritura de caché se cobra por separado según dos niveles de TTL, 5 minutos y 1 hora; la página de precios de la serie K2 no desglosa la escritura de caché. La fórmula de una solicitud es:

Costo de una solicitud =
  tokens de entrada sin acierto × precio sin acierto
+ tokens de entrada con acierto × precio con acierto
+ tokens de escritura de caché × precio del TTL correspondiente (solo K3)
+ tokens de salida × precio de salida

La documentación oficial ofrece una equivalencia útil: en texto chino estándar, aproximadamente 1.5 a 2 caracteres chinos corresponden a 1 token. Multiplicar directamente el número de caracteres por el precio subestima la entrada; para un cálculo formal conviene usar la interfaz de estimación POST /v1/tokenizers/estimate-token-count o leer el campo usage de la respuesta.

En Chat Completions, los campos de consumo son usage.prompt_tokens y usage.completion_tokens; el detalle de caché aparece en usage.prompt_tokens_details.cached_tokens y en cache_write_tokens. En Messages API, input_tokens no incluye la parte de caché: la entrada total es la suma de input_tokens, cache_read_input_tokens y cache_creation_input_tokens. En las llamadas en streaming hay que configurar stream_options.include_usage=true.

3. Cómo se factura la caché y por qué no acierta

La caché de contexto funciona por coincidencia de prefijo, no por coincidencia de toda la conversación. Si cambia cualquier punto del prefijo, el contenido posterior a ese punto deja de reutilizarse. Entre las acciones que rompen el prefijo están insertar una marca de tiempo o un identificador aleatorio en el system prompt, reordenar las definiciones de herramientas en cada llamada, concatenar fragmentos dinámicos de la base de conocimiento y cambiar de nivel de TTL. La caché también está aislada por organización: no se comparte entre organizaciones distintas.

En K3, la escritura de caché se cobra en la primera escritura; el TTL es fijo de 5 minutos o de 1 hora y no puede cambiarse a mitad de camino. Los aciertos renuevan el TTL sin cargo y no vuelven a cobrar escritura. Los dos niveles de caché no se comunican entre sí. Si la cola del prefijo no completa un bloque de caché entero, esa parte suele tratarse como fallo de acierto.

La caché no es un interruptor que «ahorra por activarse», sino un trabajo de ingeniería sobre el prefijo. Coloca al inicio el system prompt, las definiciones de herramientas, los ejemplos fijos y la parte común de la base de conocimiento; deja las variables al final y comprueba la tasa de acierto con cached_tokens.

4. Costo del contexto largo: lo caro es reenviarlo

K3 admite un contexto de 1,048,576 tokens y la serie K2, de 262,144 token. K3 usa una facturación uniforme por consumo y ya no divide por tramos de 8k, 32k o 128k como la antigua moonshot-v1, así que no se puede usar la tabla de precios por tramos del modelo anterior para extrapolar K3.

El contexto largo no es un problema en sí; el problema es reenviar el mismo material en cada turno. En un diálogo sobre un documento de 200,000 tokens, si haces diez preguntas y cada una incluye el texto completo, el costo de entrada se acumula rápidamente con el número de turnos. Los registros de herramientas, el cuerpo de las páginas web y los resultados de código también permanecen en el historial y siguen facturándose. Lo habitual es recuperar primero los fragmentos relevantes y luego pedir al modelo que los lea; usar resúmenes rotativos en conversaciones de varios turnos; convertir las partes estables en un prefijo de caché; y reservar el contexto largo solo para el texto original que de verdad debe conservarse.

El contexto largo también amplía la latencia y la tasa de fallos. Las solicitudes largas sin streaming son más propensas a agotar el tiempo de espera del gateway, y un reintento genera nuevo consumo de entrada. Para tareas largas conviene priorizar la salida en streaming y configurar un tiempo de lectura razonable.

5. Reintentos y solicitudes fallidas

Los códigos de error oficiales dividen el 429 en tres casos: rate_limit_reached_error indica que se alcanzó el límite de concurrencia, RPM, TPM o TPD de la organización; exceeded_current_quota_error señala saldo o cuota insuficientes; engine_overloaded_error significa que el servidor está sobrecargado. Solo el problema de saldo se resuelve recargando; la sobrecarga de capacidad no desaparece por recargar. Para 500 y 503 se recomienda reintentar más tarde; cuando una solicitud larga agota el tiempo del gateway, es mejor pasar a streaming que reenviarla tal cual.

La documentación oficial no promete que las solicitudes fallidas sean gratuitas. Lo prudente es no suponer que reintentar no cuesta, conciliar con los registros de solicitudes y el campo usage, y contabilizar los reintentos por separado. La política de reintentos puede aplicarse en este orden:

  1. Clasifica primero por código de error; no reintentes deudas, errores de parámetros ni fallos de moderación de contenido.
  2. Reintenta solo ante límites 429, errores 500, 503 y cortes de red.
  3. Usa retroceso exponencial con jitter aleatorio y respeta Retry-After.
  4. Fija un máximo de reintentos y una duración total para no ocupar la concurrencia indefinidamente.
  5. En llamadas a herramientas, usa claves de idempotencia o una tabla de deduplicación para evitar pedidos o mensajes duplicados.
  6. Registra request_id, nombre del modelo, consumo de tokens y número de reintentos para facilitar la conciliación.

6. Estimar el presupuesto: de tokens a límite mensual

El presupuesto no debe calcularse al revés desde «cuánto cuesta un millón de tokens», sino desde tareas reales. Elige entre 20 y 50 tareas representativas, cubre los niveles simple, medio y complejo, y define criterios de aceptación; después mide la entrada con la interfaz de estimación, lee el usage de las llamadas reales y compara modelos por «costo total de completar una tarea aceptable».

import os
import requests

resp = requests.post(
    "https://api.moonshot.cn/v1/tokenizers/estimate-token-count",
    headers={"Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}"},
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Extrae este contrato a JSON: ..."}],
    },
    timeout=30,
)
print(resp.json()["data"]["total_tokens"])

Después de estimar la entrada de una llamada, agrega cuatro bloques: mensajes del historial, respuestas de herramientas, proporción de fallos de caché y llamadas adicionales por reintentos. Para el procesamiento por lotes fuera de línea se puede evaluar Batch API, que según la documentación oficial cuesta alrededor de un 40 % menos que las llamadas síncronas, aunque por ahora solo admite kimi-k2.7-code y kimi-k2.6; kimi-k3 todavía no está disponible allí.

El control del presupuesto conviene dividirlo en tres capas: presupuestos diarios y mensuales por proyecto, sabiendo que la consola rechaza las solicitudes del proyecto al alcanzar el límite pero la ejecución puede tardar unos diez minutos; separación por clave o por miembro para que un solo negocio no agote la cuota de toda la organización; y conciliación semanal por modelo y escenario para detectar las llamadas que más crecen. La alerta de saldo solo evita un corte repentino; no sustituye al presupuesto.

7. Orden para reducir costos y hábitos de conciliación

No inviertas el orden. Primero trabaja la caché y la gobernanza de la entrada, después limita la salida y solo al final considera cambiar de modelo; de lo contrario, solo estarás abaratando respuestas incorrectas.

  1. Fija el system prompt, las definiciones de herramientas y el prefijo de la base de conocimiento, y verifica cached_tokens.
  2. Reduce el texto original que se envía en cada llamada con recuperación y resúmenes; usa resúmenes rotativos para el historial.
  3. Configura max_completion_tokens, exige JSON o campos fijos y reduce las salidas abiertas y largas.
  4. Enruta por tarea: kimi-k2.6 para uso general, la versión de código K2.7 para programación y K3 para material ultralargo.
  5. Pasa las solicitudes largas a streaming para reducir reintentos por timeouts y desconexiones.
  6. Usa Batch API para tareas fuera de línea y conserva la interfaz síncrona para las tareas en tiempo real.
  7. Concilia cada mes por proyecto, modelo y escenario, y registra por separado la tasa de acierto de caché, los reintentos y la longitud media de salida.

La conciliación debe incluir al menos: hora de la llamada, proyecto, modelo, tokens de entrada, tokens con acierto de caché, tokens de escritura de caché, tokens de salida, número de reintentos y request_id. Sin estos campos, cualquier diferencia en la factura solo se puede adivinar.

Preguntas frecuentes

¿Puedo seguir llamando a moonshot-v1-8k?

No. Toda la serie moonshot-v1 fue retirada el 31 de agosto de 2026 y la documentación recomienda migrar a kimi-k3. No basta con cambiar el nombre del modelo: también hay que revisar la longitud de contexto, los conceptos de facturación y los parámetros de salida.

¿Por qué no funciona el acierto de caché?

Revisa primero si el prefijo se rompió por una marca de tiempo, un identificador aleatorio, un orden dinámico o una reordenación de herramientas; después confirma que el intervalo entre solicitudes no superó el TTL; por último, verifica que la escritura y la lectura de caché estén en la misma organización y en el mismo nivel de TTL. Decide con cached_tokens, no por intuición.

¿El contexto largo siempre cuesta más?

No necesariamente, pero reenviar material largo suele encarecer la factura. El costo depende de cuántas veces se repite la entrada, de la tasa de acierto de caché y de la longitud de salida. Reduce primero el alcance con recuperación y después decide si necesitas un contexto de un millón de tokens.

¿Las solicitudes fallidas se facturan?

La documentación oficial no promete que sean gratuitas. No supongas que reintentar tiene costo cero: comprueba con los registros de solicitudes y el campo usage, e incluye los reintentos en el costo por tarea.

¿Dónde se consultan los precios actuales?

En los precios de modelos del sitio y en la documentación oficial de Moonshot/Kimi. Los precios, la lista de modelos y las reglas de caché pueden cambiar; no uses capturas antiguas.

Próximos pasos

Crea una clave de prueba en ZSQH AI Gateway y ejecuta un lote de tareas reales con kimi-k2.6 y con kimi-k3; registra entrada, salida, aciertos de caché y reintentos antes de decidir el modelo principal y el presupuesto mensual. Los precios y los modelos disponibles se rigen por los precios de modelos.

Lecturas relacionadas: