Messages API

Endpoint: POST /v1/messages. Richieste e risposte corrispondono esattamente all’API Messages di Anthropic, quindi l’SDK Anthropic — o qualsiasi strumento che la supporti — funziona con Kunavo modificando solo l’URL di base e la chiave.

Quale endpoint dovrei usare?

Kunavo offre due modalità per accedere alla famiglia Claude. Hanno tariffe identiche: scegli in base al formato delle richieste già supportato dal tuo codice.

Autenticazione

Imposta l’URL di base su https://api.kunavo.com: l’SDK Anthropic aggiunge autonomamente /v1/messages. Passa la tua chiave Kunavo (sk-kn-...) come chiave API; l’endpoint l’accetta nell’intestazione x-api-key (predefinita nell’SDK Anthropic) oppure in Authorization: Bearer.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-kn-...",                  # your Kunavo key
    base_url="https://api.kunavo.com",    # SDK appends /v1/messages
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="You are a senior staff engineer.",
    messages=[
        {"role": "user", "content": "Pros and cons of event sourcing?"},
    ],
)
print(msg.content[0].text)

caching dei prompt

Questo è il motivo principale per usare l’endpoint nativo. Aggiungi un punto di interruzione cache_control a qualsiasi blocco di sistema, blocco del contenuto di un messaggio o definizione di strumento. Il prefisso contrassegnato viene scritto nella cache una volta, poi riutilizzato nelle chiamate successive che lo condividono.

Il caching in sé non richiede questo endpoint: su /v1/chat/completions e /v1/responses Kunavo imposta da sé i punti di interruzione per i modelli Claude su un prompt lungo. Ciò che questo endpoint fa di diverso è non aggiungerne nessuno: il corpo della richiesta viene inoltrato così come l’hai inviato, quindi ogni punto di interruzione al suo interno l’hai impostato tu.

# Mark a large, stable prefix with cache_control. The first call writes that
# span to cache at 1.25× the input token price; later calls that reuse it read
# it back at ~10%.
msg = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_STYLE_GUIDE,            # tens of thousands of tokens
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "Review this PR against the guide."}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens)

Prezzi della famiglia Claude su Kunavo:

• cache_read_input_tokens — serviti dalla cache, fatturati a 0.10× della tariffa di input (sconto del 90%); 0,025× su Claude Fable 5.1, 0,05× su Claude Opus 5.5.
• cache_creation_input_tokens — scritti nella cache, fatturati a 1.25× la tariffa di input. Kunavo fattura le scritture con TTL di 1 ora alla stessa tariffa di 1.25×, inferiore al 2× di Anthropic.

Streaming

Imposta stream: true (oppure usa l’helper stream() dell’SDK). Kunavo inoltra verbatim lo stream di eventi nativo di Anthropic — message_start, content_block_delta, message_delta, message_stop —.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain CRDTs in one paragraph."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Immagini

Invia immagini come sorgenti base64 o url. Una sorgente url è l’unica parte del corpo della richiesta che Kunavo riscrive: scarica direttamente un’immagine https (oppure estrae una URI data:) e la inoltra come base64, perché il servizio upstream ignora una sorgente url e risponderebbe come se non fosse stata inviata alcuna immagine. Anche le immagini all’interno di un tool_result vengono gestite allo stesso modo. Limiti: 16 immagini per richiesta, 5 MB per immagine, 20 MB complessivi; se un’immagine non può essere recuperata, viene restituito un errore invece di ignorarla.

Oggetto usage

Ogni risposta (e gli eventi in streaming message_delta / message_start) contiene un oggetto usage nativo di Anthropic:

Strumenti lato server

Gli strumenti lato server di Anthropic (web_search, web_fetch, code_execution) vengono trasmessi come normali definizioni di strumenti. Il loro contributo alla conversazione (risultati della ricerca, una pagina recuperata, l’output di un programma) torna in usage sotto forma di token e viene fatturato alle tariffe indicate sopra.

Anche la ricerca web viene fatturata per ogni ricerca, oltre ai token: Anthropic indica un prezzo di 10 $ per 1.000 ricerche e Kunavo fattura tale importo applicando lo sconto specifico di ciascun modello. Il conteggio è usage.server_tool_use.web_search_requests, nella risposta o nell’evento finale message_delta di uno stream; una ricerca che restituisce un errore (ad esempio max_uses_exceeded) non viene conteggiata. Il recupero di pagine web e l’esecuzione di codice non costano nulla oltre ai relativi token.

Modelli supportati

Qualsiasi modello Claude abilitato accetta /v1/messages. Invia lo slug Kunavo come model:

• claude-fable-5, claude-sonnet-5
• claude-opus-5, claude-opus-4-7, claude-opus-4-6
• claude-sonnet-4-6, claude-haiku-4-5

I modelli GPT non sono disponibili qui: chiamali tramite /v1/chat/completions.

HTTP grezzo

Non è richiesto alcun SDK: l’endpoint accetta una normale richiesta POST JSON:

curl https://api.kunavo.com/v1/messages \
  -H "x-api-key: sk-kn-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

Prossimi passi

• Completamenti chat compatibili con OpenAI
• Come funziona la fatturazione (prezzi dei token, tariffe della cache, ricarico)
• Esplora tutti i modelli di chat