Migrazione graduale alle API Responses
In questa pagina
Aggiornato il 3 novembre 2026: La mappatura dei parametri indicava precedentemente che
max_tokensmanteneva il suo nome nelle API Responses; la tabella di xAI lo cambia inmax_output_tokense anche i contatori di utilizzo cambiano nome. Fonte: Confronto con Chat Completions.
Perché e quando migrare
L’endpoint Chat Completions è contrassegnato come legacy. Continuerà a funzionare, ma non riceverà nuove funzionalità. Se la tua applicazione necessita di strumenti lato server (ricerca web, esecuzione di codice), archiviazione delle conversazioni o ragionamento crittografato, la migrazione alle API Responses diventa necessaria.
La buona notizia: questa migrazione può avvenire gradualmente. Non devi riscrivere tutto in una volta sola.
Passo 1: Identifica le funzionalità che utilizzi
Prima di migrare, fai il punto su ciò che la tua applicazione utilizza con Chat Completions:
# Audit del tuo codice esistente
# Cerca questi pattern:
# 1. Chiamate di base (testo semplice)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Chiamata di funzioni
client.chat.completions.create(..., tools=[...])
# 4. Visione (immagini)
# messaggi con content come array [text, image_url]
# 5. Parametri di generazione
# temperature, max_tokens, top_p, stop, seed
Le chiamate di base e lo streaming sono le più semplici da migrare. La chiamata di funzioni richiede un adattamento del formato. La visione funziona in modo simile.
Passo 2: Migra le chiamate di base
La migrazione di una chiamata semplice segue questo schema:
# PRIMA — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# DOPO — API Responses
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mappatura dei campi
Le modifiche principali sono:
messagescon ruolosystem→instructions(parametro dedicato)messagescon ruolouser→input(stringa semplice)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, secondo la tabella di mappatura di xAI;temperaturemantiene il suo nomeresponse.usage.prompt_tokensecompletion_tokens→input_tokenseoutput_tokens(dettagli:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Passo 3: Migra le conversazioni multi-turno
È qui che le API Responses semplificano le cose. Invece di ricostruire la cronologia a ogni richiesta, le colleghi tramite ID:
# PRIMA — Chat Completions (gestisci tu la cronologia)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# DOPO — API Responses (il server gestisce la cronologia)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Il codice è più semplice e non devi più gestire manualmente l’array dei messaggi.
Passo 4: Sfrutta le nuove funzionalità
Una volta migrato, puoi sfruttare le funzionalità esclusive delle API Responses:
Ricerca web integrata
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# La risposta include citazioni con URL di origine
Archiviazione delle risposte
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Mantiene per 30 giorni
)
# Recupera successivamente
stored = client.responses.retrieve(response.id)
Ragionamento crittografato
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# Il ragionamento crittografato può essere riutilizzato nelle richieste successive
Strategia di migrazione consigliata
Invece di migrare tutto in una volta, procedi per passi:
- Identifica le chiamate Chat Completions nel tuo codice
- Classificale per complessità (base → streaming → chiamata di funzioni)
- Migra prima i nuovi endpoint o le nuove funzionalità (greenfield)
- Poi migra le chiamate esistenti più semplici
- Mantieni Chat Completions per le integrazioni di terze parti che lo richiedono (LangChain, ecc.)
Coesistenza temporanea
È perfettamente accettabile eseguire entrambi gli endpoint fianco a fianco durante la transizione:
# Wrapper che astrae l'endpoint utilizzato
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Questo approccio ti permette di passare gradualmente, testando ogni migrazione singolarmente.
Punti chiave
- La migrazione può essere graduale: non serve riscrivere tutto in una volta
- Cambiamenti principali:
messages→input/instructions,choices[0].message.content→output_text - Le conversazioni multi-turno passano da un array di messaggi a un semplice
previous_response_id - Le API Responses danno accesso a funzionalità esclusive (web_search, archiviazione, ragionamento crittografato)
- Esegui entrambi gli endpoint fianco a fianco durante la transizione e migra per ordine di complessità
Metti alla prova le tue conoscenze
L’API legacy compresa e la migrazione preparata.
1. Cosa significa lo status legacy e stateless di Chat Completions?
Risposta: L’endpoint rimane supportato ma non evolve più: essendo stateless, richiede il rinvio dell’intera cronologia a ogni chiamata; le API Responses sono la strada moderna.
2. Quali ruoli strutturano i messaggi?
Risposta: system (e developer), user, assistant: il framework, le richieste, le risposte; l’intera cronologia ricomincia a ogni richiesta.
3. Come si utilizza il codice OpenAI esistente con Grok?
Risposta: Cambiando base_url in https://api.x.ai/v1 e la chiave API; la compatibilità del formato gestisce il resto, inclusi OpenAI SDK e Vercel AI SDK.
4. Cosa leggi nella risposta e nell'utilizzo?
Risposta: choices contiene le risposte con finish_reason; usage dettaglia i token, inclusi reasoning_tokens per i modelli di ragionamento: la base per il tracciamento dei costi.
5. Come migrare correttamente alle API Responses?
Risposta: Gradualmente: nuovi sviluppi in Responses, endpoint esistenti convertiti uno per uno con nuovo test dei prompt; il confronto tra i due formati guida la conversione.
Comprendi il legacy, costruisci per il moderno: il piano di migrazione graduale del corso è la tua roadmap, senza grandi sconvolgimenti.