Kimi K3.1 Pro API: endpoints, llamada a herramientas, caché y errores
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 bas
Veröffentlicht am 26. Oktober • Zuerst erschienen auf apidog.com
Die Kimi K3.1 Pro API läuft unter https://api.moonshot.ai/v1 mit den Modell-IDs kimi-k3.1-pro und kimi-k3.1-pro-highspeed. Sie spricht drei Streaming-Formate: Chat Completions von OpenAI, die Responses API und Messages von Anthropic, sodass die SDKs, die du bereits verwendest, funktionieren, indem du nur die Base-URL änderst. Das Modell wird nach einer Mindestaufladung von 1 $ freigeschaltet.
Dies ist die Referenz für Produktionscode. Für deinen ersten Aufruf, Streaming und die Konfigurationen von Codex oder Claude Code lies, wie man Kimi K3.1 Pro verwendet; für die Kosten siehe die Preise von Kimi K3.1 Pro. Die Daten stammen aus dem K3.1 Pro Quickstart von Moonshot und den verlinkten Dokumenten, abgerufen am 24. Oktober 2026.
Moonshot stellt K3.1 Pro über drei API-Oberflächen bereit. Wähle diejenige, die deine Client-Bibliothek oder dein Agent bereits nutzt; Modell, Schlüssel und Abrechnung sind bei allen drei identisch.
Sie unterscheiden sich darin, wie der TTL des Caches festgelegt wird und wo die Nutzung erfasst wird (siehe Caching weiter unten). Kommst du von K3? Unser Leitfaden zur Kimi K3 API bleibt gültig; K3.1 Pro ist ein nachtrainiertes K3 mit demselben Kontext von 1.048.576 Tokens.
Du benötigst ein Konto mit Guthaben und einen Schlüssel des richtigen Produkts. Vier Schritte:
curl https://api.moonshot.ai/v1/models \ --header "Authorization: Bearer $MOONSHOT_API_KEY " | grep -o '"kimi-k3.1-pro[^"]*"' Enter fullscreen mode Exit fullscreen mode Wenn das Modell nicht in der Liste erscheint, behebe das zuerst. Kimi API, Kimi Code und Kimi Membership sind unterschiedliche Produkte: Ein Kimi-Code-Schlüssel funktioniert nicht am API-Endpoint, und eine Mitgliedschaft wird nicht in API-Guthaben umgewandelt.
Die meisten OpenAI-Parameter verhalten sich wie erwartet. Dies sind diejenigen, die abweichen oder Menschen häufig überrumpeln:
Reasoning-Tokens zählen zu deiner Nutzung, verwende daher "low" für Klassifizierung und Extraktion. Preserved Reasoning ist immer aktiviert, sodass jede Assistant-Nachricht mit ihrem reasoning_content intakt zurückkommt (Leitfaden zu Reasoning-Modellen).
Eine Produktions-Tool-Schleife in K3.1 Pro folgt vier Regeln aus der Dokumentation von Moonshot:
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 " Enter fullscreen mode Exit fullscreen mode Der klassische Fehler besteht darin, msg.content anstelle von msg hinzuzufügen, wodurch tool_calls und reasoning_content verworfen werden.
Wenn dein Agent Dutzende oder Hunderte von Tools hat, sende nicht alle Definitionen bei jeder Anfrage. Die Good Practice für Tool-Aufrufe von K3 bei Moonshot empfiehlt diesen Ablauf:
# after search_tools returns ["create_github_pr"] messages. append ({ " role ": " system ", " tools ": [ CATALOG [ " create_github_pr " ]]}) Enter fullscreen mode Exit fullscreen mode Die eingefügten Definitionen verwenden das Top-Level-Format tools und gelten ab dieser Nachricht. Der Server speichert sie nicht, daher musst du die Nachricht in nachfolgenden Anfragen beibehalten. Weder eine Änderung von tool_choice noch das Hinzufügen einer Definition bricht den Präfix-Cache.
K3.1 Pro akzeptiert Bilder und Video neben Text und gibt Text zurück. Wandle content in ein Array von Parts um: einen image_url-Part (das Quickstart-Beispiel sendet eine Base64-Data-URL und weist darauf hin, dass öffentliche Bild-URLs nicht unterstützt werden) oder einen video_url-Part, der auf eine hochgeladene Datei mit einer ms://-ID verweist.
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. " }] Enter fullscreen mode Exit fullscreen mode Übergib content als User-Nachricht und lösche die Datei mit client.files.delete(video.id), wenn du fertig bist.
Das Caching erfolgt automatisch für wiederholte Präfixe mit einem Standard-TTL von 5 Minuten. Cache-Treffer werden mit 0,20 $ pro Million Tokens abgerechnet, gegenüber 2,00 $ für nicht gecachten Input, und ein 1-Stunden-Schreibvorgang kostet 4,00 $ gegenüber 2,00 $ für 5 Minuten. Bei einem Präfix von 1 M Tokens amortisiert sich der 1-Stunden-TTL nach zwei Treffern.
Platziere stabilen Inhalt zuerst (System-Prompt, Tool-Definitionen, Dokumentation), sich ändernden Inhalt am Ende, und keine Zeitstempel im Präfix. Mit dem openai-SDK übergibst du den TTL über 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 )) Enter fullscreen mode Exit fullscreen mode Die Anthropic-API legt den TTL über ein Top-Level-Feld cache_control fest; Marker innerhalb der Nachrichten werden ignoriert:
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"}]}' Enter fullscreen mode Exit fullscreen mode Wo die Cache-Nutzung erscheint, hängt von der Schnittstelle ab:
Beim Streaming von Chat Completions setze stream_options.include_usage=true, um die Nutzung im letzten Chunk zu erhalten. Jeder Treffer erneuert den TTL, der bei der ersten Schreibanforderung festgelegt wird. Vollständige Regeln: der Leitfaden zum Context Caching.
Die meisten Fehler lassen sich auf sechs Muster zurückführen. Prüfe bei jedem 429 error.type, weil die Lösung davon abhängt.
Vorsicht bei Wiederholungsversuchen. Das OpenAI-SDK wiederholt Anfragen bei Verbindungsfehlern, 408, 409, 429 und 5xx standardmäßig 2-mal, sodass ein einzelner Aufruf zu drei Anfragen gegen dein RPM werden kann. In einem niedrigen Tier reduziere das max_retries des Clients und implementiere das Backoff selbst anhand von error.type. Anfragen, die durch ein 429 unterbrochen wurden, werden nicht abgerechnet.
Wenn ein Agent eines Drittanbieters fehlschlägt, rufe die API direkt mit demselben Schlüssel, Endpoint und Modell auf. Wenn das funktioniert, liegt das Problem am Tool. Siehe die Seite zur Fehlerbehebung und die Fehlercodes.
Deine kumulative Aufladung bestimmt dein Tier auf der Limits-Seite:
Tier 0 erlaubt 3 Anfragen pro Minute, und jeder Durchlauf einer Tool-Schleife ist eine Anfrage. Ein Agent-Run mit fünf Durchläufen überschreitet in diesem Tier bereits eine Minute, plane also 10 $ kumuliert ein, bevor du Agents ernsthaft testest.
Ein Vertragstest erkennt den Tag, an dem deine Tool-Schleife keine tool_calls mehr erhält. Lass deinen Coding-Agenten ihn mit der Apidog CLI erstellen. Installiere und melde dich einmal an:
npm install -g apidog-cli@latest apidog login --with-token <YOUR_TOKEN> apidog skill install Enter fullscreen mode Exit fullscreen mode Sage dann Claude Code, Codex oder dem Agenten, den du verwendest:
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.message.tool_calls is non-empty. Run it and report failures. Enter fullscreen mode Exit fullscreen mode Der Agent liest das Schema, validiert seine Payload und führt den Testfall aus:
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 Zum Erweitern in den Vollbildmodus wechseln Zum Erweitern den Vollbildmodus beenden Testfälle benötigen eine gültige Kategorie; apidog test-case category --project <projectId> listet diese auf. Sobald der Lauf erfolgreich ist, ändere -r cli,json zu -r junit mit --out-dir, und dieselbe Prüfung steuert deine CI, wie unser Leitfaden zu CI/CD mit der Apidog CLI zeigt. Die Konfiguration des Agents befindet sich in Apidog CLI in Claude Code.
Der kostenlose Plan von Apidog deckt bis zu 4 Nutzer ab.
https://api.moonshot.ai/v1 für Chat Completions und die Responses API, und https://api.moonshot.ai/anthropic für die zu Anthropic kompatible Messages API.
Nein. Das Reasoning ist immer aktiviert. Steuere es über das Feld reasoning_effort auf oberster Ebene ("low", "high" oder "max").
Lies error.type. engine_overloaded_error bedeutet Serverkapazität, und ein Neuladen wird das nicht beheben. rate_limit_reached_error bedeutet die Limits deiner Stufe, und Tier0 erlaubt nur 3 RPM.
Ein von null verschiedenes Cache-Read-Feld in usage bedeutet einen Treffer: prompt_tokens_details.cached_tokens bei Chat Completions oder cache_read_input_tokens bei Messages.
Nein. Die API erfordert eine Mindestaufladung von 1 $. Der kostenlose Chat in der Kimi-App ist der 0-$-Weg, behandelt in wie man Kimi K3.1 Pro kostenlos nutzt. Um das Modell kennenzulernen, siehe was ist Kimi K3.1 Pro.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Posted on Oct 26 • Originally published at apidog.com
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.
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.
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.
Necesitas una cuenta con saldo y una clave del producto correcto. Cuatro pasos:
curl https://api.moonshot.ai/v1/models \ --header "Authorization: Bearer $MOONSHOT_API_KEY " | grep -o '"kimi-k3.1-pro[^"]*"' Enter fullscreen mode Exit fullscreen mode 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.
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:
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 ).
Un bucle de herramientas de producción en K3.1 Pro sigue cuatro reglas de la documentación de Moonshot:
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 " Enter fullscreen mode Exit fullscreen mode El error clásico es añadir msg.content en lugar de msg, lo que descarta tool_calls y reasoning_content.
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:
# after search_tools returns ["create_github_pr"] messages. append ({ " role ": " system ", " tools ": [ CATALOG [ " create_github_pr " ]]}) Enter fullscreen mode Exit fullscreen mode 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.
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. " }] Enter fullscreen mode Exit fullscreen mode Pasa content como mensaje del usuario y elimina el archivo con client.files.delete(video.id) cuando termines.
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 )) Enter fullscreen mode Exit fullscreen mode 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"}]}' Enter fullscreen mode Exit fullscreen mode Dónde aparece el uso de la caché depende de la interfaz:
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.
La mayoría de los fallos se engloban en seis patrones. Comprueba error.type en cada 429, porque la solución depende de ello.
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.
Tu recarga acumulada determina tu nivel en la página de límites:
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.
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 Enter fullscreen mode Exit fullscreen mode 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.message.tool_calls is non-empty. Run it and report failures. Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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.
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.
No. El razonamiento siempre está activado. Contrólalo con el campo reasoning_effort de nivel superior ( "low", "high" o "max" ).
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.
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.
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.