Anthropic API Reference

Claude Sonnet
JSON Reference

Tutti i parametri JSON ammessi per costruire prompt e chiamate API verso Claude Sonnet via endpoint /v1/messages.

POST https://api.anthropic.com/v1/messages

Campo	Tipo	Stato	Descrizione	Esempio / Valori
Campi principali — body JSON
model	string	obbligatorio	Modello da usare. Specifica la versione esatta di Claude da invocare.	claude-sonnet-4-6
max_tokens	integer	obbligatorio	Token massimi in output. Il modello può fermarsi prima. Deve essere ≥ 1.	1024
messages	array	obbligatorio	Conversazione completa. Lista ordinata di messaggi alternati user/assistant. L'API è stateless: invia sempre tutta la history.	[{role,content}]
messages[].role	string	obbligatorio	Ruolo del messaggio nella conversazione. I turni devono alternarsi.	"user" \| "assistant"
messages[].content	string \| array	obbligatorio	Stringa semplice (= un solo text block) oppure array di content block tipizzati (text, image, tool_use, tool_result).	"Testo" oppure [{type:"text", text:"…"}]
system	string \| array	opzionale	System prompt. Istruzioni globali per Claude (ruolo, stile, vincoli). Viene processato prima di tutti i messaggi.	"Sei un esperto di..."
Parametri di controllo generazione
temperature	number	opzionale	Casualità dell'output. 0 = deterministico, 1 = creativo. Default: 1.	0.0 – 1.0
top_p	number	opzionale	Nucleus sampling. Considera solo i token con prob. cumulativa ≤ top_p. Usare temperature o top_p, non entrambi.	0.0 – 1.0
top_k	integer	opzionale	Considera solo i top-K token più probabili ad ogni step. Raramente necessario.	≥ 1
stop_sequences	array[string]	opzionale	Sequenze di testo che fermano la generazione. Risposta avrà stop_reason = "stop_sequence".	["END", "\n\n"]
stream	boolean	opzionale	Streaming SSE. Se true, la risposta arriva token-per-token via Server-Sent Events invece che tutta insieme.	true \| false
metadata	object	opzionale	Metadati della richiesta. Contiene user_id per associare la richiesta a un utente specifico.	{user_id: "u_123"}
metadata.user_id	string	opzionale	ID utente opaco per audit e tracciamento. Max 256 caratteri.	"usr_abc123"
service_tier	string	opzionale	Livello di servizio API. Influenza priorità e rate limit della richiesta.	"standard" \| "priority"
Tools — function calling
tools	array	opzionale	Definizione tool/funzioni. Claude può invocarli per recuperare dati o eseguire azioni. Ogni tool ha name, description, input_schema.	[{name, desc, input_schema}]
tools[].name	string	obbligatorio	Nome univoco del tool, usato da Claude per invocarlo nel JSON di risposta.	"get_weather"
tools[].description	string	opzionale	Descrizione dello scopo del tool. Più è dettagliata, meglio Claude decide quando usarlo.	"Restituisce meteo attuale"
tools[].input_schema	object	obbligatorio	Schema JSON del tipo {type:"object"} che definisce i parametri di input del tool con tipi e required.	{type:"object", properties:{…}}
tool_choice	object	opzionale	Controllo uso tool. auto (Claude decide), any (forza un tool), tool (specifica quale), none (non usare tool).	{type:"auto"} {type:"tool", name:"…"}
Structured output
output_config	object	opzionale	Output strutturato. Garantisce che Claude risponda con JSON valido conforme a uno schema. Sostituisce il vecchio output_format beta.	{format:{type: "json_schema",…}}
output_config.format	object	opzionale	Formato di output. type può essere "json_schema" (schema preciso) o "json_object" (qualsiasi JSON valido).	{type: "json_schema", json_schema:{…}}
Prompt caching (beta)
cache_control	object	opzionale	Prompt caching. Aggiunto ai content block per indicare un breakpoint di cache. Riduce costi fino al 90% su contenuto ripetuto.	{type:"ephemeral"}

Struttura base — Ogni richiesta JSON deve contenere almeno model, max_tokens e messages. Tutto il resto è opzionale.

PROMPT MINIMO

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Ciao! Come stai?"
    }
  ]
}

CON SYSTEM PROMPT E CONTROLLI

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 2048,
  "system": "Sei un videomaker e grafico esperto. Rispondi sempre in italiano.",
  "temperature": 0.7,
  "stop_sequences": ["###"],
  "messages": [
    {
      "role": "user",
      "content": "Crea uno storyboard per un video di 30 secondi."
    }
  ],
  "metadata": {
    "user_id": "8e479f8b-d5eb-4fcd-965f-25c6b9c2f7be"
  }
}

CON OUTPUT STRUTTURATO JSON

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Estrai i dati di contatto da: John Doe, via Roma 64, tel 345566533"
    }
  ],
  "output_config": {
    "format": {
      "type": "json_schema",
      "json_schema": {
        "name": "ContactInfo",
        "schema": {
          "type": "object",
          "properties": {
            "nome": { "type": "string" },
            "cognome": { "type": "string" },
            "indirizzo": { "type": "string" },
            "telefono": { "type": "string" }
          },
          "required": ["nome", "cognome"]
        }
      }
    }
  }
}

CON TOOL / FUNCTION CALLING

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_image_info",
      "description": "Recupera dimensioni e formato di un file immagine",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": { "type": "string" },
          "format":   { "type": "string", "enum": ["png","jpg","webp"] }
        },
        "required": ["filename"]
      }
    }
  ],
  "tool_choice": { "type": "auto" },
  "messages": [
    {
      "role": "user",
      "content": "Che formato ha il file hero_banner.png?"
    }
  ]
}

Nota su temperature vs top_p — Anthropic raccomanda di usare uno solo dei due parametri per volta. Impostare entrambi può produrre comportamenti imprevedibili.

Header obbligatori

x-api-keyChiave API per autenticazione. Generata dalla Console Anthropic.
anthropic-versionVersione API da usare. Valore stabile: 2023-06-01
content-typeSempre application/json

Header opzionali / beta

anthropic-betaAttiva feature beta. Più valori separati da virgola.
request-idRestituito in response per tracciare la richiesta.

HEADERS COMPLETI — cURL

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --header "anthropic-beta: prompt-caching-2024-07-31" \
  --data '{ ... }'

Valori anthropic-beta comuni

prompt-caching-2024-07-31Abilita il prompt caching fino a 1 ora.
extended-thinking-2025-02-19Extended thinking / chain-of-thought.
computer-use-2025-01-24Computer use tool (controllo GUI).
search-results-2025-06-09Blocchi search result con citazioni native.
interleaved-thinking-2025-05-14Thinking interleaved con tool use.

STRUTTURA RESPONSE

{
  "id":       "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type":     "message",
  "role":     "assistant",
  "model":    "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "Risposta di Claude..."
    }
  ],
  "stop_reason":   "end_turn",   // end_turn | max_tokens | stop_sequence | tool_use
  "stop_sequence": null,
  "usage": {
    "input_tokens":              2095,
    "output_tokens":             503,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens":     0
  }
}

stop_reason — valori possibili

end_turnIl modello ha completato naturalmente la risposta.
max_tokensRaggiunto il limite di max_tokens.
stop_sequenceTrovata una delle stop_sequences.
tool_useIl modello vuole invocare un tool.

content[].type — possibili tipi

textRisposta testuale standard.
tool_useIl modello invoca un tool.
thinkingExtended thinking block (beta).
redacted_thinkingThinking cifrato (non leggibile).