Richiesta e utilizzo della Claude Messages API

Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. La Claude Messages API è il formato API nativo ufficiale di Anthropic; diversamente dal formato compatibile con OpenAI (Chat Completion), adotta una struttura di richiesta e risposta proprietaria di Anthropic, consentendo di sfruttare meglio le capacità uniche di Claude, come l’input di contenuti multimodali, la chiamata di strumenti, il ragionamento approfondito (Extended Thinking) e altre funzionalità avanzate. Questo documento presenta principalmente il flusso di utilizzo delle operazioni della Claude Messages API. Usandola, possiamo utilizzare un’interfaccia nativa coerente con quella ufficiale di Anthropic per richiamare le funzionalità di conversazione di Claude.

Processo di richiesta

Per utilizzare la Claude Messages API, innanzitutto vai alla console di Ace Data Cloud per ottenere il tuo API Token e conservarlo come riserva.

Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per registrarti ed effettuare l’accesso; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token consente di richiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio. La prima richiesta include un credito gratuito, per consentire una prova gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale nella console.

📘 Documentazione completa: Claude Messages API →

Utilizzo di base

Il percorso di richiesta della Claude Messages API è /v1/messages, coerente con l’API ufficiale di Anthropic. Dobbiamo fornire almeno tre parametri obbligatori:

model: seleziona il modello Claude da utilizzare. claude-opus-5-5 è disponibile solo tramite Messages API, supporta un contesto di 1 milione di Token, un output massimo di 128K Token e abilita sempre il ragionamento adattivo. Il più recente modello di punta è claude-fable-5-1 (contesto di 1 milione di Token, output massimo di 128K Token); il precedente claude-fable-5 rimane compatibile e disponibile. claude-sonnet-5-5 è stato aggiunto alla serie di interfacce native Messages, supporta l’input di immagini e il ragionamento adattivo; i suoi prezzi di riferimento ufficiali per input, output e lettura della cache sono rispettivamente 2, 10 e 0,20 dollari per milione di Token.
messages: array dei messaggi in input; ogni messaggio contiene role (ruolo) e content (contenuto), dove role supporta user e assistant.
max_tokens: numero massimo di token in output, utilizzato per limitare la lunghezza di una singola risposta.

Parametri opzionali comuni:

system: prompt di sistema, utilizzato per impostare il comportamento e il ruolo del modello.
temperature: casualità della generazione, compresa tra 0 e 1; maggiore è il valore, più divergente sarà la risposta.
stream: se utilizzare la risposta in streaming; impostandolo su true è possibile ottenere un effetto di restituzione carattere per carattere.
stop_sequences: sequenze di arresto personalizzate; il modello smetterà di generare quando incontrerà questi testi.
top_p: parametro di campionamento del nucleo, utilizzato con temperature per controllare la casualità della generazione.
top_k: campiona solo tra le K opzioni con probabilità più alta.
tools: definizioni degli strumenti, utilizzate per consentire al modello di chiamare funzioni esterne.
tool_choice: controlla come il modello utilizza gli strumenti forniti.
cache_control: crea automaticamente un punto di interruzione della cache nell’ultimo blocco di contenuto memorizzabile nella cache della richiesta; può anche essere scritto nel blocco di contenuto specifico.

Esempio cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Esempio Python

import requests

url = "https://api.acedata.cloud/v1/messages"

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

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

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

Dopo la chiamata, il risultato restituito è il seguente:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Descrizione dei campi del risultato restituito:

id: identificatore univoco di questo messaggio.
type: sempre message.
role: sempre assistant.
content: array dei contenuti della risposta; ogni elemento contiene type (ad esempio text) e il contenuto corrispondente.
model: nome del modello che elabora la richiesta.
stop_reason: motivo dell’arresto. I valori stabili includono end_turn, max_tokens, stop_sequence, tool_use, pause_turn (puoi ritrasmettere invariato il contenuto corrente dell’assistant per continuare), refusal e model_context_window_exceeded.
stop_sequence: se l’arresto avviene a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente.
stop_details: quando stop_reason è refusal, può contenere la categoria e la descrizione del rifiuto.
usage: statistiche sull’utilizzo dei token. input_tokens è l’input non memorizzato nella cache; cache_creation_input_tokens e cache_read_input_tokens sono rispettivamente la scrittura e la lettura della cache; output_tokens è il numero totale di token in output. Se viene restituito output_tokens_details.thinking_tokens, questo valore è un sottoinsieme di output_tokens; non sommarlo nuovamente quando si calcola il totale o il costo. Questo dettaglio può essere null o omesso quando non è disponibile un conteggio autorevole.
usage.cache_creation: dettaglio opzionale del TTL di scrittura della cache, contenente ephemeral_5m_input_tokens e ephemeral_1h_input_tokens. Quando l’oggetto è presente, la somma dei due elementi è uguale a cache_creation_input_tokens; un campo null o omesso indica che la risposta corrente non dispone di una suddivisione TTL utilizzabile e non può essere interpretato come 0.
usage.cost: le risposte non in streaming possono contenere l’oggetto di consumo del credito registrato da Ace Data Cloud, dove amount è il consumo effettivo di questa richiesta, currency è l’unità di misura e list_amount è l’importo prima dello sconto (se presente). Il prezzo base ufficiale per la lettura della cache di Fable 5.1 è di $0,25/milione di Token, mentre i prezzi base per la scrittura della cache di 5 minuti e di 1 ora sono rispettivamente $12,50 e $20/milione di Token; il prezzo effettivo della piattaforma viene calcolato in base allo sconto del piano.

Prompt di sistema

La Claude Messages API supporta l’impostazione del prompt di sistema tramite il campo system, utilizzato per definire il comportamento, il ruolo e il contesto del modello.

Esempio Python

import requests

url = "https://api.acedata.cloud/v1/messages"

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

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

Impostando il prompt system, è possibile controllare con precisione il ruolo e il comportamento di Claude.

Risposta in streaming

Questa interfaccia supporta anche le risposte in streaming: impostando il parametro stream su true è possibile ottenere un effetto di restituzione progressiva, particolarmente adatto per implementare la visualizzazione carattere per carattere nelle pagine web.

Esempio Python

import requests

url = "https://api.acedata.cloud/v1/messages"

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

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

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

La risposta in streaming viene restituita nel formato Server-Sent Events (SSE), con ogni riga preceduta da event: e data:. I tipi di eventi in streaming includono:

message_start: inizio del messaggio, include le informazioni di base del messaggio e il nome del modello.
content_block_start: inizio del blocco di contenuto.
content_block_delta: aggiornamento incrementale del blocco di contenuto, include il frammento di testo appena generato.
content_block_stop: fine del blocco di contenuto.
message_delta: aggiornamento incrementale a livello di messaggio, include stop_reason e le informazioni finali di usage. Il valore autorevole di output_tokens_details.thinking_tokens deve essere letto solo dall’ultimo message_delta.usage, senza accumularlo tra gli eventi.
message_stop: fine del messaggio.

L’effetto di output è il seguente:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Come si può vedere, nella risposta in streaming l’evento content_block_delta contiene il testo generato progressivamente; concatenando tutti i text_delta è possibile ottenere la risposta completa.

Esempio JavaScript

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

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Conversazione multi-turno

Se desiderate integrare la funzionalità di conversazione multi-turno, dovete disporre alternativamente i messaggi con ruolo user e assistant nell’array messages, trasmettendo insieme l’intera cronologia della conversazione precedente.

Esempio Python

import requests

url = "https://api.acedata.cloud/v1/messages"

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

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

Il risultato restituito è il seguente:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Passando l’intera cronologia della conversazione in messages, Claude può fornire risposte accurate tenendo conto del contesto.

Modello di ragionamento approfondito

Il thinking e il thinking summary di Claude sono due concetti diversi: il modello può eseguire un ragionamento interno, ma l’API non restituisce la catena di pensiero originale. Quando è necessario mostrare il processo di ragionamento, l’API restituisce un riepilogo elaborato. Per il modello attuale si consiglia di utilizzare l’adaptive thinking e di controllare l’impegno complessivo di ragionamento tramite output_config.effort:

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

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

Il blocco thinking nella risposta ha la seguente forma:

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" restituisce un riepilogo leggibile del ragionamento; non è la catena di pensiero originale.
display: "omitted" restituisce thinking: "", ma conserva comunque una signature opaca per supportare le conversazioni successive.
display: "updates" è la modalità beta di Anthropic e richiede anthropic-beta: thinking-display-updates-2026-08-18. La definizione ufficiale è nascondere il corpo del ragionamento e mostrare brevi aggiornamenti di avanzamento tra le chiamate agli strumenti. La piattaforma trasmette questo parametro e l’header beta ai valori originali e non lo riscrive forzatamente come summarized; il contenuto effettivo dell’output dipende dal supporto del modello selezionato.
thinking, output_config, effort, parametri di campionamento e nuovi campi estesi vengono trasmessi ai valori originali. La piattaforma non mantiene enumerazioni di valori codificate per modello, limitazioni di combinazione, né riscrive automaticamente la modalità thinking; se questi parametri siano accettati viene deciso dal modello selezionato, e gli errori di parametro restituiti dal modello vengono ritrasmessi al client.
Il valore predefinito di display per Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 è omitted; Opus 4.6, Sonnet 4.6 e i modelli precedenti che supportano thinking usano per impostazione predefinita summarized.
Display influisce solo sul contenuto restituito e sulla latenza dello streaming, non disabilita il ragionamento né riduce la fatturazione dei token thinking.
Se thinking sia abilitato per impostazione predefinita e il valore predefinito di display sono due questioni indipendenti. Opus 5 e Sonnet 5 abilitano per impostazione predefinita adaptive thinking; per Opus 5, omettere thinking equivale a adaptive, e omettere output_config.effort equivale a high. Opus 4.8, 4.7 e 4.6 richiedono un’abilitazione esplicita.
Thinking e il corpo finale condividono il budget di output max_tokens. Se il budget è troppo ridotto, thinking può consumare gran parte della quota, lasciando il corpo vuoto o troncato; aumentare max_tokens, oppure usare effort low / medium per controllare l’investimento nel ragionamento.
Per i modelli che consentono di disabilitare thinking, è possibile passare thinking: {"type":"disabled"}. Le nuove modalità come between_tools e le combinazioni di effort dipendono dal modello selezionato; la piattaforma non rifiuta in anticipo in base alle vecchie regole dei modelli.
Il budget di pensiero fisso può essere passato tramite budget_tokens; i nuovi modelli usano generalmente thinking.type=adaptive e output_config.effort. Se il budget fisso o la disabilitazione del pensiero siano supportati dipende dalle capacità attuali del modello selezionato.
Nelle conversazioni multi-turno e nelle chiamate agli strumenti, è necessario ritrasmettere invariati il blocco thinking completo e la signature restituiti dall’assistant; non modificare né generare autonomamente la signature.
La trasmissione dei parametri non significa che ogni modello supporti tutte le funzionalità. Le chiamate tra protocolli richiedono comunque conversione, e l’ambito di supporto e gli errori per contenuti come redacted_thinking sono determinati dal servizio del modello che effettivamente elabora la richiesta.

Nelle richieste in streaming, summarized produce thinking_delta; omitted non produce thinking_delta, mantenendo solo il ciclo di vita del blocco thinking e signature_delta.

Modelli visivi

Claude supporta input multimodali e può elaborare simultaneamente testo e immagini. Nella Messages API, le capacità visive possono essere utilizzate impostando content nel formato array e passando blocchi di contenuto immagine.

Utilizzare immagini codificate in Base64

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

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

# 读取并编码图片
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What's in this image?"
                }
            ]
        }
    ]
}

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

Utilizzare immagini URL

import requests

url = "https://api.acedata.cloud/v1/messages"

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

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

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

Esempio cURL

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

I formati immagine supportati includono: image/jpeg, image/png, image/gif, image/webp.

Documenti e PDF

I PDF utilizzano il blocco di contenuto document, con supporto per due fonti stabili: Base64 e URL. La fonte Base64 deve utilizzare application/pdf:

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

La fonte URL si scrive come {"type":"url","url":"https://example.com/report.pdf"}. document supporta inoltre text/plain e fonti content composte da blocchi text/image; i campi opzionali includono title, context e citations. La fonte file_id della Files API appartiene a una funzionalità beta separata e non rientra nel contratto stabile di questa interfaccia.

Cache dei prompt

Il cache_control di livello superiore posiziona automaticamente il punto di interruzione della cache sull’ultimo blocco memorizzabile nella cache:

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Quando è necessario controllare con precisione la posizione, è possibile anche scrivere lo stesso cache_control sui blocchi di contenuto text, image, document, tool_use, tool_result o sulla definizione dello strumento. ttl supporta 5m (predefinito) e 1h; utilizzare usage.cache_creation_input_tokens e usage.cache_read_input_tokens per determinare la scrittura nella cache e il raggiungimento della cache. Quando la risposta fornisce usage.cache_creation, ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. Se cache_creation è null o viene omesso, indica che esiste solo il totale delle scritture nella cache, senza una suddivisione autorevole per TTL; in questo caso non considerare alcun bucket come uno 0 noto, e la fatturazione e il totale rimangono basati sul campo aggregato. Esempio di risultato restituito:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Chiamata di strumenti (Tool Use)

La Claude Messages API supporta nativamente la funzionalità di chiamata di strumenti, consentendo al modello di chiamare gli strumenti/funzioni predefiniti quando necessario.

Esempio Python

import requests

url = "https://api.acedata.cloud/v1/messages"

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

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

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

Quando il modello decide di chiamare uno strumento, il content nel risultato restituito conterrà un blocco di contenuto di tipo tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

Si noti che stop_reason è tool_use, a indicare che il modello deve chiamare lo strumento. Dopo aver ricevuto questo risultato, è necessario eseguire la funzione dello strumento e restituire il risultato al modello sotto forma di tool_result:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

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

Il modello genererà la risposta finale in linguaggio naturale in base al risultato restituito dallo strumento.

Differenze rispetto alla Chat Completion API

Ace Data Cloud fornisce contemporaneamente due formati di Claude API, le cui principali differenze sono le seguenti: usage.input_tokens della Messages API rappresenta solo l’input non memorizzato nella cache, mentre cache_read_input_tokens e cache_creation_input_tokens sono bucket di fatturazione indipendenti; tutti e tre vengono calcolati separatamente in base ai rispettivi prezzi.

Caratteristica	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Formato	Formato nativo Anthropic	Formato compatibile con OpenAI
Prompt di sistema	Campo `system` indipendente	Trasmissione tramite `role: "system"` in `messages`
Struttura della risposta	Array `content` (supporta più tipi)	Array `choices` (include `message`)
Formato streaming	Eventi SSE (più tipi di eventi)	Righe SSE `data`
Ragionamento approfondito	`thinking` nativo e `output_config.effort`	Strategia predefinita del modello e parametri compatibili
Chiamata di strumenti	`tools` nativo + `input_schema`	Formato `tools` compatibile con OpenAI
Statistiche Token	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

Se il proprio sistema è già integrato con API in formato OpenAI, è possibile utilizzare la Chat Completion API per effettuare una transizione senza interruzioni. Se è necessario utilizzare tutte le funzionalità native di Claude, si consiglia di utilizzare la Messages API.

Gestione degli errori

Le risposte di errore dell’interfaccia pubblica utilizzano l’envelope della piattaforma Ace Data Cloud: error.code è un codice di errore stabile, error.message è la descrizione e trace_id viene utilizzato per analizzare le richieste. Gli stati HTTP comuni includono:

400: i parametri della richiesta o il contenuto del protocollo non sono validi.
401: il token di autorizzazione non è valido, è mancante o è scaduto.
403: accesso negato, saldo insufficiente o quota limitata.
404: l’API o il modello non esiste.
413: il corpo della richiesta è troppo grande.
429: troppe richieste.
500 / 503 / 504: errore del servizio, temporaneamente non disponibile o timeout di elaborazione.

Esempio di risposta di errore

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Questa struttura di errore è il contratto di runtime di Ace Data Cloud e non equivale all’envelope di errore ufficiale di Anthropic; gestirla in base allo stato HTTP e a error.code.

Conclusione

Attraverso questo documento, hai già appreso come utilizzare la Claude Messages API per richiamare la funzionalità di conversazione di Claude nel formato nativo di Anthropic. La Messages API supporta funzionalità avanzate come conversazioni di base, prompt di sistema, risposte in streaming, conversazioni multi-turno, ragionamento approfondito, comprensione visiva, PDF, caching dei prompt e chiamate di strumenti. In caso di domande, 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 Messages API

Processo di richiesta

Utilizzo di base

Esempio cURL

Esempio Python

Prompt di sistema

Esempio Python

Risposta in streaming

Esempio Python

Esempio JavaScript

Conversazione multi-turno

Esempio Python

Modello di ragionamento approfondito

Modelli visivi

Utilizzare immagini codificate in Base64

Utilizzare immagini URL

Esempio cURL

Documenti e PDF

Cache dei prompt

Chiamata di strumenti (Tool Use)

Esempio Python

Differenze rispetto alla Chat Completion API

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di richiesta

​Utilizzo di base

​Esempio cURL

​Esempio Python

​Prompt di sistema

​Esempio Python

​Risposta in streaming

​Esempio Python

​Esempio JavaScript

​Conversazione multi-turno

​Esempio Python

​Modello di ragionamento approfondito

​Modelli visivi

​Utilizzare immagini codificate in Base64

​Utilizzare immagini URL

​Esempio cURL

​Documenti e PDF

​Cache dei prompt

​Chiamata di strumenti (Tool Use)

​Esempio Python

​Differenze rispetto alla Chat Completion API

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di richiesta

Utilizzo di base

Esempio cURL

Esempio Python

Prompt di sistema

Esempio Python

Risposta in streaming

Esempio Python

Esempio JavaScript

Conversazione multi-turno

Esempio Python

Modello di ragionamento approfondito

Modelli visivi

Utilizzare immagini codificate in Base64

Utilizzare immagini URL

Esempio cURL

Documenti e PDF

Cache dei prompt

Chiamata di strumenti (Tool Use)

Esempio Python

Differenze rispetto alla Chat Completion API

Gestione degli errori

Esempio di risposta di errore

Conclusione