Guida all’integrazione
Qui i modelli di testo parlano i protocolli che il tuo SDK già parla: Chat Completions, il sottoinsieme senza stato di Responses, Anthropic Messages e generateContent di Google. La domanda interessante è cosa succede a un parametro che il modello di destinazione non ha mai dichiarato.
La sfida
Il fallimento classico non è un 500. È un parametro che il tuo gateway ha accettato, scartato e mai menzionato, così il modello ha girato senza la tua temperature, senza le tue definizioni di strumenti o senza il tuo formato di risposta – e l’output è sembrato soltanto deludente invece che rotto.
01
messages, tools, tool_choice, response_format, max_tokens, temperature e top_p si mappano sui campi dichiarati dal modello. Tutto il resto viene inoltrato allo schema del modello e restituisce 400 quando il modello non lo dichiara. Il silenzio non è mai la risposta.
02
Su /v1 il corpo è un oggetto errore in stile OpenAI o Anthropic, non la struttura {code, msg, data, request_id} usata da /api/v1. Gestisci entrambi se il tuo prodotto mescola le due superfici.
03
stream: true restituisce eventi chat.completion.chunk chiusi da data: [DONE]. La fatturazione segue comunque l’uso misurato, quindi uno stream interrotto non è una richiesta gratis.
L’approccio
Cambia base_url e api_key, sostituisci la stringa del modello con un valore da GET /v1/models ed esegui la suite di test che hai già. Dove torna un 400 su un parametro, quel parametro non era supportato dal modello che hai scelto – un’informazione che la versione silenziosa non ti dava.
Funziona qualsiasi client compatibile con OpenAI. Cambiano solo la base URL e il valore di model.
POST /v1/chat/completions
from openai import OpenAI
client = OpenAI(
base_url="https://api.spicyapi.ai/v1",
api_key=os.environ["SPICY_API_KEY"],
)
stream = client.chat.completions.create(
model="<publisher>/<model>/chat", # exact value from GET /v1/models
messages=[{"role": "user", "content": "Summarise these notes in three bullets."}],
temperature=0.7,
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")text/event-stream
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"- "}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Ships"}}]}
data: [DONE]Contratto
| Campo o header | Valore o limite |
|---|---|
| POST /v1/chat/completions | chat.completion · SSE with stream: true |
| GET /v1/models | every callable model value |
| Authorization: Bearer · x-api-key · x-goog-api-key | accepted on /v1 |
| undeclared parameter | 400 · never silently dropped |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Scelta
Verifiche
/v1/chat/completions, /v1/responses, /v1/messages e /v1beta/models/{model}:generateContent si autenticano tutti con la stessa chiave. Authorization: Bearer, x-api-key e x-goog-api-key sono accettati ognuno dove l’SDK se lo aspetta.
GET /v1/models restituisce esattamente gli identificatori accettati da ogni operazione /v1 e /api/v1, con il produttore del modello in owned_by. I prezzi arrivano da /api/v1/models, che è specifico dell’account e quindi privato.
Il livello di compatibilità riusa autenticazione, limiti di frequenza, validazione, prezzi e logica dei blocchi della superficie nativa. Cambia solo la struttura della risposta.
Prima del lancio
Domande frequenti
Modelli
Ogni link apre la pagina di quella famiglia di modelli: input, limiti, politica sui contenuti e prezzo attuale per unità.
Continua
Punta un client OpenAI, Anthropic o Google su SpicyAPI. Cosa passa tale e quale, cosa viene rifiutato apposta e come si fattura il testo.
