Guida pratica a Kimi K3: nuovi parametri e matrice di supporto alle API

Questo articolo illustra i nuovi parametri e le note d'uso per Kimi K3. Su AIHubMix, K3 è disponibile tramite le API Chat Completions, Responses e Messages compatibile con Claude. Vedi anche: documentazione ufficiale della piattaforma Moonshot.

Le conclusioni "Verificato" e le risposte di esempio in ogni sezione provengono da chiamate effettive eseguite il 17-07-2026 tramite le API di AIHubMix (Chat Completions / Responses / Messages).

1. Specifiche del modello in sintesi

Verificato: entrambi i limiti di stop vengono validati e superarli restituisce 400; l'API Messages applica la stessa validazione a stop_sequences.

❗ Quando viene raggiunta una sequenza di arresto, l'API Messages 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 arresto può risultare vuoto. I client che si basano su questi due campi per rilevare un troncamento devono tenerne conto.

# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"

2. Modalità di ragionamento: reasoning_effort supporta solo max

Il ragionamento di K3 è attivo per impostazione predefinita, e reasoning_effort supporta un unico livello: "max".

La cronologia del ragionamento nelle conversazioni multi-turno va restituita integralmente: secondo la documentazione ufficiale di Moonshot, K3 è addestrato con ragionamento preservato, quindi nelle conversazioni multi-turno il messaggio precedente dell'assistente deve essere restituito completo e non modificato (incluso il contenuto del ragionamento). La mancanza della cronologia del ragionamento porta a una qualità dell'output instabile. Se usi un framework di gestione delle sessioni o un livello proxy, verifica che il contenuto del ragionamento venga restituito senza tagli.
Chat Completions

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

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": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
    ],
)

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

# Multi-turn: pass the previous assistant message back verbatim
messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "Paris.", "reasoning_content": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "And its population?"},
]

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

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

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="Answer in one word: capital of France",
)

# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"

Messages

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

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": "Answer in one word: capital of France"}
    ],
)

# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message

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 della specifica ufficiale e non possono essere verificati dai segnali di risposta; segui la raccomandazione ufficiale e omettili.

4. Chiamata di strumenti e caricamento dinamico degli strumenti

tools supporta fino a 128 strumenti; tool_choice supporta la forzatura e la disattivazione delle chiamate agli strumenti. K3 supporta anche il caricamento dinamico degli strumenti: l'inserimento di nuovi strumenti durante la conversazione tramite il campo tools di un messaggio di sistema (una struttura di messaggio specifica dell'API Chat).
Chat Completions

tool_choice supporta auto / none / required; required obbliga il modello a chiamare uno strumento. Caricamento dinamico degli strumenti: il messaggio di sistema che inserisce gli strumenti non contiene content, gli strumenti inseriti hanno effetto dai turni successivi e il messaggio deve essere incluso di nuovo in ogni richiesta.

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello."},
    {"role": "assistant", "content": "Hi, how can I help you?"},
    # Inject a new tool mid-conversation: tools field only, no content
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Get the current time",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "What time is it now?"},
]

# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

Verificato: tool_choice: "required" forza una chiamata di strumento anche per prompt non pertinenti; "none" sopprime le chiamate agli strumenti; gli strumenti inseriti durante la conversazione tramite un messaggio di sistema senza content possono essere chiamati normalmente.
Responses

Le definizioni degli strumenti usano una struttura piatta (name al livello superiore); forzare una chiamata si ottiene allo stesso modo con tool_choice: "required", e le chiamate vengono restituite come elementi di output function_call. Il supporto al caricamento dinamico degli strumenti è in corso; per ora, dichiara tutti gli strumenti nel parametro tools di primo livello.

response = client.responses.create(
    model="kimi-k3",
    input="Hello",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Messages

Gli strumenti usano il formato Anthropic (input_schema); per forzare una chiamata usa tool_choice: {"type": "any"} e per disattivarle {"type": "none"}. ❗ L'endpoint Messages ufficiale di Kimi K3 (compatibile con Anthropic) non supporta il caricamento dinamico degli strumenti: nei test, il messaggio che li inserisce restituisce 200, ma lo strumento inserito non ha effetto (il modello non riesce a chiamarlo). Dichiara tutti gli strumenti nel parametro tools di primo livello.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Hello"}],
)

# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather

5. Output strutturato

L'output strutturato fa sì che il modello restituisca contenuti che rispettano rigorosamente 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": "Paris is the capital of France. Extract the city name."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Observed response content: {"city":"Paris"}

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

L'output strutturato si dichiara tramite text.format.

response = client.responses.create(
    model="kimi-k3",
    input="Paris is the capital of France. Extract the city name.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Observed output text: {"city":"Paris"}

Messages

❗ L'endpoint Messages ufficiale di Kimi K3 (compatibile con Anthropic) non supporta l'output strutturato: i campi relativi all'output strutturato vengono ignorati silenziosamente; la richiesta restituisce HTTP 200 con testo libero, senza errori né avvisi, e il parsing JSON a valle fallirà. Quando ti serve un output strutturato, usa l'API Chat Completions o Responses.

6. Il caching del contesto è automatico

Il caching del contesto di K3 è abilitato automaticamente, senza parametri da impostare. Quando un prefisso lungo e ripetuto colpisce la cache, la quantità di hit viene riportata in usage (il nome del campo varia a seconda dell'API). I prezzi della cache sono indicati nella pagina del modello.
Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}

Verificato: la seconda richiesta con un prefisso lungo identico riporta l'hit in usage.prompt_tokens_details.cached_tokens.
Responses

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. Completamento del prefisso con partial

Il completamento del prefisso fa sì che il modello continui a generare a partire da un prefisso dato, particolarmente adatto al completamento di codice e a output con formato controllato.
Chat Completions

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

messages = [
    {"role": "user", "content": "Write a haiku about the sea."},
    {"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]

# Prefix: "Waves fold into foam,"  ->  continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.

Verificato: la generazione prosegue dal prefisso dato senza ripeterlo.
Responses

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

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt hangs in the air— / moon pulls the tide home."

Messages

La stessa funzionalità si ottiene con il prefill nativo dell'assistente del protocollo, senza parametro partial: passa il prefisso come ultimo messaggio dell'assistente.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."

8. Input visivo

Le immagini vengono passate in base64; il formato dei blocchi di contenuto varia a seconda dell'API.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Observed response content: "Red"  (input: a 64x64 solid red PNG)

Verificato: l'input di immagini in base64 funziona e il modello descrive correttamente l'immagine di test.
Responses

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What is the dominant color of this image? One word."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

Messages

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Observed response text: "Red"

9. Riferimento verificato: latenza e utilizzo di un'attività lunga in una sola chiamata

Il ragionamento di K3 è fissato al livello max, quindi le richieste singole per attività complesse richiedono molto più tempo rispetto ai modelli tipici. Dati misurati da un'attività di generazione di un gioco HTML in un unico file (un solo prompt con un'immagine di riferimento, generato in un'unica soluzione senza iterazioni): la singola richiesta ha impiegato 2.541 secondi (circa 42 minuti), con 74.994 token di completamento, di cui 54.486 (73%) token di ragionamento; l'output finale è composto da 1.275 righe di codice eseguibile direttamente, con finish_reason stop.

Raccomandazioni lato client:

• Imposta timeout del client di minuti o più, e preferisci lo streaming per le attività lunghe;
• Lascia ampio margine in max_completion_tokens: in questo caso il solo ragionamento ha consumato 54.486 token.

10. Matrice di supporto Funzionalità × API

Ogni cella della tabella seguente è stata verificata il 17-07-2026 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), Responses (/v1/responses) e l'API Messages compatibile con Claude (/v1/messages).

Il ragionamento può essere disattivato o ridotto?
No. Il ragionamento di K3 è attivo per impostazione predefinita, e reasoning_effort supporta solo il singolo livello "max".

Perché reasoning_content deve essere passato nelle conversazioni multi-turn?
K3 è addestrato con il pensiero preservato; Moonshot richiede che il messaggio precedente dell'assistente venga passato per intero e senza modifiche. Se manca la cronologia del ragionamento, la qualità dell'output diventa instabile.

Quali sono i limiti del parametro stop?
Sono consentite al massimo 5 sequenze di stop, ciascuna di non più di 32 byte; superando uno dei due limiti viene restituito un errore 400.

L'API Messages supporta l'output strutturato?
❗ No. L'endpoint Messages ufficiale di Kimi K3 (compatibile con Anthropic) ignora silenziosamente i campi per l'output strutturato, restituendo 200 con testo libero e nessun errore. Per l'output strutturato, usa response_format su Chat Completions oppure text.format su Responses.

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

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

Ultimo aggiornamento: 2026-07-17