Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API Responses vs Chat Completions: perché migrare

Lezione 2 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. API Responses vs Chat Completions
  2. Cambiamenti fondamentali
  3. Gestione delle sessioni lato server
  4. JSON garantito, non JSON sperato
  5. Chiamate di funzione e streaming
  6. Guida rapida alla migrazione
  7. Devi migrare immediatamente?
  8. Punti chiave

API Responses vs Chat Completions

L’API Chat Completions è stata lo standard per anni e gran parte del codice che trovi online la utilizza ancora. Tuttavia, dal 2025, OpenAI l’ha classificata come legacy e raccomanda l’API Responses per tutti i nuovi progetti. Questa lezione confronta le due interfacce, concentrandosi sulle differenze che impattano realmente il tuo codice.

Cambiamenti fondamentali

Con Chat Completions, costruivi una lista di messaggi e inviavi l’intera lista a ogni chiamata. Lo stato della conversazione risiedeva nella tua applicazione, mai sul server:

from openai import OpenAI
client = OpenAI()

# Vecchio modello — Chat Completions (legacy)
response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ]
)
print(response.choices[0].message.content)
# Result: "The capital of France is Paris."

L’API Responses riduce questa stessa chiamata a due parametri e fornisce accesso diretto al testo generato. Il messaggio di sistema diventa il parametro instructions e l’estrazione del contenuto non richiede più di navigare attraverso choices[0].message.content:

from openai import OpenAI
client = OpenAI()

# Nuovo modello — API Responses
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the capital of France?"
)
print(response.output_text)
# Result: "The capital of France is Paris."

Gestione delle sessioni lato server

Questo offre il vantaggio più immediato. L’API mantiene lo stato della conversazione, quindi devi solo fare riferimento alla risposta precedente tramite il suo ID. Immagina un assistente per il supporto: al decimo scambio, l’approccio Chat Completions ti costringeva a reinviare i nove scambi precedenti, significando che pagavi di nuovo per quei token. Qui, basta un singolo campo:

# Prima domanda
response = client.responses.create(
    model="gpt-5.6-terra",
    input="My name is Marie."
)

# Seconda domanda — il contesto è preservato automaticamente
followup = client.responses.create(
    model="gpt-5.6-terra",
    input="What is my name?",
    previous_response_id=response.id
)
print(followup.output_text)
# Result: "Your name is Marie."

JSON garantito, non JSON sperato

Il secondo grande miglioramento riguarda l’output strutturato. Descrivi il formato atteso e l’API Responses garantisce che la risposta aderisca al tuo schema JSON, permettendoti di deserializzare senza reti di sicurezza. Un modulo di registrazione che estrae informazioni da testo libero non si rompe più solo perché il modello decide di aggiungere una frase introduttiva prima del suo JSON:

from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str
    population: int

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={"format": {"type": "json_schema", "json_schema": {
        "name": "city",
        "strict": True,
        "schema": City.model_json_schema()
    }}}
)
print(response.output_text)
# Result: {"name": "Paris", "country": "France", "population": 2161000}

Chiamate di funzione e streaming

La dichiarazione degli strumenti segue la stessa logica di semplificazione: il descrittore della funzione è dichiarato in modo piatto in tools e la chiamata richiesta dal modello appare direttamente in response.output, senza livelli extra di annidamento.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the weather like in Lyon?",
    tools=[{
        "type": "function",
        "name": "get_meteo",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Name of the city"}
            },
            "required": ["city"]
        }
    }]
)

# L'API restituisce direttamente la chiamata di funzione da eseguire
for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}, Arguments: {item.arguments}")
# Result: Function: get_meteo, Arguments: {"city": "Lyon"}

Lo streaming non restituisce più un flusso di chunk indifferenziati, ma eventi tipizzati. Filtri su event.type e sai esattamente cosa stai gestendo: un frammento di testo, un argomento di funzione o la fine della generazione:

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Tell a short story.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Guida rapida alla migrazione

Chat CompletionsAPI Responses
client.chat.completions.create()client.responses.create()
messages=[...]input="..." o input=[...]
response.choices[0].message.contentresponse.output_text
Cronologia manualeprevious_response_id
response_formattext={"format": {...}}
tools + tool_choicetools (semplificato)

Devi migrare immediatamente?

L’API Chat Completions rimane funzionale e non verrà rimossa. Il codice esistente che funziona, non richiede modifiche e si basa su una pipeline di test costruita attorno al vecchio formato non trae alcun vantaggio da una riscrittura urgente. Allo stesso modo, se dipendi da una libreria di terze parti che non supporta ancora l’API Responses, attendi il suo aggiornamento. Tuttavia, per qualsiasi nuovo progetto, la risposta è chiara: l’API Responses è il punto di partenza e il resto di questo corso procede da questa assunzione.

Punti chiave

  • L’API Responses sostituisce Chat Completions con un’interfaccia più semplice
  • La gestione delle sessioni lato server elimina la necessità di reinviare la cronologia
  • Output strutturato e chiamate di funzione sono integrati nativamente
  • La migrazione è diretta: i concetti restano gli stessi, cambia solo la sintassi