> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Kimi Chat Completion API richiesta e utilizzo > Kimi API guide - Ace Data Cloud Kimi è una serie di modelli AI lanciata da Moonshot. L'attuale modello raccomandato `kimi-k3` è orientato alla programmazione a lungo termine, agli agenti, al ragionamento complesso e al lavoro di conoscenza, ed è accessibile tramite l'API Chat Completions compatibile con OpenAI. Questo documento descrive principalmente il processo di utilizzo dell'API Kimi Chat Completion, che ci consente di utilizzare facilmente le funzionalità di conversazione ufficiali di Kimi. ## Processo di richiesta Per utilizzare l'API Kimi Chat Completion, prima di tutto vai al [Pannello di controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. **Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio.** La prima richiesta offre un credito gratuito, che consente di provare senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [Kimi Chat Completion API →](https://platform.acedata.cloud/documents/kimi-chat-completions) ## Utilizzo di base Ora puoi compilare i contenuti corrispondenti nell'interfaccia, come mostrato nell'immagine:

Quando utilizzi questa interfaccia per la prima volta, è necessario compilare almeno tre contenuti: `authorization` può essere selezionato direttamente dall'elenco a discesa; `model` serve a scegliere il modello Kimi, si consiglia di utilizzare `kimi-k3`; `messages` è un array di messaggi di conversazione, ogni messaggio contiene `role` e `content`, dove `role` supporta `user`, `assistant`, `system` e `tool`. Puoi anche notare che a destra c'è un codice di chiamata corrispondente generato, puoi copiare il codice e eseguirlo direttamente, oppure cliccare direttamente sul pulsante "Try" per testare.

Di seguito è riportata una risposta reale di K3 ottenuta utilizzando `reasoning_effort: max` (sono stati omessi i campi di estensione non utilizzati): ```json theme={null} { "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA", "object": "chat.completion", "created": 1784466588, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Ciao! Come posso aiutarti oggi?" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 86, "completion_tokens": 206, "total_tokens": 292 } } ``` Il risultato restituito contiene diversi campi, descritti come segue: * `id`, l'ID generato per questo compito di conversazione, utilizzato per identificare univocamente questo compito di conversazione. * `model`, il modello Kimi scelto dal sito ufficiale. * `choices`, le informazioni di risposta fornite da Kimi in base alla domanda. * `usage`: informazioni statistiche sui token per questo scambio di domande e risposte. Tra cui `choices` contiene le informazioni di risposta di Kimi, e all'interno di `choices` ci sono le informazioni specifiche della risposta di Kimi, come mostrato nell'immagine.

Si può vedere che il campo `content` all'interno di `choices` contiene il contenuto specifico della risposta di Kimi; K3 potrebbe anche restituire `reasoning_content`, utilizzato per rappresentare il processo di ragionamento. ## Intensità di ragionamento di K3 `kimi-k3` ha sempre il ragionamento attivato. Il corpo della richiesta supporta il campo `reasoning_effort` a livello superiore, l'unico valore attualmente supportato è `max`; omettendo questo campo si utilizza comunque `max`. `standard`, `high` o altre stringhe potrebbero essere parzialmente accettate da upstream in modo flessibile, ma non garantiscono di modificare il comportamento del ragionamento, non fare affidamento su di esse. ```bash theme={null} curl https://api.acedata.cloud/kimi/chat/completions \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "kimi-k3", "messages": [{"role": "user", "content": "Esamina questo codice e fornisci una soluzione di riparazione"}], "reasoning_effort": "max" }' ``` Utilizzando l'SDK di OpenAI, puoi passare direttamente questo campo: ```python theme={null} response = client.chat.completions.create( model="kimi-k3", messages=[{"role": "user", "content": "Progetta una coda di attività affidabile"}], reasoning_effort="max", ) ``` Durante le conversazioni a più turni e le chiamate agli strumenti, assicurati di restituire il messaggio completo dell'assistente dell'ultimo turno a `messages`, inclusi `reasoning_content` e `tool_calls`. ### Riferimenti ufficiali * [Thinking Effort](https://platform.kimi.ai/docs/guide/use-thinking-effort): spiega che Kimi K3 ha sempre il ragionamento attivato, l'unico valore attualmente supportato per `reasoning_effort` è `max`. * [Model Parameter Reference](https://platform.kimi.ai/docs/api/models-overview): confronta i parametri di ragionamento, la finestra di contesto e le differenze nelle chiamate agli strumenti tra K3 e la serie K2. * [Create Chat Completion](https://platform.kimi.ai/docs/api/chat): richieste, risposte e definizioni dei campi OpenAPI ufficiali di Moonshot Chat Completions. ## Risposta in streaming Questa interfaccia supporta anche le risposte in streaming, il che è molto utile per l'integrazione web, consentendo di visualizzare il testo parola per parola. Se desideri restituire la risposta in streaming, puoi modificare il parametro `stream` nell'intestazione della richiesta, impostandolo su `true`. La modifica è mostrata nell'immagine, ma il codice di chiamata deve avere le modifiche corrispondenti per supportare la risposta in streaming.

Dopo aver modificato `stream` in `true`, l'API restituirà i dati JSON riga per riga, e a livello di codice dobbiamo apportare le modifiche necessarie per ottenere i risultati riga per riga. Esempio di codice di chiamata in Python: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"user","content":"Ciao"}], "reasoning_effort": "max", "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Di seguito è riportato un estratto dei blocchi di dati di avvio, ragionamento, corpo, fine e utilizzo da una risposta in streaming reale di K3 Max: ```json theme={null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"reasoning_content":"Il"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"Ciao"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[],"usage":{"prompt_tokens":172,"completion_tokens":168,"total_tokens":340}} data: [DONE] ``` Puoi vedere che ci sono molti `data` nella risposta, e `data` contiene il `choices` che è il contenuto della risposta più recente, coerente con quanto descritto in precedenza. `choices` è il contenuto della risposta aggiuntiva, puoi integrarlo nel tuo sistema in base ai risultati. Inoltre, la fine della risposta in streaming è determinata dal contenuto di `data`, se il contenuto è `[DONE]`, significa che la risposta in streaming è completamente terminata. I risultati di `data` restituiti hanno diversi campi, descritti come segue: * `id`, l'ID generato per questo compito di conversazione, utilizzato per identificare univocamente questo compito di conversazione. * `model`, il modello scelto dal sito ufficiale di Kimi. * `choices`, le informazioni di risposta fornite da Kimi in base alla domanda. JavaScript è supportato, ad esempio, il codice di chiamata in streaming per Node.js è il seguente: ```javascript theme={null} const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "kimi-k3", "messages": [{"role":"user","content":"Ciao"}], "stream": true }) }; fetch("https://api.acedata.cloud/kimi/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` Esempio di codice Java: ```java theme={null} JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "kimi-k3"); jsonObject.put("messages", [{"role":"user","content":"Ciao"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/kimi/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Altre lingue possono essere modificate di conseguenza, il principio è lo stesso. ## Conversazione multipla Se desideri integrare la funzionalità di conversazione multipla, devi caricare più domande nel campo `messages`, un esempio specifico di più domande è mostrato nell'immagine qui sotto:

Esempio di codice Python: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"assistant","content":"Ciao! Come posso aiutarti oggi?"},{"role":"user","content":"Quale modello sei?"}], "reasoning_effort": "max" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Caricando più domande, puoi facilmente realizzare conversazioni multiple. Di seguito è riportata la risposta reale ottenuta da K3 Max per questa richiesta (i campi di estensione non utilizzati sono omessi): ```json theme={null} { "id": "msg_Rqp8nPGBDHWwBlL4VpxuafOp", "object": "chat.completion", "created": 1784466628, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Sono Kimi, un assistente AI sviluppato da Moonshot AI (月之暗面). Non ho un identificatore di versione del modello pubblico specifico da condividere da qui." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 134, "completion_tokens": 346, "total_tokens": 480 } } ``` Puoi vedere che le informazioni contenute in `choices` sono coerenti con il contenuto di base utilizzato, questo include il contenuto specifico della risposta di Kimi a più conversazioni, in modo da poter rispondere alle domande corrispondenti in base ai contenuti delle conversazioni multiple. ## Gestione degli errori Quando chiami l'API, se incontri un errore, l'API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio: * `400 token_mismatched`: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. * `400 api_not_implemented`: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. * `401 invalid_token`: Non autorizzato, token di autorizzazione non valido o mancante. * `429 too_many_requests`: Troppe richieste, hai superato il limite di frequenza. * `500 api_error`: Errore interno del server, qualcosa è andato storto sul server. ### Esempio di risposta di errore ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusione Attraverso questo documento, hai compreso come utilizzare l'API Kimi Chat Completion per realizzare conversazioni normali, risposte in streaming, conversazioni multiple, e come controllare l'intensità di ragionamento di K3 tramite `reasoning_effort`.