Guida Pratica a Kimi K3: Nuovi Parametri e Matrice di Supporto API

Questo articolo tratta dei nuovi parametri e delle note di utilizzo per Kimi K3. Su AIHubMix, K3 è disponibile tramite le API di Chat Completions, Risposte e Messaggi compatibili con Claude. Vedi anche: documentazione ufficiale della piattaforma Moonshot.

Le conclusioni e le risposte campione "Verificate" in ciascuna sezione provengono da chiamate effettive effettuate il 2026-07-17 tramite le API di AIHubMix (Chat Completions / Risposte / Messaggi).

1. Specifiche del Modello a Colpo d'Occhio

Verificato: entrambi i limiti di stop sono convalidati e superare uno di essi restituisce 400; l'API Messaggi applica la stessa convalida a stop_sequences.

❗ Quando viene colpita una sequenza di stop, l'API Messaggi non segue la semantica di Anthropic: nei test, stop_reason è "end_turn" (anziché "stop_sequence"), stop_sequence è null, e il testo visibile prima della parola di stop potrebbe essere vuoto. I client che si basano su questi due campi per rilevare la troncatura dovrebbero prenderne nota.

# stop con 6 voci / una voce di 33 byte -> HTTP 400
"Richiesta non valida: array di stop troppo lungo. Ci si aspettava un array con lunghezza massima 5, ma è stato ricevuto un array con lunghezza 6"
"Richiesta non valida: la sequenza di stop non deve essere più lunga di 32, ma è stata ricevuta 33"

2. Modalità di Pensiero: reasoning_effort Supporta Solo max

Il pensiero di K3 è attivato per impostazione predefinita, e reasoning_effort supporta solo un singolo livello: "max".

Le conversazioni multi-turno devono restituire la storia del pensiero parola per parola: secondo la documentazione ufficiale di Moonshot, K3 è addestrato con il pensiero preservato, quindi nelle conversazioni multi-turno il messaggio precedente dell'assistente deve essere restituito completo e non modificato (incluso il contenuto del pensiero). La mancanza di storia del pensiero porta a una qualità di output instabile. Se utilizzi un framework di gestione delle sessioni o un livello proxy, conferma che il contenuto del pensiero venga restituito senza tagli.
Chat Completions

Il contenuto del pensiero viene restituito nel campo reasoning_content della risposta; nelle conversazioni multi-turno, restituisci il messaggio precedente dell'assistente (incluso reasoning_content) parola per parola.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "Una lumaca è sul fondo di un pozzo di 10 metri. Ogni giorno sale di 3 metri, ma ogni notte scivola indietro di 2 metri. Quanti giorni ci vogliono per raggiungere la cima?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# Multi-turn: restituisci il messaggio precedente dell'assistente parola per parola
messages = [
    {"role": "user", "content": "Qual è la capitale della Francia?"},
    {"role": "assistant", "content": "Parigi.", "reasoning_content": "<reasoning_content dalla risposta precedente>"},
    {"role": "user", "content": "E la sua popolazione?"},
]

Verificato: la risposta restituisce reasoning_content; dopo aver restituito il messaggio precedente dell'assistente (incluso reasoning_content) parola per parola, i turni successivi rispondono normalmente.
Risposte

Il contenuto del pensiero viene restituito come un elemento di output reasoning; nelle conversazioni multi-turno, aggiungi gli elementi di output del turno precedente (reasoning + message) di nuovo in input parola per parola.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="Rispondi in una parola: capitale della Francia",
)

# Tipi di elementi di output osservati: ["reasoning", "message"]; testo: "Parigi"
# Multi-turn: input = [primo messaggio dell'utente] + output della risposta + [prossimo messaggio dell'utente]
# Risposta osservata al secondo turno con elementi di output restituiti: "Berlino"

Messaggi

Il contenuto del pensiero viene restituito come blocchi di contenuto thinking nativi; nelle conversazioni multi-turno, restituisci i blocchi di contenuto precedenti dell'assistente (inclusi i blocchi di pensiero) parola per parola.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Rispondi in una parola: capitale della Francia"}
    ],
)

# Tipi di blocchi di risposta osservati: ["thinking", "text"]; testo: "Parigi"
# Multi-turn: restituisci response.content parola per parola come messaggio dell'assistente

3. I Parametri di Campionamento Sono Fissi

I parametri di campionamento di K3 sono fissati dal fornitore del modello: temperature 1.0, top_p 0.95, n 1, e presence_penalty / frequency_penalty 0. La raccomandazione ufficiale è di omettere questi parametri dalle richieste.

Nota: i valori di campionamento fissi fanno parte delle specifiche ufficiali e non possono essere verificati dai segnali di risposta; segui la raccomandazione ufficiale e ometti questi parametri.

4. Chiamata agli Strumenti e Caricamento Dinamico degli Strumenti

tools supporta fino a 128 strumenti; tool_choice supporta la forzatura e la disabilitazione delle chiamate agli strumenti. K3 supporta anche il caricamento dinamico degli strumenti: iniezione di nuovi strumenti a metà conversazione tramite il campo tools di un messaggio di sistema (una forma di messaggio specifica per l'API Chat).
Chat Completions

tool_choice supporta auto / none / required; required costringe il modello a chiamare uno strumento. Caricamento dinamico degli strumenti: il messaggio di sistema che inietta lo strumento non porta alcun content, gli strumenti iniettati hanno effetto per i turni successivi, e il messaggio deve essere incluso di nuovo in ogni richiesta.

messages = [
    {"role": "system", "content": "Sei un assistente utile."},
    {"role": "user", "content": "Ciao."},
    {"role": "assistant", "content": "Ciao, come posso aiutarti?"},
    # Inietta un nuovo strumento a metà conversazione: solo campo tools, nessun contenuto
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Ottieni l'ora attuale",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "Che ore sono adesso?"},
]

# tool_choice="required" con prompt "Ciao" -> il modello è costretto a chiamare lo strumento
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

Verificato: tool_choice: "required" costringe una chiamata allo strumento anche per prompt non correlati; "none" sopprime le chiamate agli strumenti; gli strumenti iniettati a metà conversazione tramite un messaggio di sistema senza content possono essere chiamati normalmente.
Risposte

Le definizioni degli strumenti utilizzano una struttura piatta (name a livello superiore); costringere una chiamata utilizza anch'esso tool_choice: "required", e le chiamate vengono restituite come elementi di output function_call. Il supporto per il caricamento dinamico degli strumenti è in fase di sviluppo; per ora, dichiara tutti gli strumenti nel parametro tools a livello superiore.

response = client.responses.create(
    model="kimi-k3",
    input="Ciao",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Ottieni il meteo per una città",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# L'output osservato contiene: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Messaggi

Gli strumenti utilizzano il formato di Anthropic (input_schema); costringi una chiamata con tool_choice: {"type": "any"} e disabilita le chiamate con {"type": "none"}. ❗ L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) non supporta il caricamento dinamico degli strumenti: nei test, il messaggio di iniezione restituisce 200, ma lo strumento iniettato non ha effetto (il modello non può chiamarlo). Dichiara tutti gli strumenti nel parametro tools a livello superiore.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Ottieni il meteo per una città",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Ciao"}],
)

# Osservato: stop_reason "tool_use"; il contenuto contiene un blocco tool_use che chiama get_weather

5. Output Strutturato

L'output strutturato fa sì che il modello restituisca contenuti che si conformano rigorosamente a uno schema JSON dato.
Chat Completions

response_format supporta json_schema con modalità strict.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Parigi è la capitale della Francia. Estrai il nome della città."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Contenuto di risposta osservato: {"city":"Parigi"}

Verificato: l'output è un JSON valido conforme allo schema.
Risposte

L'output strutturato è dichiarato tramite text.format.

response = client.responses.create(
    model="kimi-k3",
    input="Parigi è la capitale della Francia. Estrai il nome della città.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Testo di output osservato: {"city":"Parigi"}

Messaggi

❗ L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) non supporta l'output strutturato: i campi di output strutturato vengono silenziosamente ignorati: la richiesta restituisce HTTP 200 con testo libero, senza errore o avviso di fallback, e il parsing JSON a valle fallirà. Quando hai bisogno di output strutturato, utilizza le API Chat Completions o Responses.

6. Il Caching del Contesto è Automatico

Il caching del contesto di K3 è abilitato automaticamente, senza parametri richiesti. Quando un prefisso lungo ripetuto colpisce la cache, l'importo colpito viene riportato nell'uso (il nome del campo varia a seconda dell'API). I prezzi della cache sono sulla pagina del modello.
Chat Completions

# uso della seconda chiamata con un prefisso lungo identico
"prompt_tokens_details": {"cached_tokens": 1536}

Verificato: la seconda richiesta con un prefisso lungo identico riporta il colpo in usage.prompt_tokens_details.cached_tokens.
Risposte

# uso della seconda chiamata Risposte con istruzioni lunghe identiche
"input_tokens_details": {"cached_tokens": 1536}

Messaggi

# uso della seconda chiamata Messaggi con un lungo prompt di sistema identico
"cache_read_input_tokens": 1536

7. Completamento del Prefisso partial

Il completamento del prefisso fa sì che il modello continui a generare da un dato prefisso, ben adatto al completamento del codice e all'output controllato dal formato.
Chat Completions

Passa "partial": true nell'ultimo messaggio dell'assistente.

messages = [
    {"role": "user", "content": "Scrivi un haiku sul mare."},
    {"role": "assistant", "content": "Le onde si piegano nella schiuma,", "partial": True},
]

# Prefisso: "Le onde si piegano nella schiuma,"  ->  continuazione restituita dal modello
# il sale aleggia nell'aria—
# la luna tira la marea a casa.

Verificato: la generazione continua dal prefisso dato senza ripeterlo.
Risposte

Passa il prefisso come messaggio dell'assistente alla fine dell'array input; non è necessario alcun parametro partial.

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Scrivi un haiku sul mare."},
        {"role": "assistant", "content": "Le onde si piegano nella schiuma,"},
    ],
)

# Continuazione osservata: "il sale aleggia nell'aria— / la luna tira la marea a casa."

Messaggi

La stessa capacità è raggiunta con il prefill nativo dell'assistente del protocollo, senza alcun parametro partial: passa il prefisso come ultimo messaggio dell'assistente.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Scrivi un haiku sul mare."},
        {"role": "assistant", "content": "Le onde si piegano nella schiuma,"},
    ],
)

# Continuazione osservata: "il vento di sale porta il grido del gabbiano— / la marea tira ..."

8. Input Visivo

Le immagini vengono passate come base64; il formato del blocco di contenuto varia a seconda dell'API.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Qual è il colore dominante di questa immagine? Una parola."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Contenuto di risposta osservato: "Rosso"  (input: un PNG rosso solido 64x64)

Verificato: l'input dell'immagine base64 funziona, e il modello descrive correttamente l'immagine di test.
Risposte

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Qual è il colore dominante di questa immagine? Una parola."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Testo di output osservato: "Rosso"

Messaggi

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Qual è il colore dominante di questa immagine? Una parola."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Testo di risposta osservato: "Rosso"

9. Riferimento Verificato: Latenza e Utilizzo di un Compito Lungo in una Singola Chiamata

Il pensiero di K3 è fissato al livello massimo, quindi le richieste singole per compiti complessi richiedono significativamente più tempo rispetto ai modelli tipici. Dati misurati da un compito di generazione di gioco HTML a file singolo (un prompt con un'immagine di riferimento, generato in un colpo solo senza iterazione): la richiesta singola ha impiegato 2.541 secondi (circa 42 minuti), con 74.994 token di completamento, di cui 54.486 (73%) erano token di pensiero; l'output finale era di 1.275 righe di codice direttamente eseguibile, con finish_reason stop.

Raccomandazioni lato client:

• Imposta i timeout del client su minuti o più a lungo, e preferisci lo streaming per compiti lunghi;
• Lascia ampio margine in max_completion_tokens: in questo caso il solo pensiero ha consumato 54.486 token.

10. Capacità × Matrice di Supporto API

Ogni cella nella tabella sottostante è stata verificata il 2026-07-17 tramite chiamate effettive alle API di produzione di AIHubMix; ogni cella mostra la sintassi del parametro / campo per l'API corrispondente.

FAQ

Quali API supporta K3 su AIHubMix?
Chat Completions (/v1/chat/completions), Risposte (/v1/responses), e l'API Messaggi compatibile con Claude (/v1/messages).

È possibile disabilitare o ridurre il pensiero?
No. Il pensiero di K3 è attivato per impostazione predefinita, e reasoning_effort supporta solo il singolo livello "max".

Perché reasoning_content deve essere restituito nelle conversazioni multi-turno?
K3 è addestrato con il pensiero preservato; Moonshot richiede che il messaggio precedente dell'assistente venga restituito completo e non modificato. La mancanza di storia del pensiero porta a una qualità di output instabile.

Quali sono i limiti sul parametro stop?
Al massimo 5 sequenze di stop, ciascuna non più lunga di 32 byte; superare uno di questi limiti restituisce un errore 400.

L'API Messaggi supporta output strutturato?
❗ No. L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) ignora silenziosamente i campi di output strutturato (restituendo 200 con testo libero e senza errore). Per output strutturato, utilizza response_format su Chat Completions o text.format su Risposte.

Perché le richieste singole di K3 richiedono così tanto tempo?
Il pensiero di K3 è fissato al livello massimo, e i token di pensiero costituiscono una grande parte nei compiti complessi (73% dei token di completamento nel caso misurato). Imposta i timeout del client su minuti o più a lungo e utilizza lo streaming.

Per prezzi e stato in tempo reale, vedere la pagina del modello Kimi K3; per altri modelli, visita la galleria dei modelli.

Ultimo aggiornamento: 2026-07-17