completamenti chat

Endpoint: POST /v1/chat/completions. La forma della richiesta e della risposta corrisponde esattamente all'API Chat Completions di OpenAI, compresi lo streaming e i campi facoltativi tool_calls / reasoning_tokens.

Chiamata di base

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a senior staff engineer."},
        {"role": "user", "content": "Pros and cons of postgres LISTEN/NOTIFY for a job queue?"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)

Parametri

Sono accettati tutti i parametri standard di OpenAI. Alcuni hanno senso solo per determinati fornitori: il traduttore inoltra quelli supportati da ciascun fornitore upstream.

Streaming

Imposta stream=True. Kunavo emette eventi inviati dal server nel formato esatto di OpenAI: ogni segmento è un chat.completion.chunk con choices[0].delta.content. Il payload finale di utilizzo arriva con data: [DONE].

stream = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
    stream=True,
)

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

Chiamata agli strumenti / alle funzioni

La chiamata agli strumenti funziona con tutti i fornitori. Definisci gli strumenti tramite uno schema JSON; il modello restituisce tool_calls nel messaggio; esegui lo strumento e reinviane i risultati come messaggi role: "tool".

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

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

# Inspect tool calls the model wants to make
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

Output JSON (response_format)

response_format richiede JSON. Le garanzie dipendono dalla famiglia di modelli, perché la richiesta di ciascuna famiglia viene tradotta in un meccanismo upstream diverso:

import json

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Jane Doe <jane@example.com> wants the Pro plan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "signup",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
                },
                "required": ["name", "email", "plan"],
                "additionalProperties": False,
            },
        },
    },
)
signup = json.loads(resp.choices[0].message.content)  # constrained to the schema

Quattro aspetti da conoscere su Claude:

• Lo schema viene inviato ad Anthropic quasi esattamente come l'hai scritto. Anthropic richiede additionalProperties: false per gli oggetti, quindi Kunavo lo aggiunge agli oggetti con proprietà elencate e lo lascia non impostato se lo produce Pydantic tramite model_json_schema(). Anthropic continua a rifiutare questi casi con un errore 400 che indica il problema: un oggetto lasciato aperto (additionalProperties impostato su un valore diverso da false oppure, se non sono elencate proprietà, additionalProperties non impostato) e oneOf — usa anyOf. La pagina di Anthropic sugli output strutturati elenca gli altri casi.
• strict e name vengono ignorati: Anthropic applica tutti gli schemi che accetta, in modalità strict o meno.
• Uno schema non può essere combinato con un messaggio assistant finale (un prefill); Anthropic risponde con un errore 400.
• Se max_tokens si esaurisce nel mezzo di un oggetto, il JSON viene troncato e finish_reason è "length".

Input visivo / multimodale

I modelli con la funzionalità vision accettano blocchi di contenuto immagine. Usa un URL HTTPS oppure un URI base64 data:.

# Pass an image URL or a base64 data URI as part of a multimodal message
resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/cat.jpg"
            }},
        ],
    }],
)
print(resp.choices[0].message.content)

Tra i modelli con funzionalità visiva nel catalogo figurano Claude Opus 5.5: consulta l'elenco dei modelli per gli altri.

Per un'immagine https, Kunavo scarica il file direttamente e lo invia al modello in linea, perché alcuni fornitori upstream ignorano un semplice URL dell'immagine. Limiti: 16 immagini per richiesta, 5 MB per immagine, 20 MB in totale, 10 secondi per download. Se non è possibile recuperare un'immagine, viene restituito un errore che la identifica, invece di ignorarla.

Ragionamento

La funzione di un controllo del ragionamento su questo endpoint dipende dalla famiglia, perché la richiesta di ciascuna famiglia viene tradotta in un'API upstream diversa:

# GPT models: reasoning_effort is forwarded as the Responses API's
# reasoning.effort. Reasoning tokens are part of completion_tokens.
resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Plan a 3-week MLOps migration."}],
    reasoning_effort="high",
)
details = resp.usage.completion_tokens_details   # absent when no reasoning ran
print(details.reasoning_tokens if details else 0)

caching dei prompt

Un prompt di sistema lungo, un documento di riferimento, un blocco few-shot: qualsiasi prefisso stabile può essere memorizzato nella cache a monte e riutilizzato nelle chiamate successive a una frazione del costo di input. Le cache hit compaiono nell’oggetto usage come prompt_tokens_details.cached_tokens.

I modelli GPT memorizzano automaticamente nella cache: non serve modificare la richiesta. cached_tokens è un sottoinsieme di prompt_tokens e viene fatturato a una tariffa ridotta per la lettura dalla cache.

Claude memorizza nella cache solo fino a un breakpoint cache_control e, su un prompt lungo, questo endpoint imposta i breakpoint al posto tuo: sul prompt di sistema, sulle definizioni degli strumenti e sull’ultimo messaggio non appena la conversazione contiene un turno dell’assistente. Per scegliere tu il prefisso, applica cache_control a un blocco di contenuto, come qui sotto; Kunavo mantiene i tuoi breakpoint e aggiunge i propri solo nelle posizioni che hai lasciato libere:

# Claude caches prefixes you mark with cache_control. Attach it to a content
# block; later calls reusing that prefix read it at ~10% of the input price.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LONG_DOCUMENT,            # the stable, reused prefix
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Summarize the document above."},
        ],
    }],
)
print(resp.usage.prompt_tokens_details.cached_tokens)

Oggetto usage

Ogni risposta (e il chunk finale dello streaming) include un oggetto usage:

Compatibilità di Ollama con OpenAI — /v1/chat/completions

Ollama rende disponibili i suoi modelli locali tramite un’API compatibile con OpenAI all’indirizzo http://localhost:11434/v1, implementando lo stesso contratto /chat/completions documentato in questa pagina. I due servizi sono quindi intercambiabili lato client: qualsiasi applicazione sviluppata per l’API v1 di Ollama funziona con quella di Kunavo cambiando l’URL di base e il modello.

from openai import OpenAI

# Before — Ollama's OpenAI-compatible API, local models
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",                       # ignored locally
)
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

# After — the same call against hosted frontier models.
# Two lines changed. Everything below them is untouched.
client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # <- was localhost:11434/v1
    api_key=os.environ["KUNAVO_API_KEY"],
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",  # <- was llama3.2
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

Gli elementi che di solito si rompono quando si cambia provider qui funzionano, perché il formato sul filo è lo stesso:

Prossimi passi

• Messages API Anthropic nativa
• Riferimento per la generazione di immagini
• Come funziona la fatturazione (prezzi dei token, maggiorazione)
• L’API di Ollama compatibile con OpenAI e il passaggio ai modelli ospitati
• Esplora tutti i modelli di chat