Claude Messages API richiesta e utilizzo

Anthropic Claude è un sistema di dialogo AI molto potente, in grado di generare risposte fluide e naturali in pochi secondi semplicemente inserendo un prompt. Claude Messages API è il formato API nativo ufficiale di Anthropic, che, a differenza del formato compatibile con OpenAI (Chat Completion), utilizza una struttura di richiesta e risposta proprietaria di Anthropic, in grado di sfruttare meglio le capacità uniche di Claude, come l’input di contenuti multimodali, le chiamate agli strumenti, il pensiero profondo (Extended Thinking) e altre caratteristiche avanzate. Questo documento descrive principalmente il processo di utilizzo dell’API Claude Messages, che ci consente di utilizzare un’interfaccia nativa coerente con quella ufficiale di Anthropic per richiamare le funzionalità di dialogo di Claude.

Processo di richiesta

Per utilizzare Claude Messages API, puoi prima andare alla pagina Claude Messages API e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per la richiesta:

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che ti consente di utilizzare gratuitamente questa API.

Utilizzo di base

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

model: seleziona il modello Claude da utilizzare, come claude-opus-4-20250514, claude-sonnet-4-20250514, ecc.
messages: array di 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 della risposta singola.

Parametri opzionali comuni:

system: prompt di sistema, utilizzato per impostare il comportamento e il ruolo del modello.
temperature: casualità nella generazione, tra 0 e 1, valori più alti producono risposte più disperse.
stream: se utilizzare la risposta in streaming, impostato su true per ottenere un effetto di restituzione parola per parola.
stop_sequences: sequenze di arresto personalizzate, il modello smetterà di generare quando incontra questi testi.
top_p: parametro di campionamento nucleare, in combinazione con la temperatura per controllare la casualità della generazione.
top_k: campiona solo tra le K opzioni con la probabilità più alta.
tools: definizione degli strumenti, per consentire al modello di chiamare funzioni esterne.
tool_choice: controlla come il modello utilizza gli strumenti forniti.

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": "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-sonnet-4-20250514",
    "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-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Descrizione dei campi del risultato restituito:

id: identificatore unico per questo messaggio.
type: sempre message.
role: sempre assistant.
content: array di contenuti di risposta, ogni elemento contiene type (come text) e il contenuto corrispondente.
model: nome del modello che ha elaborato la richiesta.
stop_reason: motivo dell’arresto, i valori possibili includono end_turn (fine normale), max_tokens (raggiunta la lunghezza massima), stop_sequence (incontro con la sequenza di arresto), tool_use (chiamata a strumenti).
stop_sequence: se l’arresto è avvenuto a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente.
usage: statistiche sull’uso dei token, che includono input_tokens (numero di token in input) e output_tokens (numero di token in output).

Prompt di sistema

Claude Messages API supporta la definizione di 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": "Sei un assistente di traduzione professionale in cinese, per favore traduci l'inglese fornito dall'utente in cinese.",
    "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 la risposta in streaming; impostando il parametro stream su true, è possibile ottenere un effetto di restituzione graduale, molto adatto per implementare la visualizzazione parola per parola in una pagina 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), ogni riga è preceduta da event: e data:. I tipi di eventi in streaming includono:

message_start: inizio del messaggio, contiene 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, contiene nuovi frammenti di testo generati.
content_block_stop: fine del blocco di contenuto.
message_delta: aggiornamento incrementale a livello di messaggio, contiene stop_reason e informazioni finali su usage.
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":"Ciao"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Mi chiamo"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Come posso aiutarti oggi?"}}

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"}

Puoi vedere che l’evento content_block_delta nella risposta in streaming contiene il testo generato passo dopo passo, unendo tutti i text_delta si può 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: "Ciao, 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 multipla

Se desideri integrare la funzionalità di conversazione multipla, devi alternare i messaggi dei ruoli user e assistant nell’array messages, includendo la 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": "Ciao, mi chiamo Alice."},
        {"role": "assistant", "content": "Ciao Alice! Piacere di conoscerti. Come posso aiutarti oggi?"},
        {"role": "user", "content": "Qual è il mio nome?"}
    ]
}

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": "Il tuo nome è Alice, come mi hai appena detto!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Inviando la cronologia completa della conversazione in messages, Claude può fornire risposte accurate in base al contesto.

Modello di pensiero profondo

Claude supporta la funzionalità di Pensiero Esteso, che consente al modello di effettuare un ragionamento interno prima di rispondere, migliorando l’accuratezza nella gestione di problemi complessi. Per utilizzare questa funzionalità, è necessario inviare il parametro thinking.

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": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Qual è il seno di 30 gradi? Mostra il tuo ragionamento."}
    ]
}

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

Il risultato restituito è il seguente:

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "L'utente sta chiedendo il seno di 30 gradi. Questa è una domanda di trigonometria di base.\n\nIn un triangolo 30-60-90, i lati sono in rapporto 1:√3:2.\n\nPer un angolo di 30°:\n- Il lato opposto è 1\n- L'ipotenusa è 2\n- Quindi sin(30°) = opposto/ipotenusa = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "Il seno di 30 gradi è **1/2** o **0.5**.\n\nQuesto è uno dei valori trigonometrici fondamentali. In un triangolo 30-60-90, i lati sono in rapporto 1:√3:2, dove il lato opposto all'angolo di 30° ha lunghezza 1 e l'ipotenusa ha lunghezza 2, dandoci sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

Si può notare che l’array content contiene due blocchi di contenuto:

type: "thinking": il processo di pensiero interno del modello, che mostra i passaggi di ragionamento.
type: "text": il risultato finale della risposta.

Note:

Quando si utilizza thinking, max_tokens deve essere maggiore di budget_tokens, poiché budget_tokens è il budget di token assegnato al processo di pensiero.
Maggiore è budget_tokens, maggiore è lo spazio per un ragionamento più profondo del modello, adatto per affrontare problemi complessi.

Modello visivo

Claude supporta input multimodali, in grado di gestire contemporaneamente testo e immagini. Nella Messages API, è possibile utilizzare le capacità visive impostando content in formato array e includendo i blocchi di contenuto dell’immagine.

Utilizzo di 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"
}

# Leggi e codifica l'immagine
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": "Cosa c'è in questa immagine?"
                }
            ]
        }
    ]
}

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

Utilizzo di immagini da 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",
                        "media_type": "image/png",
                        "data": "https://example.com/image.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Cosa c'è in questa immagine?"
                }
            ]
        }
    ]
}

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

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": "Cosa c'è in questa immagine?"
                }
            ]
        }
    ]
}

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

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": "Cosa c'\''è in questa immagine?"
          }
        ]
      }
    ]
  }'

I formati di immagine supportati includono: image/jpeg, image/png, image/gif, image/webp. Esempio di risultato restituito:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Questa immagine mostra un'interfaccia di configurazione della richiesta API per quello che sembra essere un servizio di completamento chat AI. L'interfaccia include parametri per la selezione del modello, messaggi, modalità stream e impostazioni massime di token."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Utilizzo degli strumenti (Tool Use)

L’API dei messaggi di Claude supporta nativamente la funzionalità di chiamata degli strumenti, consentendo al modello di chiamare 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": "Ottieni il meteo attuale in una data posizione",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La città e lo stato, ad esempio San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Com'è il tempo a San Francisco?"}
    ]
}

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

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Fammi controllare il meteo a San Francisco per te."
    },
    {
      "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
  }
}

Nota che stop_reason è tool_use, il che indica che il modello ha bisogno di chiamare uno 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": "Ottieni il meteo attuale in una data posizione",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La città e lo stato, ad esempio San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Com'è il tempo a San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Fammi controllare il meteo a San Francisco per te."},
                {"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": "Soleggiato, 72°F"
                }
            ]
        }
    ]
}

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

Il modello genererà una risposta finale in linguaggio naturale basata sul risultato restituito dallo strumento.

Differenze con l’API di completamento chat

Ace Data Cloud offre due formati di API Claude, le principali differenze sono le seguenti:

Caratteristica	API dei messaggi (`/v1/messages`)	API di completamento chat (`/v1/chat/completions`)
Formato	Formato nativo di Anthropic	Formato compatibile con OpenAI
Prompt di sistema	Campo `system` indipendente	Passato tramite `role: "system"` in `messages`
Struttura della risposta	Array `content` (supporta più tipi)	Array `choices` (contiene `message`)
Formato streaming	Eventi SSE (diversi tipi di eventi)	Righe SSE `data`
Pensiero profondo	Parametro `thinking` nativo	Attivato tramite nomi di modelli speciali (es. suffisso `-thinking`)
Chiamata di strumenti	`tools` nativi + `input_schema`	Formato `functions` compatibile con OpenAI
Statistiche sui token	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

Se il tuo sistema è già integrato con l’API in formato OpenAI, puoi utilizzare l’API di completamento chat per un passaggio senza soluzione di continuità. Se hai bisogno di utilizzare tutte le capacità native di Claude, si consiglia di utilizzare l’API dei messaggi.

Gestione degli errori

Quando si chiama l’API, se si verifica 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 appreso come utilizzare l’API Claude Messages per chiamare le funzionalità di conversazione di Claude in formato nativo di Anthropic. L’API Messages supporta una serie di funzionalità ricche come conversazioni di base, messaggi di sistema, risposte in streaming, conversazioni multi-turno, pensiero profondo, comprensione visiva e chiamate a strumenti. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

Inizia

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Avanzato

Claude Messages API richiesta e utilizzo

Processo di richiesta

Utilizzo di base

Esempio cURL

Esempio Python

Prompt di sistema

Esempio Python

Risposta in streaming

Esempio Python

Esempio JavaScript

Conversazione multipla

Esempio Python

Modello di pensiero profondo

Esempio Python

Modello visivo

Utilizzo di immagini codificate in Base64

Utilizzo di immagini da URL

cURL 示例

Utilizzo degli strumenti (Tool Use)

Esempio Python

Differenze con l’API di completamento chat

Gestione degli errori

Esempio di risposta di errore

Conclusione

Inizia

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Avanzato

​Processo di richiesta

​Utilizzo di base

​Esempio cURL

​Esempio Python

​Prompt di sistema

​Esempio Python

​Risposta in streaming

​Esempio Python

​Esempio JavaScript

​Conversazione multipla

​Esempio Python

​Modello di pensiero profondo

​Esempio Python

​Modello visivo

​Utilizzo di immagini codificate in Base64

​Utilizzo di immagini da URL

​cURL 示例

​Utilizzo degli strumenti (Tool Use)

​Esempio Python

​Differenze con l’API di completamento chat

​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 multipla

Esempio Python

Modello di pensiero profondo

Esempio Python

Modello visivo

Utilizzo di immagini codificate in Base64

Utilizzo di immagini da URL

cURL 示例

Utilizzo degli strumenti (Tool Use)

Esempio Python

Differenze con l’API di completamento chat

Gestione degli errori

Esempio di risposta di errore

Conclusione