Kimi K3.1 Pro

Usa l’ID pubblico kimi-k3.1-pro. La pagina del modello offre Playground e prezzi attuali. Scarica la specifica OpenAPI per gli schemi completi e annidati di richieste e risposte.

Guida rapida

curl https://api.seedrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"kimi-k3.1-pro",
    "messages":[{"role":"user","content":"How can an idempotency key prevent a duplicate payment?"}],
    "max_completion_tokens":2048,
    "reasoning_effort":"low"
  }'

Formati nativi

Usa Authorization: Bearer $SEEDROUTER_API_KEY. Messages usa anche anthropic-version: 2023-06-01. Ogni formato restituisce JSON nativo o eventi SSE. Responses è senza stato: reinvia l’intera cronologia; previous_response_id non è un campo di richiesta supportato.

Parametri della richiesta

I campi vuoti del Playground vengono omessi. I valori espliciti false e zero sono conservati dove validi. Omesso non significa nullable. Le estensioni sconosciute di primo livello vengono scartate; i campi ufficiali non validi vengono rifiutati. Gli schemi annidati degli strumenti e la cronologia restituita rimangono intatti.

Chat Completions

Responses

Messages

Chat ha 22 campi di primo livello: model, cinque campi di campionamento fissi e 16 input variabili. Responses ha model più 12 input; Messages ha model più 10 input. Il Playground nasconde il modello fisso e i controlli di campionamento fissi.

Ragionamento e limiti di output

Il ragionamento è sempre attivo. reasoning_effort di Chat, reasoning.effort di Responses e output_config.effort di Messages accettano low, high o max; predefinito: max. Tutti i limiti di output includono il ragionamento. Chat e Responses hanno un valore predefinito di 131.072 token di output e un massimo di 1.048.576. Messages richiede un max_tokens positivo. Chat accetta il deprecato max_tokens; preferisci max_completion_tokens nelle nuove integrazioni.

La finestra di contesto è di 1.048.576 token. L’input da solo deve rientrarvi. Quando input e budget di generazione superano la finestra, il servizio può ridurre il budget allo spazio residuo. Un limite di output basso può interrompere la generazione prima di una risposta visibile.

Il campionamento di Chat è fisso: temperature:1, top_p:0.95, n:1, frequency_penalty:0, presence_penalty:0. Altri valori non sono validi. Le sequenze di arresto corrispondono al testo esatto e vengono escluse dalla risposta. Il limite di 32 byte conta byte UTF-8, non caratteri.

Output strutturato e predizioni

Chat accetta text, json_object o json_schema per response_format.type. La modalità JSON richiede anche un prompt che chieda JSON. JSON Schema richiede json_schema.name e json_schema.schema; strict è true per impostazione predefinita.

Responses usa text.format con type:json_schema, schema e, facoltativamente, name e strict. Messages usa output_config.format con type:json_schema e schema. Segui Moonshot Flavored JSON Schema; non presumere che ogni estensione generale di JSON Schema venga applicata. Convalida l’output completato nella tua applicazione.

L’output predetto di Chat usa prediction:{type:"content",content:...}. Il contenuto è una stringa o parti di solo testo. Usalo per output in gran parte noto, come un file che riceve una piccola modifica.

Strumenti e conservazione della cronologia

Gli strumenti Chat usano type:function con function.name e function.parameters. I campi facoltativi includono description e strict (true per impostazione predefinita). I nomi rispettano ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$. La scelta dello strumento supporta auto, none e required; required richiede almeno uno strumento disponibile. Forzare una funzione specifica è incompatibile con il ragionamento sempre attivo.

Un messaggio dinamico di strumenti Chat è {role:"system",tools:[...]} senza contenuto. Conserva questi messaggi nella conversazione. Aggiungi l’intera risposta dell’assistente, inclusi reasoning_content e tool_calls, poi restituisci ogni risultato come messaggio role:tool con il tool_call_id corrispondente. Le risposte dell’assistente con strumenti possono avere contenuto null. Gli altri ruoli richiedono comunque contenuto.

Responses supporta definizioni native di strumenti function, namespace, personalizzati apply_patch e web_search, con tool_choice:"auto". Restituisci elementi function_call_output o custom_tool_call_output con gli ID di chiamata corrispondenti. I valori include web_search_call.results e web_search_call.action.sources riguardano solo l’output della ricerca web.

Messages supporta definizioni native degli strumenti e oggetti di scelta con tipo auto, any o none. Conserva i blocchi di ragionamento dell’assistente e le loro firme. Restituisci i blocchi dei risultati negli appositi messaggi utente. La tua applicazione convalida gli argomenti, esegue le funzioni personalizzate e controlla le azioni esterne.

Chat Partial Mode imposta partial:true solo sull’ultimo messaggio dell’assistente. Messages continua direttamente un messaggio finale dell’assistente. Non ricostruire la cronologia dal solo testo visibile della risposta.

Vincoli multimediali

Chat accetta blocchi di testo, image_url e video_url. Usa URL dati base64 o riferimenti ms:// accettati; URL multimediali pubblici arbitrari non sono supportati. Formati immagine: JPEG, PNG, GIF, WebP, BMP, HEIC e HEIF. Formati video: MP4, MPEG, MOV, AVI, FLV, MPG, WebM, WMV e 3GPP. La guida ufficiale indica un limite totale del corpo della richiesta di 100M, senza un limite separato al numero di immagini. Immagini 4K e video Full HD sono raccomandazioni, non limiti obbligatori.

Responses usa input_image.image_url con un URL dati. Messages usa una sorgente immagine come {type:"base64",media_type:"image/png",data:"..."}, oppure il tipo url con un riferimento ms:// accettato. I tipi di immagini inline di Messages sono JPEG, PNG, GIF e WebP. Questi formati non ereditano implicitamente il blocco video di Chat; usa i loro schemi dedicati.

Il Playground allega immagini inline. Usa i campi nativi di conversazione o l’editor JSON per blocchi video e riferimenti a file. Caricamento e gestione dei file non fanno parte di questi endpoint di generazione. Un ID di file creato con un altro account non è necessariamente utilizzabile.

Cache e utilizzo

Chat e Responses usano prompt_cache_key e prompt_cache_options:{mode:"implicit",ttl:"5m"}. TTL accetta 5m o 1h, con 5 minuti predefiniti. Messages usa cache_control:{type:"ephemeral",ttl:"5m"} al primo livello e, facoltativamente, metadata.user_id. I marcatori di controllo della cache annidati di Messages vengono ignorati. prompt_cache_breakpoint a livello di contenuto non è valido.

Un prefisso già in cache conserva la TTL originale quando viene rinnovato. Richiedere una durata diversa non prova che sia stata applicata. Gli header ufficiali di scrittura nella cache di Chat indicano i conteggi effettivi di 5 minuti e 1 ora. Responses può restituire le prompt_cache_options applicate; Messages riporta entrambi i contatori TTL in usage.cache_creation.

I totali di input di Chat e Responses includono già letture e scritture nella cache. Queste categorie e la parte non in cache non si sovrappongono; non sommare due volte i token della cache. L’output include il ragionamento. Messages separa le scritture in ephemeral_5m_input_tokens e ephemeral_1h_input_tokens. Consulta le tariffe attuali; le risposte pubbliche di generazione non contengono addebiti monetari.

Streaming e completamento

Imposta stream:true. Chat emette blocchi di dati e [DONE]; stream_options.include_usage:true richiede il blocco finale di utilizzo. Responses usa eventi con nome come response.output_text.delta, response.completed e response.incomplete. Messages usa message_start, eventi dei blocchi di contenuto, message_delta e message_stop.

Una connessione chiusa non prova da sola il completamento. Controlla i motivi nativi di fine e lo stato finale. Un flusso interrotto può non includere l’utilizzo finale. Interrompere la lettura non garantisce l’annullamento della generazione.

Riferimenti ufficiali

Verificati il 25 ottobre 2026: guida Kimi K3.1 Pro, Chat, Responses, Messages, visione e cache.