API Kimi AI: come ottenerla, quanto costa e come integrarla con Kimi K3

L’API di Kimi AI dà accesso, dal proprio codice, ai modelli di Moonshot AI: oggi il modello di punta è Kimi K3, con una finestra di contesto da 1 milione di token, e accanto a lui ci sono K2.6 e K2.7 Code, più piccoli ed economici. L’interfaccia è compatibile con quella di OpenAI, quindi chi ha già uno script scritto per ChatGPT può passare a Kimi cambiando l’indirizzo del server, la chiave e il nome del modello. Quello che non c’è più è l’accesso gratuito: per fare la prima chiamata serve una ricarica, anche se di un solo dollaro.

Indice

1. Cosa offre oggi l’API di Kimi
2. È ancora gratis? Ricarica minima e buono
3. Come ottenere la chiave API
4. I modelli disponibili e quelli dismessi
5. Quanto costa: prezzi ed esempi di spesa
6. Prima chiamata: curl, Python e Node.js
7. Le particolarità di K3 da conoscere
8. Limiti di frequenza: i livelli dell’account
9. Usarla in n8n, LangChain e altri strumenti
10. Domande frequenti

Cosa offre oggi l’API di Kimi

Moonshot AI è la startup di Pechino che sviluppa Kimi. Oltre all’app per il pubblico, che abbiamo messo a confronto con ChatGPT e Claude nella guida Kimi vs ChatGPT vs Claude, l’azienda vende l’accesso ai suoi modelli attraverso la Kimi API Platform, pensata per chi sviluppa software, automazioni o agenti.

Secondo la documentazione ufficiale, la piattaforma espone oggi tre interfacce. La prima è Chat Completions, nello stesso formato di OpenAI. La seconda è Responses, sempre in formato OpenAI. La terza è Messages, compatibile con l’API di Anthropic: serve a collegare Kimi a strumenti costruiti per Claude, Claude Code compreso. Per chi parte da zero la strada più semplice resta la prima, perché funziona con la libreria Python o Node.js di OpenAI senza installare nulla di specifico.

I modelli non navigano su internet e non leggono database da soli. Per dargli accesso a dati esterni si usano gli strumenti ufficiali della piattaforma oppure funzioni scritte da chi sviluppa (il cosiddetto tool calling). Sulla ricerca web, la stessa guida di K3 avverte che è “in aggiornamento” e sconsiglia di usarla nel breve periodo per flussi di lavoro in produzione.

È ancora gratis? Ricarica minima e buono

No, e conviene chiarirlo subito perché molte guide, compresa la nostra prima versione, la presentavano come un’API gratuita. La pagina ufficiale Top-up & Rate Limits dice testualmente che per prevenire gli abusi bisogna ricaricare almeno 1 dollaro per iniziare a usare il servizio. La guida di Kimi K3 lo ripete: il modello di punta “si sblocca dopo una ricarica andata a buon fine (minimo 1 dollaro)”.

C’è un piccolo incentivo: quando le ricariche cumulative raggiungono 5 dollari, Moonshot accredita un buono da 5 dollari. In pratica chi ricarica 5 dollari ne ha 10 da spendere. Il buono però non conta per salire di livello: la stessa pagina precisa che i voucher non entrano nel totale delle ricariche che determina i limiti dell’account.

I prezzi sono indicati al netto delle imposte, che secondo la pagina dei prezzi vengono calcolate al momento del pagamento in base al paese di chi paga. Chi ricarica dall’Italia deve quindi aspettarsi un importo finale superiore alla cifra in dollari della ricarica. Le API per caricare file ed estrarne il testo sono, sempre secondo il listino, “temporaneamente gratuite”: si paga solo quando il testo estratto viene passato al modello.

Se cerchi qualcosa di davvero gratuito per sperimentare, ci sono servizi che hanno ancora un livello senza pagamento, con limiti stretti: li abbiamo verificati uno per uno nella guida alle alternative gratuite a Kimi con API.

Come ottenere la chiave API

La piattaforma internazionale si trova su platform.kimi.ai. L’indirizzo cinese platform.moonshot.cn, citato in molte vecchie guide, appartiene alla versione per la Cina continentale: dall’Italia va usata quella internazionale, che è anche quella documentata in inglese.

La procedura è breve. Ci si registra e si entra nella console. Si apre la sezione API Keys, si crea una nuova chiave dandole un nome riconoscibile (per esempio quello del progetto) e la si copia subito. Prima di usarla si passa dalla sezione di ricarica per caricare almeno 1 dollaro.

La documentazione raccomanda di non scrivere mai la chiave dentro il codice e di salvarla in una variabile d’ambiente chiamata MOONSHOT_API_KEY. Su Linux e Mac basta il comando export MOONSHOT_API_KEY="la-tua-chiave"; su Windows si usa il pannello delle variabili d’ambiente. Una chiave finita per sbaglio in un repository pubblico può essere usata da chiunque, e con un account ricaricato significa spendere soldi veri.

I modelli disponibili e quelli dismessi

L’elenco ufficiale dei modelli ne riporta quattro attivi per la chat:

Tutti e quattro accettano testo, immagini e video in ingresso. K3, presentato a luglio 2026, ha 2,8 mila miliardi di parametri ed è un modello aperto: Moonshot ha pubblicato i pesi completi, quindi in teoria può farlo girare anche un’altra azienda sui propri server. Per un privato non è un’opzione realistica, data la taglia.

La parte che interessa chi ha codice vecchio è quella dei modelli dismessi. Secondo la stessa pagina, l’intera serie moonshot-v1 (8k, 32k, 128k, auto e le varianti vision) è stata spenta il 31 agosto 2026, insieme a kimi-k2.5. La serie kimi-k2 (comprese le versioni preview, turbo e thinking) era già stata spenta il 25 maggio 2026 e kimi-latest il 28 gennaio 2026. Moonshot indica kimi-k3 come sostituto per tutti. Se uno script restituisce un errore sul nome del modello, la causa è quasi certamente questa.

Quanto costa: prezzi ed esempi di spesa

Il listino ufficiale è in dollari per milione di token, imposte escluse:

Per K3 c’è una voce in più: la scrittura in cache, cioè il costo di memorizzare l’inizio di una richiesta per riusarlo. Costa 3 dollari per milione di token con la durata predefinita di 5 minuti e 6 dollari con la durata di un’ora. La cache è automatica: quando una parte iniziale della richiesta (per esempio un lungo documento di istruzioni) si ripete entro la sua durata, quei token si pagano 0,30 dollari invece di 3.

Proviamo a tradurre il listino in casi concreti, con un esempio costruito da noi. Chiedere a K3 il riassunto di un documento da 15.000 token (una trentina di pagine) con una risposta da 1.000 token costa 0,045 dollari per l’ingresso e 0,015 per l’uscita, cioè 6 centesimi di dollaro. A questi va aggiunto il ragionamento: K3 ragiona sempre prima di rispondere, e la piattaforma fattura i token in ingresso più tutti quelli effettivamente generati. La stessa operazione con K2.6 costa circa 1,8 centesimi di dollaro (0,01425 per l’ingresso e 0,004 per l’uscita). Con la ricarica minima di 1 dollaro, quindi, si fanno al massimo una quindicina di riassunti di quel tipo con K3, meno se il ragionamento è lungo, e una cinquantina con K2.6.

Per avere un termine di paragone, le API dei modelli di Anthropic e OpenAI le abbiamo messe a confronto nell’articolo Claude vs GPT per chi lavora. Rispetto al listino di Anthropic, K3 costa meno di Opus 5.5 (4 e 20 dollari) e più di Sonnet 5.5 (2 e 10 dollari), mentre K2.6 costa meno di entrambi.

Prima chiamata: curl, Python e Node.js

Gli esempi che seguono ricalcano quelli della guida rapida ufficiale, con un messaggio in italiano al posto di quello originale. L’unico dato da cambiare rispetto a un codice scritto per OpenAI è l’indirizzo base: https://api.moonshot.ai/v1.

Il modo più veloce per verificare che chiave e ricarica funzionino è curl dal terminale:

curl https://api.moonshot.ai/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $MOONSHOT_API_KEY" \
    -d '{
        "model": "kimi-k3",
        "messages": [
            {"role": "system", "content": "Sei un assistente che risponde in italiano."},
            {"role": "user", "content": "Presentati in tre righe."}
        ]
    }'

In Python serve la libreria ufficiale di OpenAI, versione 1.0 o successiva (pip install --upgrade 'openai>=1.0'). La documentazione chiede Python 3.8 o più recente; gli esempi della guida di K3 indicano Python 3.9.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Sei un assistente che risponde in italiano."},
        {"role": "user", "content": "Spiegami in tre paragrafi come funziona il machine learning."}
    ]
)

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

In Node.js (versione 18 o successiva, con npm install openai@latest) la struttura è identica:

const OpenAI = require("openai");

const client = new OpenAI({
  apiKey: process.env.MOONSHOT_API_KEY,
  baseURL: "https://api.moonshot.ai/v1",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "kimi-k3",
    messages: [
      {"role": "system", "content": "Sei un assistente che risponde in italiano."},
      {"role": "user", "content": "Presentati in tre righe."}
    ]
  });
  console.log(completion.choices[0].message.content);
}

main();

Per passare a un modello più economico basta sostituire kimi-k3 con kimi-k2.6, oppure con kimi-k2.7-code-highspeed per il codice. La documentazione avverte però che i parametri accettati cambiano da modello a modello: un esempio scritto per K3 funziona su K2.6, ma non sempre vale il contrario.

Le particolarità di K3 da conoscere

Chi arriva da altre API inciampa di solito su tre aspetti, tutti descritti nella guida di Kimi K3.

Il ragionamento è sempre attivo. K3 non ha una modalità senza ragionamento. Si può però regolare quanto ragiona con il campo reasoning_effort, che accetta low, high e max. Il valore predefinito è max, il più costoso: per compiti semplici conviene impostare low. Con lo streaming il ragionamento arriva separato dalla risposta, nel campo reasoning_content.

Alcuni parametri sono bloccati. Temperature, top_p, n e le penalità di presenza e frequenza hanno valori fissi e la guida chiede di ometterli. Chi ha codice che imposta temperature deve toglierlo. K2.6 ha una regola simile: temperatura fissa a 1,0 con il ragionamento attivo e a 0,6 senza, e qualsiasi altro valore restituisce un errore. Su K2.6 il ragionamento si spegne con "thinking": {"type": "disabled"}.

Immagini solo in base64 o come file caricati. K3 non accetta indirizzi pubblici di immagini: vanno inviate codificate in base64 o caricate prima sulla piattaforma e richiamate con il loro identificativo. Il campo content deve essere un elenco di oggetti, non una stringa.

Ci sono anche due dati utili per i documenti lunghi. La risposta può arrivare fino a 1.048.576 token, ma il valore predefinito di max_completion_tokens è 131.072. Il server chiude le richieste che durano più di due ore con un errore 504.

Limiti di frequenza: i livelli dell’account

I limiti dipendono da quanto si è ricaricato in totale, non da un abbonamento. La tabella ufficiale è questa:

Il primo livello è molto stretto: una richiesta alla volta e 3 al minuto bastano per provare, non per un’applicazione con utenti veri. Con 10 dollari di ricariche si passa a 100 richieste al minuto e spariscono i limiti giornalieri. Tre dettagli della documentazione evitano sorprese. I limiti valgono per l’utente e non per la singola chiave, quindi creare più chiavi non li moltiplica. Sono condivisi fra tutti i modelli. E nel conteggio dei token al minuto la piattaforma usa il valore di max_completion_tokens della richiesta, non i token generati davvero: impostare un tetto alto “per sicurezza” fa raggiungere il limite prima. Quando si supera una soglia l’API risponde con l’errore 429.

La stessa pagina avverte che, se il sistema rileva attività anomale, scatta una limitazione per rischio che non può essere rimossa. È un motivo in più per non condividere la chiave.

Usarla in n8n, LangChain e altri strumenti

La compatibilità con il formato OpenAI vuol dire che Kimi si collega, in linea di principio, a qualunque strumento che permetta di indicare un indirizzo personalizzato al posto di quello di OpenAI. In questi casi i dati da inserire sono sempre gli stessi tre: indirizzo base https://api.moonshot.ai/v1, la chiave API e il nome del modello.

In n8n la strada più sicura è il nodo HTTP Request. Si imposta il metodo POST verso https://api.moonshot.ai/v1/chat/completions, si aggiunge un’intestazione Authorization con valore Bearer seguito dalla chiave e si mette nel corpo lo stesso JSON dell’esempio con curl. Un flusso tipico: arriva una mail con un PDF, n8n ne estrae il testo, lo manda a K2.6 chiedendo un riassunto e salva la risposta in un foglio di calcolo.

Per LangChain, LlamaIndex e simili vale lo stesso discorso: si usa il connettore OpenAI cambiando l’indirizzo base. Per gli strumenti nati per Claude, compreso Claude Code, Moonshot documenta l’interfaccia Messages compatibile con Anthropic e una guida dedicata nella sua documentazione. Nel nostro approfondimento sulle funzioni di Claude trovi invece come funziona Claude Code con il modello originale.

Una nota sui dati. Moonshot è un’azienda cinese, e nel confronto con ChatGPT e Claude abbiamo spiegato che l’informativa dell’app Kimi prevede la conservazione dei dati in Cina. Quella informativa riguarda l’app; per la piattaforma API valgono i termini che si accettano alla registrazione, da leggere prima di inviare documenti con dati personali di clienti o dipendenti.

Domande frequenti

L’API di Kimi è gratuita?

No. La chiave si crea gratis, ma per fare chiamate bisogna ricaricare almeno 1 dollaro. Quando le ricariche arrivano a 5 dollari Moonshot aggiunge un buono da 5 dollari. Il vecchio credito gratuito per i nuovi account, citato da molte guide, non compare nella documentazione attuale.

Il mio codice con moonshot-v1-32k ha smesso di funzionare: perché?

Perché la serie moonshot-v1 è stata spenta il 31 agosto 2026. Bisogna cambiare il nome del modello in kimi-k3 o kimi-k2.6 e l’indirizzo in https://api.moonshot.ai/v1. Se il codice imposta la temperatura, va tolta: su K3 è fissa.

Qual è la differenza tra api.moonshot.ai e api.moonshot.cn?

Il primo è l’indirizzo della piattaforma internazionale, quella documentata in inglese e accessibile dall’Italia tramite platform.kimi.ai. Il secondo appartiene alla piattaforma per la Cina continentale. Gli esempi ufficiali internazionali usano api.moonshot.ai.

Quanto contesto ha l’API di Kimi?

Kimi K3 arriva a 1.048.576 token, circa un milione. K2.6 e i due modelli K2.7 Code si fermano a 262.144 token. Ingresso e risposta insieme non possono superare la finestra del modello.

Posso usare l’API di Kimi con la libreria di OpenAI?

Sì, è la strada indicata dalla documentazione ufficiale: si installa la libreria openai (versione 1.0 o successiva) e si imposta base_url su https://api.moonshot.ai/v1. Esiste anche un’interfaccia compatibile con l’SDK di Anthropic.

Supporta lo streaming delle risposte?

Sì, con il parametro stream. Con K3 e con K2.6 in modalità ragionamento, lo stream invia separatamente il ragionamento (reasoning_content) e la risposta finale (content).

Se ti interessa usare Kimi senza scrivere codice, parti dalla guida all’app Kimi gratis e da quella su come analizzare documenti con Kimi.