Guida alle API compatibili con OpenAI — dall'endpoint locale di Ollama ai modelli frontier ospitati

"Compatibile con OpenAI" significa che un'API parla lo stesso formato di trasmissione di OpenAI /v1/chat/completions — quindi qualsiasi SDK o strumento OpenAI funziona modificando solo base_url. Ollama espone un endpoint compatibile con OpenAI per i modelli eseguiti localmente sulla tua macchina. Kunavo ne espone uno per i modelli frontier ospitati — Claude, GPT e modelli di immagini, video e audio — dietro un unico bearer token. Questa guida mostra il modello e come passare dall'uno all'altro senza riscrivere il codice.

Cosa significa "compatibile con OpenAI"

Il formato OpenAI Chat Completions è diventato lo standard de facto: un array messages in ingresso, un choices[].message in uscita, Server-Sent Events per lo streaming, tools per le chiamate di funzione. Qualsiasi endpoint che rispetti questo contratto è "compatibile con OpenAI" e gli SDK ufficiali openai (Python, Node e ogni porting della community) lo utilizzano impostando base_url.

Il modello Ollama (locale)

Ollama esegue modelli open localmente e li rende disponibili su http://localhost:11434/v1:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Stesso codice, modelli frontier ospitati (Kunavo)

Indirizza lo stesso identico SDK a Kunavo e scegli un modello frontier. Cambiano solo base_url, api_key e model — la chiamata è identica byte per byte:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Ottieni una chiave su /app/keys; la guida rapida include esempi per Node e curl.

Locale o ospitato: quale usare

Una configurazione comune: Ollama su localhost per lo sviluppo offline, Kunavo per la qualità ospitata in produzione — una variabile d'ambiente li alterna. Per il contratto campo per campo implementato da entrambe le parti — parametri, delta dello streaming, tool_calls, l'oggetto usage e la tabella di parità con la superficie v1 di Ollama — consulta il riferimento /v1/chat/completions e la relativa sezione sulla compatibilità OpenAI di Ollama.

Scoprire i modelli a runtime

Come /api/tags di Ollama, Kunavo espone un catalogo con struttura OpenAI. Risolvi gli slug a runtime invece di codificarli:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Oltre la chat

La stessa chiave raggiunge gli endpoint per immagini (/v1/images/generations), video (/v1/video/generations) e audio — tutti con struttura OpenAI. Consulta la guida all'IA multimodale e il confronto con OpenRouter per capire in cosa Kunavo differisce dagli altri gateway.

Una superficie va oltre la definizione abituale di “compatibile” ed è importante conoscerla: POST /v1/responses. Codex CLI accetta un provider personalizzato solo tramite l'API Responses, motivo per cui la maggior parte dei gateway compatibili con OpenAI non può pilotarlo — quanto costa Codex per token illustra il funzionamento con un blocco di configurazione operativo. Per calcolare il prezzo di un carico GPT includendo l'input memorizzato nella cache, il calcolatore dei prezzi dell'API OpenAI usa i tuoi conteggi di token.

Domande frequenti