Gran parte del codice LLM in circolazione parla un solo dialetto: una lista di messaggi in ingresso, un messaggio in uscita. Quel dialetto è la Chat Completions API.
Come funziona
Fai una POST di JSON a /v1/chat/completions con un model e un array messages. Ogni messaggio ha un role (system, user, assistant o tool) e un content. La risposta contiene un array choices; ogni choice porta un message e un finish_reason che dice perché la generazione è finita, più un blocco usage con il conteggio dei token.
curl https://inference.broadnet.ai/v1/chat/completions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"broadnet/gemma-4-26b-a4b",
"messages":[{"role":"system","content":"Answer in one line."},
{"role":"user","content":"What is a token?"}]}'
Nell’SDK Python di OpenAI la stessa chiamata è client.chat.completions.create(...). I campi facoltativi modellano l’output: max_tokens, temperature, stream, tools, response_format e altri.
L’API è stateless. La guida alla migrazione di OpenAI dice che in Chat Completions “conversation state must be managed manually” (traduzione: lo stato della conversazione va gestito manualmente): è il tuo codice a tenere la cronologia e a rinviarla a ogni turno. La più recente Responses API di OpenAI usa elementi tipizzati e può mantenere lo stato lato server, e OpenAI la consiglia per i nuovi progetti sulla propria piattaforma, ma dice che Chat Completions “remains supported” (resta supportata).
Perché è importante
- Portabilità. Un’API compatibile con OpenAI di solito indica proprio questo endpoint. Cambiare provider spesso significa solo un nuovo base URL, una nuova chiave e un nuovo nome di modello.
- Costo. Dato che l’intera cronologia viene rinviata, i token di input crescono a ogni turno. Accorcia o riassumi le chat lunghe.
- Campi che divergono. Non tutti i provider compatibili accettano ogni campo di OpenAI. I campi sconosciuti possono essere ignorati o rifiutati, quindi prova quelli da cui dipendi.
Su BroadNet Inference
BroadNet serve la chat con POST /v1/chat/completions su https://inference.broadnet.ai/v1, per DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B e Gemma 4 VL 26B. Lo streaming usa stream=true e termina con data: [DONE]. Tool calling e output strutturato sono documentati solo per GLM 5.3 e Qwen3.8 27B. Il riferimento API di BroadNet non documenta un endpoint Responses, quindi usa Chat Completions. Parti dal quickstart con curl o dalla guida all’SDK Python.
Errori comuni
- Inviare solo l’ultimo messaggio dell’utente aspettandosi che il modello ricordi la chat.
- Copiare campi esclusivi di OpenAI su un altro provider senza controllarne il riferimento.