Richiesta e utilizzo della Claude Chat Completion API

Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. Claude si distingue nel settore per le sue eccellenti capacità di comprensione e generazione del linguaggio; oggi Claude è già ampiamente utilizzato in vari settori e ambiti, e la sua influenza è sempre più significativa. Che si tratti di conversazioni quotidiane, scrittura creativa, consulenza professionale o programmazione di codice, Claude può fornire un’assistenza intelligente sorprendente, migliorando notevolmente l’efficienza lavorativa e la creatività umana. Questo documento presenta principalmente il flusso di utilizzo delle operazioni della Claude Chat Completion API; utilizzandola possiamo facilmente usufruire delle funzionalità di conversazione di Claude ufficiale.

Procedura di richiesta

Per utilizzare la Claude Chat Completion API, per prima cosa vai alla console Ace Data Cloud per ottenere il tuo API Token, da conservare come riserva.

Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso che ti inviterà a registrarti ed effettuare l’accesso; al termine tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza dover fare richiesta separatamente per ciascun servizio. Alla prima richiesta verrà assegnato un credito gratuito, che consente di provare il servizio gratuitamente; quando il credito è insufficiente, puoi ricaricare il saldo generico nella console.

📘 Documentazione completa: Claude Chat Completion API →

Utilizzo di base

Successivamente puoi compilare i contenuti corrispondenti nell’interfaccia, come mostrato nell’immagine:

Quando utilizzi questa interfaccia per la prima volta, dobbiamo compilare almeno tre contenuti: uno è authorization, che può essere selezionato direttamente nell’elenco a discesa. Un altro parametro è model, per il quale si consiglia di utilizzare l’ultimo modello di punta claude-fable-5-1; il precedente claude-fable-5 può comunque continuare a essere chiamato. L’ultimo parametro è messages, che è un array di prompt; ogni elemento contiene role e content; role supporta user, assistant, system, mentre content è il contenuto specifico. Claude Fable 5.1 supporta un contesto di 1 milione di Token e un output massimo di 128K Token. Allo stesso tempo puoi notare che sulla destra è presente la generazione del codice di chiamata corrispondente; puoi copiare il codice ed eseguirlo direttamente, oppure fare clic direttamente sul pulsante «Try» per effettuare un test. Parametri opzionali comuni:

max_tokens: limita il numero massimo di token per una singola risposta.
temperature: casualità della generazione, tra 0 e 2; maggiore è il valore, più divergente sarà.
n: quante risposte candidate generare in una volta.
response_format: impostazione del formato di ritorno.

Dopo la chiamata, scopriamo che il risultato restituito è il seguente:

{
  "id": "msg_bdrk_01Q6WN27v95ypCa1kbanAQ6K",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "created": 1768619365,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

Il risultato restituito contiene diversi campi, descritti come segue:

id, l’ID generato per questa attività di conversazione, utilizzato per identificare univocamente questa attività di conversazione.
model , il modello del sito ufficiale Claude selezionato.
choices, le informazioni di risposta fornite da Claude al prompt.
usage : informazioni statistiche sui token per questa sessione di domande e risposte.

Nel formato Chat Completions, usage.prompt_tokens è il totale dell’input; prompt_tokens_details.cached_tokens e prompt_tokens_details.cache_write_tokens registrano rispettivamente i dettagli di lettura e scrittura della cache. completion_tokens_details.reasoning_tokens è un sottoinsieme di completion_tokens; quando si calcola il totale o il costo, non aggiungerlo nuovamente. Le risposte non in streaming possono anche restituire l’oggetto usage.cost, dove amount è il consumo effettivo di credito, currency è l’unità di misura e list_amount è l’importo prima dello sconto (se presente). Il nome del campo compatibile con Chat è reasoning_tokens; la Messages API nativa utilizza output_tokens_details.thinking_tokens. Lo schema wire dei due protocolli è diverso e il client non deve mescolare i nomi dei campi. Tra questi, choices contiene le informazioni di risposta di Claude; il suo choices contiene le informazioni specifiche della risposta di Claude, come si può vedere nell’immagine.

Si può vedere che il campo content in choices contiene il contenuto specifico della risposta di Claude.

Risposta in streaming

Questa interfaccia supporta anche risposte in streaming, il che è molto utile per l’integrazione web e permette alla pagina web di ottenere un effetto di visualizzazione parola per parola. Se desideri restituire la risposta in streaming, puoi modificare il parametro stream nell’header della richiesta, impostandolo su true. La modifica è mostrata nell’immagine; tuttavia, il codice di chiamata deve essere modificato di conseguenza per supportare la risposta in streaming.

Dopo aver modificato stream in true, l’API restituirà riga per riga i dati JSON corrispondenti; a livello di codice dobbiamo apportare le modifiche corrispondenti per ottenere i risultati riga per riga. Codice di esempio di chiamata Python:

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-opus-4-20250514",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

L’effetto dell’output è il seguente:

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": ""}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "Hello!"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " How can I help you"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " today?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20, "prompt_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 0}}}

data: [DONE]

Si può vedere che nella risposta sono presenti molti data; i choices all’interno di data rappresentano il contenuto più recente della risposta, coerente con quanto descritto sopra. choices contiene il nuovo contenuto della risposta e puoi integrarlo nel tuo sistema in base al risultato. Allo stesso tempo, la fine della risposta in streaming viene determinata in base al contenuto di data: se il contenuto è [DONE], significa che la risposta in streaming è completamente terminata. Il risultato data restituito contiene più campi, descritti di seguito:

id, l’ID dell’attività di conversazione generata, utilizzato per identificare univocamente questa attività di conversazione.
model , il modello Claude selezionato sul sito ufficiale.
choices, le informazioni di risposta fornite da Claude alla parola della domanda.

Anche JavaScript è supportato; ad esempio, il codice di chiamata in streaming per Node.js è il seguente:

const options = {
  method: "post",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-opus-4-20250514",
    messages: [{ role: "user", content: "Hello" }],
    stream: true,
  }),
};

fetch("https://api.acedata.cloud/v1/chat/completions", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

Codice di esempio Java:

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "claude-opus-4-20250514");
jsonObject.put("messages", [{"role":"user","content":"Hello"}]);
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/v1/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())

Gli altri linguaggi possono essere adattati autonomamente; il principio è lo stesso.

Conversazione multi-turno

Se desideri integrare la funzionalità di conversazione multi-turno, devi caricare più parole della domanda nel campo messages; un esempio specifico di più parole della domanda è mostrato nella figura seguente:

Codice di esempio di chiamata Python:

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-opus-4-20250514",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello! How can I help you today?"},{"role":"user","content":"What I say just now?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Caricando più parole della domanda, è possibile realizzare facilmente una conversazione multi-turno e ottenere la seguente risposta:

{
  "id": "msg_bdrk_01Y1wfQmd89g968TVbFu57Yc",
  "model": "claude-opus-4-20250514",
  "object": "chat.completion",
  "created": 1768619674,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You said \"Hello\" - that was your first message to me in our conversation."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 20,
    "total_tokens": 49,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

Si può vedere che le informazioni contenute in choices sono coerenti con il contenuto dell’uso di base; questo include il contenuto specifico delle risposte di Claude a più conversazioni, così è possibile rispondere alle domande corrispondenti in base a più contenuti di conversazione.

Ragionamento approfondito

I modelli Claude di nuova generazione potrebbero effettuare il ragionamento secondo la strategia predefinita del modello, senza necessità di attivarlo tramite il suffisso del modello -thinking. Le risposte compatibili con Chat utilizzano il campo usage compatibile con OpenAI completion_tokens_details.reasoning_tokens. reasoning_tokens è già incluso in completion_tokens, non sommarlo nuovamente. Il ragionamento e il testo visibile condividono il limite massimo dei token di output, pertanto quando max_tokens è ridotto il testo potrebbe risultare vuoto o troncato; in tal caso aumenta il budget di output oppure, se il modello utilizzato lo supporta, seleziona un minore impegno di ragionamento. Se sono necessari thinking nativo, output_config.effort, blocchi di contenuto thinking e la restituzione della firma, utilizza /v1/messages. Il campo usage corrispondente a Messages è output_tokens_details.thinking_tokens, non confonderlo con completion_tokens_details.reasoning_tokens di Chat-compatible.

Modello visivo

claude-sonnet-4-20250514 è un modello linguistico di grandi dimensioni multimodale sviluppato da Claude, che aggiunge capacità di comprensione visiva sulla base di claude-4. Questo modello può elaborare contemporaneamente input di testo e immagini, realizzando comprensione e generazione multimodali. L’elaborazione del testo utilizzando il modello claude-sonnet-4-20250514 è coerente con i contenuti di utilizzo di base descritti sopra; di seguito verrà brevemente illustrato come utilizzare la capacità di elaborazione delle immagini del modello. La capacità di elaborazione delle immagini del modello claude-sonnet-4-20250514 viene utilizzata principalmente aggiungendo un campo type al contenuto content originale; tramite questo campo è possibile sapere se ciò che viene caricato è testo o un’immagine, utilizzando così la capacità di elaborazione delle immagini del modello claude-sonnet-4-20250514. Di seguito verranno principalmente descritti due modi per richiamare questa funzionalità, tramite Curl e Python.

Metodo script Curl

curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What'\''s in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          }
        ]
      }
    ]
  }'

Metodo script Python

import requests

url = "https://api.acedata.cloud/v1/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text", "text": "What's in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
            ],
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Quindi è possibile ottenere il risultato seguente; le informazioni dei campi nel risultato sono coerenti con quanto sopra, nello specifico:

{
  "id": "msg_bdrk_01NCrxpZmV17bhQJJRQEFEb9",
  "model": "claude-sonnet-4-20250514",
  "object": "chat.completion",
  "created": 1768628904,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "This image shows an API request configuration interface for what appears to be an AI chat completion service. Here are the key elements:\n\n**Request Body Parameters:**\n\n1. **model** (required string) - Set to \"claude-opus-4-202505...\" - specifies which AI model to use\n\n2. **messages** (required array) - Contains the conversation history with:\n   - **role** (required string) - Set to \"user\" \n   - **content** (required string) - Contains \"Hello\" as the message content\n\n3. **stream** (boolean) - Set to \"true\" - enables partial message deltas like in ChatGPT\n\n4. **max_tokens** (number) - Field for setting maximum tokens that can be generated in the response\n\n5. **n** (number) - Specifies how many chat completion choices to generate for each input\n\nThe interface has a dark theme with white text on black/dark gray backgrounds. There's a \"Fill Example\" button at the bottom right and various dropdown menus and input fields for configuring the API request parameters. A red trash/delete icon is visible, likely for removing message entries."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1570,
    "completion_tokens": 252,
    "total_tokens": 1822,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

Si può vedere che il contenuto della risposta si basa sull’immagine; pertanto, tramite i due metodi sopra indicati, è possibile utilizzare facilmente le capacità di elaborazione del testo e delle immagini del modello claude-3-7-sonnet-20250219.

Gestione degli errori

Durante la chiamata dell’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore 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, si è verificato un problema 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 già compreso come utilizzare Claude Chat Completion API per implementare facilmente la funzionalità di conversazione ufficiale di Claude. Ci auguriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Richiesta e utilizzo della Claude Chat Completion API

Procedura di richiesta

Utilizzo di base

Risposta in streaming

Conversazione multi-turno

Ragionamento approfondito

Modello visivo

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di richiesta

​Utilizzo di base

​Risposta in streaming

​Conversazione multi-turno

​Ragionamento approfondito

​Modello visivo

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di richiesta

Utilizzo di base

Risposta in streaming

Conversazione multi-turno

Ragionamento approfondito

Modello visivo

Gestione degli errori

Esempio di risposta di errore

Conclusione