Come utilizzare l'API di Claude Sonnet 5.5

In sintesi

Claude Sonnet 5.5 è un modello veloce per flussi di lavoro ben delimitati in ambito coding, documenti e uso di strumenti. Anthropic riporta oltre il 30% di output più rapido rispetto a Sonnet 5 agli stessi tassi standard di token. Inizia con una chiave CometAPI, l’ID modello claude-sonnet-5-5 e una piccola richiesta Messages o Chat Completions. Gli agent esistenti dovrebbero ritestare ragionamento, scelta degli strumenti e replay della cronologia prima del rollout.

Punti chiave

• Usa Claude Sonnet 5.5 e allinea il formato della richiesta all’endpoint.
• Inizia con una singola richiesta breve prima di aggiungere immagini, strumenti o contesti lunghi.
• Usa Messages per controlli specifici di Claude; usa Chat Completions per un’applicazione che già adotta l’SDK OpenAI.
• Rivedi le differenze nel ragionamento e nella selezione degli strumenti prima di migrare loop di agent esistenti.
• Confronta qualità dei task accettati, latenza, uso di token e cache hit prima di aumentare il traffico.

Che cos’è Claude Sonnet 5.5?

Claude Sonnet 5.5 API è l’interfaccia programmabile per il modello Sonnet 5.5 di Anthropic. È progettata per attività come sviluppo software, analisi di repository, automazione del supporto clienti, elaborazione documenti, comprensione di immagini, agent che usano strumenti e flussi di lavoro professionali strutturati.

Anthropic posiziona Sonnet 5.5 come complemento più veloce e a costo inferiore rispetto a Opus 5.5, il secondo modello della famiglia Claude 5.5, ottimizzato per coding ben definito, correzione di bug, creazione di documenti e presentazioni e attività professionali quotidiane. Gli sviluppatori possono accedere a Claude Sonnet 5.5 API in CometAPI usando claude-sonnet-5-5.

Anthropic conferma una finestra di contesto da 1M token e un limite di output sincrono di 128K. L’output in batch può raggiungere 300K token solo tramite Message Batches con l’header beta output-300k-2026-03-24. Il supporto delle funzionalità a livello di gateway va verificato separatamente dal supporto a livello di modello.

Come si comporta Claude Sonnet 5.5 sui benchmark ufficiali?

Il confronto compatto qui sotto aiuta a identificare i carichi di lavoro da valutare prima di adottare l’API. I risultati dei benchmark non sostituiscono i test sui propri prompt e loop di strumenti.

I risultati dei benchmark e le note di valutazione di Anthropic sono alla base di questo confronto. Il risultato di Terminal-Bench di Opus 5.5 usa lo sforzo Xhigh; FrontierCode riporta risultati distinti Max e Xhigh per Sonnet 5.5; OSWorld è una valutazione parziale. GDPval-AA e AA-Briefcase sono stati eseguiti da Artificial Analysis su una distribuzione pre-release della Claude Platform con un bug di structured-output che probabilmente ha sottostimato il punteggio di Sonnet 5.5; Anthropic afferma che il bug è stato poi corretto. Questi risultati devono guidare i test sui carichi di lavoro piuttosto che garantire risultati in produzione. Humanity’s Last Exam usa strumenti; Chartography no. Le nuove righe usano i punteggi pubblicati da Anthropic. L’immagine originale sotto è mantenuta; la tabella estesa include tre valutazioni aggiuntive.

Confronto ufficiale dei benchmark di Claude Sonnet 5.5

Cosa è cambiato nell’API Claude Sonnet 5.5 rispetto a Sonnet 5?

Le modifiche di migrazione a thinking, scelta degli strumenti e replay della cronologia influiscono sui loop degli agent esistenti. La tabella riassume queste modifiche operative; non è un inventario completo delle funzionalità.

Breaking changes da verificare

Verifica tutte e cinque le breaking change: sostituisci il thinking disabilitato con between_tools; rimuovi la scelta forzata dello strumento; preserva i blocchi di thinking compatibili e la cronologia della conversazione invariata; migra da computer_20251124 a computer_toolset_20260801 su Claude API e Google Cloud; e sostituisci gli accoppiamenti di advisor non supportati. Amazon Bedrock accetta ancora computer_20251124. Gli advisor non supportati includono Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6 e Haiku 5.5. Opus 5.5 è una sostituzione supportata. Leggi i blocchi di risposta per tipo. Verifica la compatibilità di piattaforma e gateway prima del rollout. Guida di migrazione ufficiale.

Capacità aggiuntive e cambiamenti nei flussi di lavoro

Usa la guida ufficiale alle funzionalità per rivedere aggiornamenti di progresso, sforzo per messaggio e controlli a conversazione in corso. Conferma il supporto del gateway prima di abilitare funzionalità beta.

Cosa serve prima di usare la Claude Sonnet 5.5 API?

• Un account CometAPI, una chiave API, accesso al modello e saldo di fatturazione disponibile.
• Un terminale con cURL; Python e pip o Node.js e npm per esempi SDK.
• Un endpoint selezionato: /v1/messages o /v1/chat/completions.
• COMETAPI_KEY memorizzata nell’ambiente del server, più accesso di rete a https://api.cometapi.com.
• Un prompt di test breve e un controllo chiaro per output utilizzabile, stato di completamento e uso dei token.

Come accedere alla Claude Sonnet 5.5 API tramite CometAPI?

Scegli la Messages API quando il comportamento di Claude in sé è importante. Scegli l’API compatibile con OpenAI quando la tua applicazione già alterna Claude, GPT, Gemini, DeepSeek o altri modelli attraverso lo stesso livello di astrazione.

Passo 1: archivia la chiave API

Crea una chiave nella console delle chiavi API di CometAPI, poi impostala nell’ambiente di runtime.

Imposta la chiave CometAPI in una shell POSIX

export COMETAPI_KEY="YOUR_COMETAPI_KEY"

Imposta la chiave CometAPI in PowerShell

$env:COMETAPI_KEY="YOUR_COMETAPI_KEY"

Passo 2: effettua la prima richiesta Messages

Invia la prima richiesta Messages compatibile con Anthropic

curl https://api.cometapi.com/v1/messages \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": "Explain exponential backoff in three bullet points."}]
  }'

Ispeziona i content block, lo stop_reason e l’uso prima di aggiungere altri controlli. La sintassi cURL sopra usa una shell POSIX.

Passo 3: usa l’SDK Python di Anthropic

Installa l’SDK Python di Anthropic

pip install anthropic

Leggi i blocchi di testo e l’uso con l’SDK Anthropic

import os
import anthropic

anthropic_client = anthropic.Anthropic(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com",
)

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Review this migration plan and list the three biggest risks."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
print("Completion:", response.stop_reason)
print("Usage:", response.usage)

Passo 4: usa l’SDK Python di OpenAI

Installa l’SDK Python di OpenAI

pip install openai

Chiama Sonnet 5.5 tramite Chat Completions compatibile OpenAI

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "system",
            "content": "You are a concise software engineering assistant."
        },
        {
            "role": "user",
            "content": "Review this function and identify the highest-risk bug."
        }
    ],
)

print(response.choices[0].message.content)

Questo approccio è utile quando un’applicazione già usa l’interfaccia dell’SDK OpenAI. Un’integrazione testuale di base può richiedere solo un nuovo base URL, chiave API e ID modello, ma le migrazioni in produzione dovrebbero comunque verificare parametri supportati, formati di risposta, chiamate a strumenti, eventi di streaming, timeout e conteggio token.

Passo 5: usa JavaScript in Node.js

Installa l’SDK Node.js di OpenAI

npm install openai

Chiama Sonnet 5.5 da un modulo ES in Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COMETAPI_KEY,
  baseURL: "https://api.cometapi.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [
    {
      role: "user",
      content: "Create a TypeScript function that validates an email address.",
    },
  ],
});

console.log(response.choices[0].message.content);

Per applicazioni backend in Node.js, mantieni COMETAPI_KEY nell’ambiente del server invece di inviarla a un client browser.

Livelli di thinking e sforzo di Claude Sonnet 5.5

L’API predefinisce sforzo alto; le applicazioni Claude e Claude Code usano medio. Seleziona lo sforzo in base a qualità del task accettato, latenza e costo in token. La tabella sotto è un punto di partenza editoriale, non una classificazione ufficiale dei carichi di lavoro.

Evita di assegnare automaticamente l’impostazione di sforzo più alta a ogni richiesta. I carichi di lavoro di agent possono diventare sensibilmente più costosi quando un ragionamento aggiuntivo genera anche più chiamate a strumenti e output più lunghi. Seleziona l’impostazione con una valutazione a livello di task. Usa thinking adattivo per Xhigh e Max, poi confronta qualità dei task accettati e costo totale con livelli inferiori. Guida ufficiale allo sforzo.

Configura lo sforzo tramite Messages

Questo esempio usa il client Anthropic inizializzato sopra. Verifica gli stessi controlli sul tuo percorso CometAPI prima del rollout.

Configura il thinking adattivo e sforzo alto

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Audit this service migration plan."}],
)

Disattiva il thinking iniziale

Usa thinking={"type": "between_tools"} con sforzo basso, medio o alto. Usa thinking adattivo per xhigh o max. between_tools non accetta i campi display o budget_tokens e non consente di cambiare lo sforzo a conversazione in corso.

Preserva il thinking nei loop di strumenti

Restituisci i blocchi di contenuto originali dell’assistente prima di aggiungere i risultati degli strumenti. Il thinking preservato dipende dal modello, dal prefisso di conversazione e dall’account produttore. Il binding del prefisso è applicato per impostazione predefinita su Claude API, Amazon Bedrock e Google Cloud per account creati a partire dal 31 agosto 2026, 00:00 UTC. Non presumere che ogni gateway esponga gli stessi controlli di binding.

Come effettuare lo streaming delle risposte di Claude Sonnet 5.5

Esegui lo streaming di risposte lunghe

Lo streaming è utile per interfacce chat, assistenti di coding e risposte lunghe perché gli utenti possono vedere l’output prima della fine della generazione.

Esegui lo streaming di testo tramite Chat Completions compatibile OpenAI

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "user",
            "content": "Explain how a retrieval-augmented generation pipeline works."
        }
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Lo streaming non riduce normalmente il numero totale di token generati. Il suo beneficio principale è la latenza percepita. Le applicazioni dovrebbero anche gestire stream interrotti, output parziali, retry di rete e cancellazioni in modo esplicito.

Usa strumenti con selezione automatica

Usa tool_choice={"type": "auto"}. Convalida ogni nome e argomento dello strumento, applica autorizzazioni e timeout, restituisci risultati strutturati e limita le iterazioni. L’esecuzione obbligatoria degli strumenti appartiene all’orchestrazione dell’applicazione.

Definisci uno strumento di lookup ticket e richiedi la selezione automatica

tools = [{
    "name": "lookup_ticket",
    "description": "Retrieve a support ticket by ID",
    "input_schema": {
        "type": "object",
        "properties": {"ticket_id": {"type": "string"}},
        "required": ["ticket_id"],
        "additionalProperties": False,
    },
}]

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Look up ticket T-123 and summarize its status."}],
)

Un blocco tool_use richiede un’azione; questa prima chiamata non la esegue. Convalida la richiesta sul tuo server, esegui l’operazione, aggiungi il contenuto dell’assistente invariato e invia un tool_result corrispondente. Lo schema in questo esempio richiede comunque la validazione in applicazione; il supporto rigoroso degli strumenti va verificato sul percorso selezionato.

Usa il prompt caching per contesti ripetuti

Il prompt caching è utile quando le richieste contengono ripetutamente lo stesso prefisso ampio, come policy di sistema, schemi di strumenti, mappe di repository, documentazione di prodotto, istruzioni riutilizzabili o manuali di riferimento.

Sonnet 5.5 richiede un prefisso cacheable di almeno 512 token. Prefissi più brevi sono elaborati senza cache, anche con cache_control. Controlla cache_creation_input_tokens e cache_read_input_tokens; se entrambi sono zero, non è stata usata alcuna cache. Conferma il supporto sul tuo route gateway. Riferimento al prompt caching.

Disponi il contesto stabile prima del contenuto dinamico della richiesta

Stable system instructions
Stable tools
Stable repository or knowledge context
---------------- cache boundary ----------------
Current user request
Current retrieved context

L’attuale tariffa di lettura cache di CometAPI è $0,16 per milione di token, contro $1,60 per input “fresco”. Le scritture cache sono fatturate separatamente. Verifica le cache hit nei metadati di usage prima di stimare i risparmi.

La cache è particolarmente utile per agent di coding e assistenti enterprise che riusano grandi prefissi di contesto tra i turni. L’economia dipende comunque dagli effettivi cache hit; riscrivere spesso il prefisso stabile può annullare gran parte del beneficio atteso.

Invia immagini usando lo schema dell’endpoint selezionato

Sonnet 5.5 accetta input di testo e immagini. Il JSON sotto è un payload Chat Completions compatibile OpenAI; sostituisci l’URL di esempio con un’immagine pubblicamente accessibile sotto il tuo controllo. Messages usa uno schema di blocco immagine diverso.

Invia un’immagine in un payload Chat Completions

{
  "model": "claude-sonnet-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Find the three most important UI problems in this screenshot."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/interface.png"
          }
        }
      ]
    }
  ]
}

La forma esatta della richiesta multimodale può differire tra interfacce native Claude e compatibili OpenAI, quindi usa lo schema dell’endpoint che effettivamente distribuisci invece di presumere che i due formati siano intercambiabili.

Gestisci salvaguardie e dati conservati

Registra rifiuti e comportamenti di fallback come stati applicativi espliciti. Anthropic descrive salvaguardie e disponibilità a zero data retention per il suo servizio. Verifica separatamente le disposizioni di retention e routing del tuo gateway prima di inviare materiale di produzione.

Claude Sonnet 5.5 vs Sonnet 5 vs Opus 5.5

Le etichette qualitative sotto sono indicazioni editoriali di instradamento basate sullo scopo del task, non valutazioni ufficiali di performance. Valida questi ruoli su carichi di lavoro rappresentativi. L’architettura dettagliata non è dedotta dai punteggi dei benchmark.

Instrada i task difficili a un modello di escalation

Routine task
    ↓
Claude Sonnet 5.5
    ↓
Confidence / validation failure?
    ├── No → Return result
    └── Yes → Escalate difficult case
                 ↓
              Opus-class model

Questo schema di routing può ridurre i costi preservando l’accesso a un livello di ragionamento più forte per i casi difficili.

Prezzi di Claude Sonnet 5.5 tramite CometAPI

Verificato il 10 ottobre 2026: input/output CometAPI restano $1,60/$8 per milione di token, 20% sotto i $2/$10 di Anthropic. La lettura/scrittura cache di CometAPI restano $0,16/$2; l’attuale lettura/scrittura cache di Anthropic sono $0,10/$2,50 per scritture con TTL di cinque minuti. La pagina di lancio mostra ancora letture cache a $0,20; questa revisione usa il riferimento caching attuale. I prezzi del gateway possono cambiare indipendentemente.

La differenza tra prezzo per token e costo del task conta per le applicazioni agent. Un agent di coding può generare meno token ma comunque eseguire più round di chiamate a strumenti, letture cache, ispezioni di codice, retry e validazioni. Il costo per task completato con successo è quindi di solito più informativo del solo prezzo dei token di input.

Stima degli addebiti per input “fresco” e token di output

Input:
100,000 / 1,000,000 × $1.60 = $0.16

Output:
5,000 / 1,000,000 × $8.00 = $0.04

Estimated model-token cost:
$0.20

Addebiti per strumenti, operazioni di cache, passaggi ripetuti dell’agent o altre funzionalità a pagamento possono modificare il costo finale.

Tariffe ricontrollate il 10 ottobre 2026 rispetto all’attuale pagina modello di CometAPI. I prezzi per input/output “fresco” sono invariati, quindi l’esempio resta $0,16 + $0,04 = $0,20 per 100.000 token di input fresco e 5.000 di output. Esclude scritture/letture cache, fee per strumenti e retry. Ricontrolla la fatturazione specifica del route prima di definire il budget.

Controlla il costo per task accettato

Ci sono diversi modi pratici per ridurre la spesa senza cambiare subito modello. Primo, definisci chiaramente i criteri di completamento:

Definisci un formato di accettazione della risposta focalizzato

Return only:
1. the root cause;
2. the affected file;
3. the smallest safe fix;
4. one regression test.

Secondo, riduci il contesto recuperato prima di inviarlo. Una finestra di contesto da 1M token è un limite di capacità, non un target. Terzo, riusa il contesto stabile tramite prompt caching. Quarto, seleziona lo sforzo per carico di lavoro invece di impostare Alto per ogni richiesta. Quinto, misura il costo per task accettato:

Calcola il costo per task accettato

Total API cost
÷
Number of outputs accepted without rework

Una richiesta più economica non è necessariamente un workflow più economico se causa retry, correzioni o chiamate a strumenti extra.

Come migrare da Sonnet 5 a Claude Sonnet 5.5 API?

1. Mantieni disponibile la configurazione di produzione precedente per un rollback.
2. Cambia l’ID modello da claude-sonnet-5 a claude-sonnet-5-5.
3. Applica le modifiche a thinking, selezione strumenti e cronologia descritte sopra.
4. Riproduci richieste rappresentative, inclusi strumenti, immagini e streaming.
5. Confronta output accettati, tasso di correzione umana, latenza p50/p95 e costo totale del task.
6. Testa retry, rifiuti, cancellazioni e stream interrotti.
7. Verifica cache hit e comportamento del budget di output nei metadati di usage.
8. Rilascia un canarino di traffico ridotto ed espandi solo dopo il superamento delle soglie di accettazione.

Risoluzione dei problemi di Claude Sonnet 5.5 API

Non riprovare richieste malformate o errori di autenticazione senza modifiche. Impedisci azioni duplicate degli strumenti quando riproduci esecuzioni di agent interrotte.

Buone pratiche per la produzione con Claude Sonnet 5.5

Scegli un carico di lavoro, definisci una soglia di accettazione e valuta l’applicazione completa. Registra ID modello, endpoint, sforzo, latenza, uso di token e cache, errori degli strumenti, stato di completamento ed esito dei task accettati. Mantieni le chiavi lato server e configura timeout, retry con limiti e limiti alle iterazioni degli agent.

Misura la qualità e l’affidabilità del workflow

Per agent di coding, traccia anche test superati, file modificati inutilmente, patch revertite e completamento con successo senza intervento umano.

Esempio: correggere un bug ben delimitato in un repository

Fornisci il test fallito, i file sorgente rilevanti e il comportamento atteso. Richiedi una patch focalizzata con un controllo di regressione. La soglia di accettazione è una correzione riproducibile, test pertinenti superati e nessuna modifica non correlata. Confronta il costo totale di API e strumenti con le patch accettate.

Esempio: triage di un ticket di supporto

Recupera il problema del cliente e i passaggi approvati del knowledge base. Chiedi al modello di classificare il problema, redigere una risposta supportata da evidenze e segnalare i casi da escalare. Accetta un risultato solo quando le sue affermazioni corrispondono al materiale recuperato e la decisione di routing segue la policy di supporto.

Esempio: revisione di un documento e uno screenshot

Fornisci una procedura approvata e uno screenshot dell’interfaccia corrispondente. Chiedi le discrepanze con riferimenti al passaggio pertinente e all’elemento UI visibile. Richiedi a un revisore di confermare i risultati prima di modificare la procedura.

Conclusione

Claude Sonnet 5.5 offre ai team un candidato pratico per workflow rapidi di coding, supporto, documenti e uso di strumenti. Inizia con una richiesta CometAPI funzionante, poi aggiungi i controlli necessari per la tua applicazione.

La migrazione richiede più del semplice cambio di ID modello: verifica impostazioni di thinking, selezione automatica degli strumenti, parsing delle risposte e replay della cronologia. Promuovi il modello quando le valutazioni sul tuo carico di lavoro mostrano un equilibrio accettabile tra qualità, latenza e costo; riserva un livello più potente per i task che non superano la tua soglia di accettazione.

FAQ

Come dovrebbero i team ruotare una chiave API di Claude Sonnet 5.5 senza downtime?

Conserva le chiavi in un secret manager lato server e consenti ai worker di ricaricare le credenziali senza incorporarle nel codice applicativo. Se il provider supporta chiavi attive sovrapposte, introduce prima la sostituzione, valida una piccola richiesta, sostituisci gradualmente i worker, quindi revoca la chiave precedente. Monitora gli errori di autenticazione durante il cambio ed evita di loggare entrambe le chiavi.

Come può un job di Claude Sonnet 5.5 riprendere dopo un riavvio del worker?

Conserva un identificatore di job, l’ultimo passaggio completato, la configurazione della richiesta e i record di esecuzione degli strumenti. Riprendi da un checkpoint verificato. Prima di ripetere un’azione di uno strumento, controlla se è già stata completata e se è sicuro ripeterla. Una trascrizione salvata da sola non impedisce ticket duplicati, messaggi o scritture su database.

Come dovrebbero i team rilevare cambiamenti di comportamento di Claude Sonnet 5.5 nel tempo?

Mantieni un set di valutazione datato con risposte accettate o controlli di accettazione, insieme alle versioni degli SDK e alle impostazioni delle richieste. Eseguilo periodicamente e dopo modifiche a provider, SDK, prompt o routing. Confronta successo del task, tasso di correzione, latenza e costo totale. Se un account offre il pinning di versione, conferma le sue garanzie prima di farvi affidamento; mantieni una rotta di rollback per workflow critici.