Utilizzo della Messages API

Anthropic offre due modi per sviluppare con Claude, ciascuno adatto a casi d'uso diversi:

Questa guida illustra i pattern comuni per lavorare con la Messages API, incluse le richieste di base, le conversazioni multi-turno, le tecniche di prefill e le funzionalità di visione. Per le specifiche complete dell'API, consulta il riferimento della Messages API.



Richiesta e risposta di base

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Su Claude Opus 4.7 e modelli successivi, le risposte di rifiuto (stop_reason: "refusal") includono anche un oggetto stop_details che identifica la categoria di policy che ha attivato il rifiuto. Consulta Gestione dei motivi di arresto per il riferimento dei campi e il codice di esempio per la gestione.



Turni conversazionali multipli

La Messages API è stateless, il che significa che devi sempre inviare l'intera cronologia conversazionale all'API. Puoi utilizzare questo pattern per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude. Puoi utilizzare messaggi assistant sintetici.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}



Ruolo system nei messaggi

Su Claude Opus 4.8, puoi includere messaggi con "role": "system" dopo un turno utente (soggetto alle regole di posizionamento) per aggiungere una nuova istruzione di sistema a metà di una conversazione. Un messaggio system non può essere la prima voce in messages; utilizza il campo system di primo livello per le istruzioni che si applicano fin dall'inizio.

Un messaggio di sistema a metà conversazione ha la stessa autorità del campo system di primo livello, ma poiché viene aggiunto alla fine della cronologia dei messaggi, non invalida alcun prefisso memorizzato nella cache che lo precede. Utilizza il campo system di primo livello per le istruzioni che devono applicarsi fin dal primo turno, e un messaggio di sistema a metà conversazione per le istruzioni che diventano rilevanti solo in seguito.

Consulta Messaggi di sistema a metà conversazione per la guida completa, incluso come combinarli con la cache dei prompt.



Mettere le parole in bocca a Claude

Puoi precompilare parte della risposta di Claude nell'ultima posizione dell'elenco dei messaggi di input. Questo può essere utilizzato per modellare la risposta di Claude. L'esempio seguente utilizza "max_tokens": 1 per ottenere una singola risposta a scelta multipla da Claude.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}



Visione

Claude può leggere sia testo che immagini nelle richieste. Le immagini possono essere fornite utilizzando i tipi di sorgente base64, url o file. Il tipo di sorgente file fa riferimento a un'immagine caricata tramite la Files API. I tipi di media supportati sono image/jpeg, image/png, image/gif e image/webp. Consulta la guida alla visione per maggiori dettagli.

import base64
import httpx

# Opzione 1: immagine codificata in Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# Opzione 2: immagine referenziata tramite URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}



Uso degli strumenti e uso del computer

Consulta la guida all'uso degli strumenti per esempi su come utilizzare gli strumenti con la Messages API. Consulta la guida all'uso del computer per esempi su come controllare ambienti desktop con la Messages API. Per output JSON garantito, consulta Output strutturati. Per un budget di token consultivo su un intero ciclo agentico, imposta output_config.task_budget; consulta Budget delle attività.