Chat Completions vs API Responses: confronto
In questa pagina
Due endpoint, due filosofie
xAI offre due endpoint per interagire con i modelli Grok: Chat Completions (/v1/chat/completions) e l’API Responses (/v1/responses). Comprendere le loro differenze è essenziale per scegliere l’endpoint giusto per il tuo progetto e pianificare eventuali migrazioni.
| Aspetto | Chat Completions | API Responses |
|---|---|---|
| Stato | Legacy | Primario (consigliato) |
| Gestione dello stato | Senza stato (invia cronologia) | Con stato (previous_response_id) |
| Archiviazione server | No | Sì (30 giorni con store: true) |
| Conversazione | Array di messaggi | Concatenata per ID |
| Strumenti server | Solo chiamata di funzioni | web_search, x_search, code_interpreter, functions |
| Ragionamento crittografato | No | Sì (encrypted_content) |
| Nuove funzionalità | Non prioritarie | Prioritarie |
| Compatibilità OpenAI | Completa | Parziale |
Gestione dello stato: la differenza fondamentale
Chat Completions: gestisci tu la cronologia
Con ogni richiesta, devi reinviare l’intera conversazione:
# Chat Completions — reinvia tutto ogni volta
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello, my name is Alice."},
{"role": "assistant", "content": "Hello Alice! How can I help you?"},
{"role": "user", "content": "What is my first name?"}
]
)
API Responses: il server gestisce la cronologia
Con l’API Responses, un semplice identificatore basta per continuare una conversazione:
# API Responses — solo l'ID della risposta precedente
response1 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Hello, my name is Alice."
)
response2 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What is my first name?",
previous_response_id=response1.id
)
Il server mantiene il contesto e ricostruisce automaticamente la cronologia. Non paghi meno token (la cronologia viene comunque addebitata), ma semplifichi il tuo codice e riduci le dimensioni delle tue richieste.
Strumenti e funzionalità esclusive
L’API Responses dà accesso a strumenti server che Chat Completions non offre:
web_search: ricerca web in tempo realex_search: ricerca nei post di X (Twitter)code_interpreter: esecuzione di codice Python lato server
Questi strumenti sono integrati direttamente nella richiesta:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What is the latest news on AI?",
tools=[{"type": "web_search"}]
)
Chat Completions supporta la chiamata di funzioni (strumenti definiti dallo sviluppatore), ma non questi strumenti server gestiti da xAI.
Quando usare Chat Completions?
Chat Completions rimane la scelta giusta in diversi scenari:
- Migrazione da OpenAI: il tuo codice esistente funziona senza grandi modifiche
- Multi-provider: vuoi passare tra OpenAI, Anthropic e xAI con lo stesso codice
- Framework di terze parti: LangChain, LlamaIndex, Haystack e la maggior parte dei framework usano il formato Chat Completions
- Controllo totale: vuoi gestire tu la cronologia (riassunto, filtraggio, modifica)
Quando usare l’API Responses?
L’API Responses è preferibile per:
- Nuovi progetti: beneficia delle ultime funzionalità fin dall’inizio
- Strumenti server: necessità di ricerca web, esecuzione di codice o ricerca su X
- Conversazioni lunghe: nessun bisogno di reinviare la cronologia a ogni richiesta
- Ragionamento crittografato: accesso al contenuto del ragionamento per la continuità tra le richieste
Punti chiave
- Chat Completions è senza stato (gestisci tu la cronologia), l’API Responses è con stato (gestisce il server)
- L’API Responses offre strumenti server esclusivi: web_search, x_search, code_interpreter
- Chat Completions ha una compatibilità completa con OpenAI, l’API Responses è specifica per xAI
- Entrambi gli endpoint addebitano l’intera cronologia della conversazione
- Usa Chat Completions per la compatibilità, l’API Responses per le nuove funzionalità