La API de Kimi K3.1 Pro se ejecuta en https://api.moonshot.ai/v1 con los IDs de modelo kimi-k3.1-pro y kimi-k3.1-pro-highspeed. Habla tres formatos de transmisión: Chat Completions de OpenAI, la API de Responses y Messages de Anthropic, por lo que los SDK que ya usas funcionan cambiando la URL base. El modelo se desbloquea tras una recarga mínima de 1 $.
Esta es la referencia para código de producción. Para tu primera llamada, el streaming y las configuraciones de Codex o Claude Code, lee cómo usar Kimi K3.1 Pro; para los costes, consulta precios de Kimi K3.1 Pro. Los datos provienen del inicio rápido de K3.1 Pro de Moonshot y de los documentos enlazados, consultados el 24 de octubre de 2026.
API de Responses, API de Anthropic y Chat Completions de Kimi K3.1 Pro
Moonshot expone K3.1 Pro a través de tres superficies de API. Elige la que tu biblioteca cliente o agente ya utilice; el modelo, la clave y la facturación son los mismos en las tres.
| Interfaz | Formato | Endpoint | Cliente típico |
|---|---|---|---|
| Chat Completions | OpenAI | https://api.moonshot.ai/v1/chat/completions |
SDK openai, la mayoría de frameworks |
| Responses API | OpenAI Responses | https://api.moonshot.ai/v1/responses |
Codex (wire_api = "responses") |
| Messages API | Anthropic | https://api.moonshot.ai/anthropic/v1/messages |
SDK de Anthropic, Claude Code |
Se diferencian en cómo se establece el TTL de la caché y dónde se registra el uso (ver el almacenamiento en caché más abajo). ¿Vienes de K3? Nuestra guía de la API de Kimi K3 sigue siendo válida; K3.1 Pro es un K3 post-entrenado con el mismo contexto de 1.048.576 tokens.
Clave de API de Kimi K3.1 Pro: desbloquear y verificar el acceso
Necesitas una cuenta con saldo y una clave del producto correcto. Cuatro pasos:
- Recarga al menos 1 $ en la plataforma Kimi API. K3.1 Pro es un modelo insignia y solo se desbloquea tras una recarga correcta.
- Crea una clave en la consola de claves de API y expórtala como
MOONSHOT_API_KEY. - Confirma que el modelo es visible para esa clave con
GET /v1/models. - Llama a
kimi-k3.1-prodesde el código.
curl https://api.moonshot.ai/v1/models \
--header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'
Si el modelo no aparece en la lista, soluciona eso primero. Kimi API, Kimi Code y Kimi Membership son productos distintos: una clave de Kimi Code no funcionará en el endpoint de la API, y una membresía no se convierte en saldo de API.
Parámetros de solicitud que importan para K3.1 Pro
La mayoría de los parámetros de OpenAI se comportan como esperas. Estos son los que difieren o suelen pillar desprevenido a la gente:
| Parámetro | Qué hay que saber |
|---|---|
reasoning_effort |
Campo de nivel superior: "low", "high" o "max" (por defecto "max"). El razonamiento siempre está activado. |
thinking |
No lo envíes. K3.1 Pro no lo admite; usa reasoning_effort en su lugar. |
max_completion_tokens |
Por defecto 131072. La salida máxima es 1.048.576 menos tus tokens de prompt. |
response_format |
json_schema con strict: true. Analiza solo message.content, nunca reasoning_content. |
partial |
Pon "partial": true en un mensaje final del asistente para continuar desde un prefijo. |
tool_choice |
"required" fuerza al menos una llamada a herramienta; "auto" deja que el modelo decida. |
prompt_cache_options |
{"mode": "implicit", "ttl": "5m" o "1h"} en Chat Completions y Responses. |
Los tokens de razonamiento cuentan para tu uso, así que usa "low" para clasificación y extracción. El razonamiento preservado siempre está activado, por lo que cada mensaje del asistente vuelve con su reasoning_content intacto (guía de modelos con razonamiento).
Llamada a herramientas de Kimi K3.1 Pro: un bucle completo en Python
Un bucle de herramientas de producción en K3.1 Pro sigue cuatro reglas de la documentación de Moonshot:
- Fuerza una llamada a herramienta en el primer turno con
tool_choice="required"y luego cambia a"auto". - Añade el mensaje completo del asistente, incluidos
reasoning_contentytool_calls. - Envía un mensaje
toolpor cadatool_call_id. - Limita el número de turnos para que un modelo confundido no pueda entrar en un bucle infinito.
import json, os
from openai import OpenAI
client = OpenAI([REDACTED CREDENTIAL],
base_url="https://api.moonshot.ai/v1")
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up an order's shipping status by ID",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]}}}]
def get_order_status(order_id):
return {"order_id": order_id, "status": "shipped"}
messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8): # hard cap on turns
resp = client.chat.completions.create(
model="kimi-k3.1-pro", reasoning_effort="high",
messages=messages, tools=TOOLS, tool_choice=tool_choice)
msg = resp.choices[0].message
messages.append(msg) # whole message, not msg.content
if not msg.tool_calls:
print(msg.content)
break
for call in msg.tool_calls:
result = get_order_status(**json.loads(call.function.arguments))
messages.append({"role": "tool", "tool_call_id": call.id,
"content": json.dumps(result)})
tool_choice = "auto"
El error clásico es añadir msg.content en lugar de msg, lo que descarta tool_calls y reasoning_content.
Llamada a herramientas a escala con search_tools
Cuando tu agente tiene decenas o cientos de herramientas, no envíes todas las definiciones en cada solicitud. La buena práctica de llamada a herramientas de K3 de Moonshot recomienda este flujo:
- Declara una función
search_tools(tu backend la implementa) más unas pocas herramientas principales. - Establece
tool_choice: "required"en el primer turno para que el modelo recupere antes de responder. - Inyecta las definiciones de herramientas coincidentes mediante un mensaje
systemque lleve un campotools. - Deja que el modelo llame a las herramientas cargadas en turnos posteriores, con
tool_choicede nuevo en"auto".
# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
"tools": [CATALOG["create_github_pr"]]})
Las definiciones inyectadas usan el formato tools de nivel superior y se aplican a partir de ese mensaje. El servidor no las conserva, así que mantén el mensaje en solicitudes posteriores. Ni cambiar tool_choice ni añadir una definición rompe la caché de prefijo.
Entrada de visión y vídeo
K3.1 Pro acepta imágenes y vídeo junto con texto y devuelve texto. Convierte content en un array de partes: una parte image_url (el ejemplo del inicio rápido envía una URL de datos en base64 y señala que las URL de imágenes públicas no son compatibles) o una parte video_url que apunta a un archivo subido con un ID ms://.
from pathlib import Path
video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
{"type": "text", "text": "Summarize this video."}]
Pasa content como mensaje del usuario y elimina el archivo con client.files.delete(video.id) cuando termines.
Caché de contexto en código
El almacenamiento en caché es automático para prefijos repetidos con un TTL predeterminado de 5 minutos. Los aciertos de caché se facturan a 0,20 $ por millón de tokens frente a 2,00 $ para la entrada no cacheada, y una escritura de 1 hora cuesta 4,00 $ frente a 2,00 $ por 5 minutos. En un prefijo de 1 M de tokens, el TTL de 1 hora se amortiza tras dos aciertos.
Coloca primero el contenido estable (prompt de sistema, definiciones de herramientas, documentación), el contenido cambiante al final, y sin marcas de tiempo en el prefijo. Con el SDK openai, pasa el TTL a través de extra_body:
resp = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "system", "content": DOCS},
{"role": "user", "content": question}],
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
getattr(d, "cache_write_tokens", 0))
La API de Anthropic establece el TTL con un campo cache_control de nivel superior; los marcadores dentro de los mensajes se ignoran:
curl https://api.moonshot.ai/anthropic/v1/messages \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $MOONSHOT_API_KEY" \
--data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
"cache_control": {"type": "ephemeral", "ttl": "1h"},
"messages": [{"role": "user", "content": "Hello"}]}'
Dónde aparece el uso de la caché depende de la interfaz:
| Interfaz | Lectura de caché | Escritura de caché |
|---|---|---|
| Chat Completions | usage.prompt_tokens_details.cached_tokens |
usage.prompt_tokens_details.cache_write_tokens |
| Responses | usage.input_tokens_details.cached_tokens |
usage.input_tokens_details.cache_write_tokens |
| Messages | usage.cache_read_input_tokens |
usage.cache_creation_input_tokens |
Al hacer streaming de Chat Completions, establece stream_options.include_usage=true para obtener el uso en el fragmento final. Cada acierto renueva el TTL, que queda fijado en la primera escritura. Reglas completas: la guía de almacenamiento en caché de contexto.
Errores y soluciones de la API de Kimi K3.1 Pro
La mayoría de los fallos se engloban en seis patrones. Comprueba error.type en cada 429, porque la solución depende de ello.
| Síntoma | Causa | Solución |
|---|---|---|
| 401 o 404 | Clave de producto incorrecta, discrepancia de región, sin saldo o nombre de modelo incorrecto | Usa una clave de Kimi API, comprueba el saldo, confirma el modelo en GET /v1/models, limpia variables de entorno y proxies obsoletos |
429 engine_overloaded_error
|
Capacidad del servidor | Espera según Retry-After, aplica retroceso, reduce la concurrencia. Recargar saldo no ayudará. |
429 rate_limit_reached_error
|
Tu organización alcanzó los límites de concurrencia, RPM, TPM o TPD | Ve más despacio o sube de nivel |
429 exceeded_current_quota_error
|
Saldo bajo, cuenta vencida o cupón caducado | Consulta la API de saldo y recarga |
finish_reason: "length" |
La salida alcanzó max_completion_tokens
|
Aumenta el límite o continúa con el modo partial |
| La misma herramienta se llama una y otra vez | Estructura de mensajes rota | Añade el mensaje tal cual, haz coincidir cada tool_call_id, ensambla por completo los tool_calls transmitidos y luego añade detección de repeticiones en el cliente |
Cuidado con los reintentos. El SDK de OpenAI reintenta 2 veces de forma predeterminada ante errores de conexión, 408, 409, 429 y 5xx, así que una llamada puede convertirse en tres solicitudes contra tu RPM. En un nivel bajo, reduce el max_retries del cliente y aplica tú mismo el retroceso según error.type. Las solicitudes interrumpidas por un 429 no se cobran.
Si un agente de terceros falla, llama a la API directamente con la misma clave, endpoint y modelo. Si eso funciona, el problema es la herramienta. Consulta la página de solución de problemas y los códigos de error.
Límites de velocidad de Kimi K3.1 Pro por nivel
Tu recarga acumulada determina tu nivel en la página de límites:
| Nivel | Recarga acumulada | Concurrencia | RPM | TPM |
|---|---|---|---|---|
| Tier0 | $1 | 1 | 3 | 500.000 (1,5 M al día) |
| Tier1 | $10 | 15 | 100 | 2.000.000 |
| Tier2 | $20 | 40 | 100 | 3.000.000 |
| Tier3 | $100 | 50 | 200 | 3.000.000 |
| Tier4 | $1,000 | 60 | 200 | 4.000.000 |
| Tier5 | $3,000 | 100 | 300 | 5.000.000 |
El nivel Tier0 permite 3 solicitudes por minuto, y cada turno de un bucle de herramientas es una solicitud. Una ejecución de agente de cinco turnos ya supera un minuto en ese nivel, así que presupuesta 10 $ acumulados antes de probar agentes en serio.
Pruebas de contrato de la API de Kimi con Apidog CLI
Una prueba de contrato detecta el día en que tu bucle de herramientas deja de recibir tool_calls. Deja que tu agente de programación la construya con Apidog CLI. Instala e inicia sesión una vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Luego indica a Claude Code, Codex o el agente que uses:
In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.
El agente lee el esquema, valida su payload y ejecuta el caso:
apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json
Los casos de prueba necesitan una categoría válida; apidog test-case category --project <projectId> las lista. Una vez que la ejecución pase, cambia -r cli,json por -r junit con --out-dir y la misma comprobación controlará tu CI, como muestra nuestra guía de CI/CD con Apidog CLI. La configuración del agente está en Apidog CLI en Claude Code. El plan gratuito de Apidog cubre hasta 4 usuarios.
Preguntas frecuentes
¿Cuál es la URL base de la API de Kimi K3.1 Pro?
https://api.moonshot.ai/v1 para Chat Completions y la API de Responses, y https://api.moonshot.ai/anthropic para la API de Messages compatible con Anthropic.
¿La API de Kimi K3.1 Pro admite el parámetro thinking?
No. El razonamiento siempre está activado. Contrólalo con el campo reasoning_effort de nivel superior ("low", "high" o "max").
¿Por qué recibo un 429 justo después de recargar saldo?
Lee error.type. engine_overloaded_error es capacidad del servidor y una recarga no lo solucionará. rate_limit_reached_error significa los límites de tu nivel, y Tier0 solo permite 3 RPM.
¿Cómo sé si el almacenamiento en caché está funcionando?
Un campo de lectura de caché distinto de cero en usage significa un acierto: prompt_tokens_details.cached_tokens en Chat Completions o cache_read_input_tokens en Messages.
¿Existe un nivel gratuito de la API de Kimi K3.1 Pro?
No. La API requiere una recarga mínima de 1 $. El chat gratuito en la app de Kimi es la vía de 0 $, tratada en cómo usar Kimi K3.1 Pro gratis. Para conocer el modelo, consulta qué es Kimi K3.1 Pro.
Top comments (0)