Utilizzo della Messages API

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

Questa guida copre i pattern comuni per lavorare con la Messages API, incluse le richieste di base, le conversazioni multi-turno, le tecniche di prefill e le capacità di visione. Per le specifiche complete dell'API, consulta il riferimento della Messages API. Per l'harness di agenti gestito, consulta invece la panoramica di Claude Managed Agents.

Richiesta e risposta di base

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    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-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Le risposte di rifiuto (stop_reason: "refusal") includono anche un oggetto stop_details che identifica la categoria di policy che ha attivato il rifiuto, su ogni modello. Consulta Gestione dei motivi di arresto per il riferimento dei campi e il codice di gestione di esempio.

Turni conversazionali multipli

La Messages API è stateless (senza stato), il che significa che invii sempre l'intera cronologia della conversazione all'API. Puoi usare questo pattern per costruire una conversazione nel tempo. I turni conversazionali precedenti non devono necessariamente provenire effettivamente da Claude. Puoi usare messaggi assistant sintetici.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    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-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Ruolo system nei messaggi

Su Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 e Claude Opus 5, puoi includere messaggi con "role": "system" dopo un turno dell'utente (soggetti 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. Usa il campo system di primo livello per le istruzioni che si applicano 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 in cache che lo precede. Usa 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.

Prefill della risposta di Claude

Puoi precompilare parte della risposta di Claude nell'ultima posizione dell'elenco dei messaggi di input. Usa questa tecnica per modellare la risposta di Claude. L'esempio seguente usa "max_tokens": 1 per ottenere da Claude una singola risposta a scelta multipla.

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. Puoi fornire immagini usando 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 httpx2

# Opzione 1: immagine codificata in Base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    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-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

Prossimi passi