Kimi K3 API

K3 è compatibile con il formato OpenAI. Va bene qualsiasi SDK OpenAI: punti base_url a un endpoint che serve kimi-k3 e imposti la stringa del modello. L'integrazione è tutta qui.

Guida rapida

Questo codice chiama K3 attraverso EvoLink, che serve kimi-k3 su un endpoint compatibile con OpenAI. Sostituisci il base_url con quello di un altro gateway: il resto non cambia.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_EVOLINK_API_KEY",
    base_url="https://direct.evolink.ai/v1",   # <-- l'unica riga che cambi
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Explain prompt caching in two sentences."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)

curl https://direct.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain prompt caching in two sentences."}
    ]
  }'

L'autenticazione è un bearer token: Authorization: Bearer <key>. Tienila in una variabile d'ambiente, mai nel codice sorgente. Il percorso dell'endpoint è /v1/chat/completions: se usi un SDK OpenAI, passagli la radice /v1 e lascia che sia l'SDK ad aggiungere il resto.

La key: dove ottenerla — decidi in base a cosa chiamerai

Il codice qui sopra ha bisogno di una API key, e la fonte giusta dipende da una sola domanda. Chiamerai soltanto modelli Kimi? Allora vai diretto a Moonshot: nessun intermediario, e il codice di questa pagina funziona anche lì con base_url="https://api.moonshot.ai/v1". K3 starà accanto a GPT, Claude o Gemini? Allora ti serve un gateway: una sola key e un solo saldo per tutti. I due da valutare sono EvoLink e OpenRouter; li abbiamo misurati uno contro l'altro, e gli esempi di questo sito usano EvoLink come impostazione predefinita perché restituisce la struttura di risposta nativa di Moonshot senza modifiche. Tre cose sono identiche su ogni percorso:

• Le tariffe — $3.00 / $0.30 / $15.00 per 1M di token, con data.
• Il comportamento del modello — i blocchi della cache e la fatturazione del ragionamento; è lo stesso modello.
• Il codice — formato OpenAI ovunque; cambiare più avanti è una riga di base_url.

A cambiare è tutto quello che sta intorno alla chiamata:

Stai valutando OpenRouter? Stessa tariffa di listino, stesso modello, stessa cache — ma rinomina il campo reasoning_content di K3, e il codice scritto sulla documentazione di Moonshot smette di vederlo senza dire niente. Il confronto misurato copre questo, l'affidabilità e la latenza.

Dopo la registrazione arrivi nella dashboard, con onboarding e 10 crediti gratuiti. Hai già un account? Prendi una key dalla dashboard →

Com'è fatta una risposta reale

Accorciata, ma per il resto è esattamente quello che è tornato indietro:

{
  "id": "chatcmpl-6a593017ec44f116fb614895",
  "object": "chat.completion",
  "created": 1784229923,
  "model": "kimi-k3",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "OK",
      "reasoning_content": "The user is asking me to reply with exactly \"OK\". This is a simple request with no complications..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 90,
    "completion_tokens": 47,
    "total_tokens": 137,
    "completion_tokens_details": {"reasoning_tokens": 31},
    "prompt_tokens_details": {"cached_tokens": 90}
  }
}

Su cached_tokens: 90 uguale a prompt_tokens: era una chiamata ripetuta dello stesso prompt da 90 token, e i prompt piccoli possono finire in cache per intero. La granularità a blocchi di 256 token che abbiamo misurato altrove si vede quando il prefisso supera i ~1k token — la pagina sul caching contiene entrambi i set di dati.

Due campi meritano attenzione perché non hanno un equivalente in OpenAI:

• message.reasoning_content — il ragionamento di K3, restituito insieme alla risposta. La risposta vera leggila da content. Su K3 il ragionamento non è una modalità che attivi: è sempre acceso.
• usage.completion_tokens_details.reasoning_tokens — quanti token di output sono finiti nel ragionamento. Qui sopra, 31 su 47 token per una risposta di due lettere. Vengono fatturati alla tariffa di output.

Verifica che la chiamata sia andata a buon fine

Su K3 un HTTP 200 non è la prova che sia andato tutto bene. Controlla quattro cose:

1. model restituisce kimi-k3 — e non un fallback che il gateway ha sostituito in silenzio.
2. finish_reason è stop, non length — length con contenuto vuoto è la firma della trappola del budget di ragionamento.
3. content è una stringa vera, non "".
4. usage.total_tokens è diverso da zero — e ti dice quanto hai speso.

Nel codice, l'unico controllo che vale la pena scrivere:

choice = response.choices[0]
if choice.finish_reason == "length" and not choice.message.content:
    raise RuntimeError(
        f"Reasoning consumed the whole budget "
        f"({response.usage.completion_tokens_details.reasoning_tokens} reasoning tokens). "
        f"Raise max_completion_tokens."
    )

I parametri che contano

Riferimento completo di parametri e schema di risposta: la documentazione API kimi-k3 di EvoLink (docs.evolink.ai).

Input di immagini

K3 accetta immagini, con due vincoli che rompono lo schema dato per scontato dalla maggior parte del codice OpenAI-vision. Secondo la guida rapida ufficiale di Moonshot (letta il 2026-07-20): gli URL pubblici delle immagini non sono supportati — manda l'immagine in base64 o come riferimento ms://<file-id> — e il content del messaggio deve essere un array di oggetti, non una stringa semplice. Il vision non l'abbiamo ancora misurato noi; questa sezione riporta la documentazione, non una misurazione.

Streaming

Server-sent events, chiusi da data: [DONE]. La particolarità di K3: i primi token che ricevi sono ragionamento, non la risposta. Su prompt brevi realistici (n=10, direct.evolink.ai, una sola finestra pomeridiana, 2026-07-18) la mediana è stata 11.3s al primo token di ragionamento e 21.4s al primo token di content, con singole esecuzioni ovunque tra 2.9s e 40s — forte oscillazione di ora in ora. Un prompt banale «say OK» è molto più rapido: 2.8s il 2026-07-16, 3.35s rimisurato il 07-18. E in tre esecuzioni su cinque del 2026-07-16 il token di content non è mai arrivato, perché un tetto di 128 token è stato consumato dal ragionamento.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Count to three."}],
    stream=True,
    stream_options={"include_usage": True},   # altrimenti non ricevi alcun usage
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        pass                      # ragionamento — di solito non è ciò che mostri
    if delta.content:
        print(delta.content, end="", flush=True)

Se mostri reasoning_content agli utenti, sappi che stai facendo vedere gli appunti del modello. Alla maggior parte dei prodotti conviene mostrare uno spinner durante il ragionamento e trasmettere in streaming solo content.

Un'altra cosa da mettere in conto: nelle ore di punta puoi incontrare 429 o errori di capacità. La nostra esecuzione del 2026-07-18 ha fatto 50 chiamate senza un solo errore, ma è un giorno in una sola finestra — prevedi un percorso di retry, tieni a portata di mano il riferimento errori e controlla lo stato in tempo reale se le chiamate iniziano a fallire.

FAQ sull'API

Qual è il model ID di Kimi K3?

Esattamente kimi-k3. Sbaglialo — per esempio kimi-k3-chat — e ricevi un HTTP 404 il cui corpo di errore contiene "did_you_mean": "kimi-k3", segnala l'errore come permanente (non riprovare con lo stesso ID) e ti rimanda a GET /v1/models (misurato il 2026-07-18).

Kimi K3 è compatibile con OpenAI?

Sì. K3 viene servito sulla forma standard /v1/chat/completions, quindi qualsiasi SDK OpenAI funziona senza modifiche: imposti base_url e la stringa del modello. Le due aggiunte specifiche di K3 sono reasoning_content nel messaggio e reasoning_tokens in usage.

Serve un account Moonshot per usare l'API di Kimi K3?

No. Va bene qualsiasi endpoint che serve kimi-k3: tramite EvoLink un solo account con 10 crediti gratuiti raggiunge K3 insieme a GPT, Claude, Gemini e decine dei principali modelli al mondo, alle stesse tariffe di Moonshot diretto.

Quale base_url devo usare per Kimi K3?

Tramite EvoLink: https://direct.evolink.ai/v1. Diretto a Moonshot: https://api.moonshot.ai/v1 (guida rapida di Moonshot, letta il 2026-07-20). Il resto del codice è identico in entrambi i casi.