Torna al blog
Guida·23 maggio 2026·6 min di lettura

Chiamare Claude con l'SDK OpenAI — cambia una riga, mantieni il tuo codebase

L'SDK di Anthropic è eccellente, ma l'ecosistema si è standardizzato su quello di OpenAI. Ecco come chiamare Claude Opus 4.7, Sonnet 4.6 e Haiku 4.5 con gli SDK Python e Node di OpenAI non modificati — inclusi streaming, uso degli strumenti e visione.

L'SDK ufficiale di Anthropic è eccellente, ma l'intero ecosistema IA si è standardizzato sulla struttura del client OpenAI: ogni esempio, ogni adattatore di framework, ogni tutorial "hello world" presume che tu abbia a portata di mano un'istanza OpenAI(...). Migrare il codice per chiamare direttamente l'SDK di Anthropic è un refactoring significativo.

Non è necessario. Questo articolo mostra come chiamare Claude Opus 4.7, Sonnet 4.6 e Haiku 4.5 tramite l'SDK OpenAI senza modifiche, instradando le chiamate attraverso Kunavo. Stesso SDK, stessi tipi, stesso streaming, stesso utilizzo degli strumenti. L'unica riga che cambia è base_url.

La modifica minima

Con il pacchetto Python openai già installato, la migrazione completa è questa.

main.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",   # the only line that changes
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",              # a Claude slug, not gpt-4o
    messages=[
        {"role": "system", "content": "You are a senior platform engineer."},
        {"role": "user",   "content": "Critique this SQL migration..."},
    ],
)
print(resp.choices[0].message.content)

api_key diventa la tua chiave Kunavo (creata in /app/keys). base_url punta al nostro gateway. L'ID del modello passa da gpt-4o a uno slug Claude: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5. Il corpo della richiesta, la struttura della risposta e ogni helper dell'SDK si comportano esattamente come con OpenAI.

Streaming

Lo streaming funziona nello stesso modo. Kunavo inoltra i chunk SSE di Anthropic nel formato OpenAI chat.completion.chunk, quindi il modello di iterazione asincrona esistente funziona senza modifiche.

stream.py
for chunk in client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Explain Raft in 200 words."}],
    stream=True,
):
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Utilizzo degli strumenti / chiamate di funzione

Il protocollo di utilizzo degli strumenti di Anthropic è semanticamente uguale alle chiamate di funzione di OpenAI: differiscono solo a livello di trasmissione. Kunavo traduce in entrambe le direzioni l'array tools, la risposta tool_calls e i messaggi successivi tool. Usa tool_choice="auto", "none" o uno strumento denominato: vengono tutti mappati.

tools.py
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather in a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)
print(resp.choices[0].message.tool_calls)

Visione

Claude è multimodale dalla versione 3.5; passare un'immagine usa il normale array OpenAI content: [{ type: 'text' }, { type: 'image_url' }]. image_url.url può essere un URL https oppure un URI base64 data:.

vision.py
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url",
             "image_url": {"url": "https://example.com/cat.jpg"}},
        ],
    }],
)

Quando usare l'SDK nativo di Anthropic

Alcune funzioni esclusive di Anthropic non possono essere espresse nel formato OpenAI, soprattutto la direttiva cache_control per il caching dei prompt e i token thinking estesi. Se ti serve una di queste funzioni, cambia SDK ma mantieni la stessa chiave: Kunavo espone anche l'endpoint nativo /v1/messages, quindi anche l'SDK di Anthropic funziona con una sola modifica a base_url.

anthropic_native.py
from anthropic import Anthropic

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

resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system="You are a senior platform engineer.",
    messages=[{"role": "user", "content": "What is a hot standby?"}],
)
print(resp.content[0].text)

Consulta la documentazione dell'API Messages nativa per l'elenco completo dei parametri pass-through e /docs/caching per sapere come il caching dei prompt consente di risparmiare fino al 90% del costo degli input nei prompt ripetuti.

Il caching dei prompt non richiede di per sé di cambiare SDK. Con un prompt lungo, Kunavo imposta per te i punti di interruzione della cache sul percorso nel formato OpenAI: sul prompt di sistema, sulle definizioni degli strumenti e sull'ultimo messaggio di una conversazione che contiene già un turno dell'assistente. Un cache_control che aggiungi tu a un messaggio di sistema, a un messaggio dell'utente o a una definizione di strumento viene inoltrato a Claude.

Cosa rinunci e cosa ottieni

Il percorso nel formato OpenAI è una traduzione, non il protocollo nativo. Due piccoli elementi non attraversano il confine:

  • Parametri del thinking: thinking e reasoning_effort non vengono inoltrati a Claude su questo percorso. Per attivare l'extended thinking o regolarlo, usa l'API Messages nativa.
  • Output del thinking: quando il modello usa il thinking, la risposta non lo include e l'oggetto usage non ne riporta un conteggio separato; i token di thinking vengono conteggiati all'interno di completion_tokens.

Il vantaggio è significativo: un solo SDK per Claude, GPT, GPT-Image, Veo e il resto del catalogo; al di sotto dei prezzi ufficiali dei provider a seconda del modello; fatturazione nativa Stripe nella tua valuta locale; nessuna sostituzione silenziosa del modello: il failover cambia il provider, mai il modello, e la dashboard dettaglia il modello, i token e il costo di ogni chiamata.

Due minuti per verificare

Registrati su kunavo.com/app/signup: una ricarica di $10 copre diverse migliaia di chiamate Claude, con pagamento a consumo, e il saldo non scade mai. Inserisci il tuo base_url, sostituisci l'ID del modello con uno slug Claude ed esegui la suite di test esistente. Se qualcosa non funziona correttamente, scrivi a contact@kunavo.com: leggiamo ogni messaggio.

Approfondimenti correlati