Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chat Completions vs API Responses: confronto

Lezione 11 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Due endpoint, due filosofie
  2. Gestione dello stato: la differenza fondamentale
  3. Strumenti e funzionalità esclusive
  4. Quando usare Chat Completions?
  5. Quando usare l’API Responses?
  6. Punti chiave

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 reale
  • x_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à