API Chat Completion: come funziona e come utilizzarla

Scopri come funziona l'API Chat Completion, impara a integrarla con Python, comprendi i parametri chiave, lo streaming e le chiamate agli strumenti, e scopri come provider compatibili con OpenAI come Kimi API possono supportare uno sviluppo flessibile di applicazioni IA.

9 min di letturaAggiornato: 2026-11-14

Prova Kimi API

Flusso di richiesta e risposta dell'API Chat Completion

Che tu stia sviluppando un chatbot IA o aggiungendo funzionalità conversazionali a un'applicazione, è importante capire come l'IA gestisce le conversazioni. L'API Chat Completion lo rende possibile collegando le applicazioni ai modelli IA per generare risposte pertinenti e simili a quelle umane. Grazie a funzionalità come l'integrazione con Python, lo streaming e le chiamate agli strumenti, gli sviluppatori possono creare applicazioni più interattive. Vediamo come funziona, come utilizzarla e in che modo provider come Kimi API supportano uno sviluppo flessibile con l'IA.

Che cos'è l'API Chat Completions

L'API Chat Completions è un'interfaccia che consente alle applicazioni di inviare una sequenza di messaggi a un modello IA e ricevere una risposta dell'assistente, supportando conversazioni sia a turno singolo sia a più turni. Ad esempio, puoi usare Kimi K3.1 Pro per rispondere a una domanda sui decorator Python e poi porre una domanda di approfondimento:

Prima richiesta: invia il messaggio dell'utente: "Che cos'è un decorator Python?" Kimi restituisce un messaggio dell'assistente che spiega il concetto.
Seconda richiesta: per continuare la conversazione, invia il precedente messaggio dell'utente, il messaggio completo dell'assistente di Kimi e un nuovo messaggio dell'utente: "Puoi farmi un esempio?"

L'array messages contiene il contesto necessario per ogni richiesta. Tre scelte progettuali chiave rendono questa interfaccia ampiamente adottata:

Cronologia gestita dall'applicazione: le applicazioni gestiscono la cronologia della conversazione e includono il contesto pertinente in ogni richiesta, dando agli sviluppatori il controllo su ciò che il modello vede.
Ruoli dei messaggi più comuni: tra i ruoli comuni figurano system (istruzioni), user (input), assistant (output del modello, riproposto per il contesto multi-turno) e tool (risultati delle chiamate di funzione). Insieme, consentono di esprimere istruzioni, dialoghi e interazioni con gli strumenti.
Funzionalità flessibili: in base al supporto del modello, l'interfaccia può gestire lo streaming, le chiamate di strumenti, gli input visivi e gli output strutturati. Kimi K3.1 Pro supporta queste funzionalità.

Come usare l'API Chat Completions con Kimi

Gli esempi seguenti usano Kimi K3.1 Pro e l'SDK Python di OpenAI per mostrare come configurare il client, inviare richieste, gestire le risposte e implementare le chiamate di strumenti:

Guida rapida: chiamare Kimi con l'SDK Python di OpenAI

Installa l'SDK Python di OpenAI:

pip install --upgrade openai

Imposta la tua chiave Kimi API come variabile d'ambiente:

export MOONSHOT_API_KEY="sk-your-kimi-key"

Non ti serve una chiave OpenAI API. L'SDK Python di OpenAI funge da libreria client, mentre la tua chiave Kimi API e l'URL di base autenticano e instradano le richieste a Kimi.

Inizializza il client e invia la tua prima richiesta:

import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1", ) resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Explain REST in one paragraph."} ], ) print(resp.choices[0].message.content)

Questo esempio usa l'endpoint API internazionale di Kimi. Per la configurazione ufficiale e i dettagli del modello, consulta la guida rapida di Kimi K3.1 Pro.

Parametri principali

Questi parametri includono le principali opzioni disponibili quando chiami Kimi K3.1 Pro tramite l'API Chat Completions:

Parametro	Scopo
`model`	Specifica l'ID del modello, ad esempio `kimi-k3.1-pro`.
`messages`	Fornisce i messaggi della conversazione, inclusi gli input precedenti dell'utente e le risposte dell'assistente. Supporta contenuti testuali e multimodali.
`reasoning_effort`	Controlla la profondità del ragionamento. Accetta `low`, `high` o `max` (predefinito).
`max_completion_tokens`	Imposta il budget massimo di generazione, inclusi sia i token di ragionamento sia quelli della risposta finale. I token di input vengono conteggiati separatamente, ma il totale dei token di input e generati deve rientrare nella finestra di contesto del modello.
`stream`	Impostalo su `true` per ricevere la risposta in modo incrementale, anziché attendere l'output completo.
`tools`	Definisce le funzioni che il modello può richiedere all'applicazione di eseguire.
`response_format`	Controlla la formattazione dell'output. Supporta `json_object` per la modalità JSON e `json_schema` per un output strutturato vincolato da schema.

Nota: Kimi K3.1 Pro utilizza impostazioni di campionamento fisse. Non aggiungere temperature o top_p alle richieste. Per i dettagli sui parametri e i valori supportati, consulta il riferimento dell'API Chat Completions.

Leggere la risposta

Dopo una richiesta riuscita, puoi accedere ai principali campi della risposta tramite l'oggetto di completamento restituito:

choices[0].message – Contiene la risposta dell'assistente, inclusi content o tool_calls quando il modello richiede una funzione.
choices[0].finish_reason – Indica il motivo per cui la generazione si è interrotta, ad esempio stop, length o tool_calls.
usage – Fornisce informazioni sull'utilizzo dei token, inclusi i conteggi dei token di input, output e memorizzati nella cache, quando disponibili.

Per una risposta testuale di base, leggi choices[0].message.content. Se il modello restituisce tool_calls, la tua applicazione deve eseguire le funzioni richieste e inviarne i risultati in una richiesta successiva

Esempio di streaming

Imposta stream=True per ricevere la risposta di Kimi in blocchi incrementali. L'esempio seguente riutilizza il client configurato sopra e stampa la risposta finale man mano che arriva:

stream = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Write a haiku about autumn."} ], stream=True, ) for chunk in stream: if not chunk.choices: continue delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True)

Kimi K3.1 Pro restituisce il contenuto del ragionamento separatamente dalla risposta finale. Questo esempio stampa solo delta.content, quindi visualizza la risposta finale senza elaborare il campo reasoning_content separato.

Le chiamate di strumenti in breve

Le chiamate di strumenti consentono a Kimi di richiedere funzioni esterne quando un'attività richiede informazioni o azioni che vanno oltre la risposta del modello. Ad esempio, se un utente chiede: "Devo portare un ombrello a Tokyo oggi?", Kimi può richiedere una funzione get_weather per recuperare le previsioni.

Il flusso di lavoro prevede tre passaggi:

Dichiara la funzione: definisci get_weather e gli argomenti previsti nel parametro tools.
Esegui lo strumento: Kimi restituisce una voce tool_calls con il nome della funzione e gli argomenti. La tua applicazione esegue la funzione corrispondente e recupera i dati meteorologici.
Invia il risultato: aggiungi alla conversazione il messaggio completo dell'assistente di Kimi e il risultato dello strumento (utilizzando il tool_call_id corrispondente), quindi chiama di nuovo Kimi per generare una risposta destinata all'utente.

L'esempio seguente riutilizza il client configurato sopra. Prima di eseguirlo, assicurati di aver implementato una funzione get_weather(city) che restituisca dati meteorologici serializzabili in JSON. La funzione viene eseguita dalla tua applicazione, non da Kimi.

import json tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get the weather forecast for a city.", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } } ] messages = [ {"role": "user", "content": "Should I bring an umbrella in Tokyo today?"} ] # Ask Kimi whether it needs to call a tool resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) assistant_message = resp.choices[0].message # Preserve the complete assistant message, including tool_calls messages.append(assistant_message) # Execute the requested function in your application for tool_call in assistant_message.tool_calls or []: if tool_call.function.name == "get_weather": args = json.loads(tool_call.function.arguments) # Call your own weather service or API weather_result = get_weather(city=args["city"]) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(weather_result) }) # Let Kimi interpret the tool result and answer the user final_resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) print(final_resp.choices[0].message.content)

Qui, get_weather() rappresenta una funzione implementata dalla tua applicazione, non una funzione eseguita direttamente da Kimi. Kimi decide quando richiederla e fornisce gli argomenti; la tua applicazione esegue l'operazione effettiva e restituisce il risultato.

In produzione, implementa un ciclo che elabori ogni chiamata di strumento, aggiunga i risultati corrispondenti alla conversazione e invii i messaggi aggiornati a Kimi. Ripeti questo ciclo finché il modello non restituisce una risposta finale senza richiedere strumenti aggiuntivi.

Perché la compatibilità con OpenAI conta nella scelta di un provider

Molti provider supportano il formato OpenAI Chat Completions, consentendo agli sviluppatori di riutilizzare SDK e strutture di richiesta già noti. Il passaggio richiede in genere di aggiornare l'URL di base, la chiave API e l'ID del modello, quindi di verificare i parametri supportati e la gestione delle risposte. Nel confrontare i provider, considera i seguenti fattori:

Fedeltà della compatibilità: verifica che lo streaming, le chiamate di strumenti, gli output strutturati e la segnalazione di usage funzionino come previsto dalla tua applicazione. La compatibilità con lo stesso formato API non garantisce supporto delle funzionalità o comportamento delle risposte identici tra i vari provider.
Qualità del modello per il tuo carico di lavoro: la combinazione di lingue e i tipi di attività sono più importanti dei benchmark generici.
Finestra di contesto: i modelli a contesto lungo possono semplificare alcuni flussi di lavoro sui documenti elaborando più materiale sorgente in un'unica richiesta.
Meccanismi di costo: la cache e gli sconti per l'elaborazione in batch spesso incidono più dei prezzi per token dichiarati.
Ampiezza dell'ecosistema: endpoint compatibili aggiuntivi, come Responses e Anthropic Messages, possono offrire più opzioni di integrazione e flessibilità con l'evoluzione della tua applicazione.

Kimi API: un provider compatibile con OpenAI da prendere in considerazione

Kimi API, sviluppata da Moonshot AI, merita di essere presa in considerazione se cerchi un provider compatibile con OpenAI, in particolare per applicazioni in lingua cinese, l'elaborazione di documenti lunghi e gli agenti di coding. Combina schemi di integrazione API familiari con le capacità di contesto lungo e ragionamento di Kimi.

Compatibile senza modifiche

Se la tua applicazione utilizza già l'SDK Python di OpenAI, puoi integrare Kimi senza riscrivere l'intero flusso di richieste. Ti basta aggiornare la configurazione dell'API, inclusi base_url, api_key e l'ID del modello, mantenendo la familiare interfaccia Chat Completions.

Ad esempio, il codice seguente legge un report locale da report.txt, ne invia il contenuto a Kimi K3.1 Pro per generare un riepilogo e trasmette in streaming la risposta generata:

from pathlib import Path report_text = Path("report.txt").read_text(encoding="utf-8") resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ { "role": "user", "content": f"Summarize the following report:\n\n{report_text}" } ], stream=True, ) for chunk in resp: if not chunk.choices: continue content = chunk.choices[0].delta.content if content: print(content, end="", flush=True)

Qui, client riutilizza il client Kimi inizializzato in precedenza con la tua chiave API letta da una variabile d'ambiente. Scegli l'URL di base in base alla tua regione: https://api.moonshot.ai/v1 per la piattaforma internazionale oppure https://api.moonshot.cn/v1 per gli utenti che accedono all'API dalla Cina continentale.

Questo approccio ti consente di mantenere il flusso di lavoro esistente con l'SDK OpenAI e di usare i modelli Kimi per attività come il riepilogo di documenti e altre applicazioni basate su API.

Cosa distingue Kimi

Un modello di punta con una finestra di contesto di 1M token: Kimi K3.1 Pro supporta una finestra di contesto fino a 1M token e la comprensione visiva nativa. Gli sviluppatori possono lavorare con codebase estese, documenti lunghi quanto un libro e input di immagini in un unico flusso di lavoro, rendendolo adatto al ragionamento complesso, alla programmazione e alle applicazioni multimodali.
Ottimizzazione flessibile dei costi: Kimi API supporta la cache automatica del contesto per i prefissi di richieste ripetuti e l'inferenza Batch API per attività su larga scala che non richiedono risposte in tempo reale. La fatturazione della cache e i prezzi Batch dipendono dal modello e dalle regole tariffarie applicabili. Consulta i prezzi ufficiali di Kimi API per le tariffe attuali e i dettagli di fatturazione.
Compatibilità tra ecosistemi API: Kimi offre endpoint Chat Completions e Responses API compatibili con OpenAI, nonché un endpoint compatibile con Anthropic Messages. Gli sviluppatori possono integrare Kimi K3.1 Pro nei flussi di lavoro esistenti usando SDK e formati API familiari, con gli adeguamenti necessari in base all'endpoint e alle funzionalità supportate.

Conclusione

Iniziare a usare l'API Chat Completions è semplice: configura le tue credenziali API, invia una richiesta e leggi la risposta generata da choices[0].message.content. Quando la prima chiamata API funziona, puoi ampliare l'integrazione in base alle esigenze della tua applicazione aggiungendo conversazioni a più turni, risposte in streaming o chiamate di strumenti. Pronto a sviluppare con Kimi? Ottieni la tua chiave Kimi API e inizia a effettuare richieste API.

Prova Kimi API

Domande frequenti

No. L'API Chat Completions non è riservata ai modelli OpenAI. Altri provider di IA, tra cui Kimi, offrono API che seguono il formato Chat Completions compatibile con OpenAI. Questo consente agli sviluppatori di riutilizzare SDK e strutture di richiesta familiari con modelli supportati di provider diversi, anche se il supporto delle funzionalità può variare.

Entrambe le API consentono alle applicazioni di interagire con modelli IA, ma utilizzano strutture di richiesta e risposta diverse. Chat Completions usa un array messages e restituisce risposte tramite un array choices. La Responses API utilizza una struttura di input e output più flessibile, che supporta diversi tipi di contenuto e interazioni con gli strumenti. La gestione dello stato della conversazione varia in base al provider. Con la Responses API di Kimi, le applicazioni devono includere la cronologia della conversazione pertinente in ogni richiesta, anziché affidarsi al concatenamento tramite ID della risposta.

Se la tua applicazione usa l'SDK OpenAI, in genere puoi passare a Kimi aggiornando tre valori di configurazione: base_url con l'endpoint API di Kimi, api_key con la tua chiave Kimi API e model con un ID di modello Kimi supportato. Quindi, testa l'integrazione per verificare che i parametri e le funzionalità su cui si basa la tua applicazione, come lo streaming e le chiamate agli strumenti, siano supportati.