La tua prima chiamata API
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato sunone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Utilizzo di GPT-6 · GPT-5.6 Terra.
La tua prima chiamata API
Il tuo ambiente è pronto: mettiamoci al lavoro. Stai per effettuare la tua prima chiamata all’API Responses, analizzare l’oggetto restituito e quindi manipolare i parametri che distinguono una risposta generica da una utile.
La chiamata più semplice
Ti servono solo due parametri: model, l’identificativo del modello da interrogare, e input, il tuo prompt (che può essere una stringa di testo o un elenco di messaggi, come vedremo a breve).
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the difference between Python and JavaScript?"
)
print(response.output_text)
# Result: Python is a versatile language oriented toward data science
# and backend development, while JavaScript is primarily used for
# frontend and backend web development (via Node.js)...
Cosa contiene realmente la risposta
output_text è solo una scorciatoia pratica. L’oggetto response contiene anche il suo ID univoco (essenziale per concatenare gli scambi e consultare le chiamate nei tuoi log), il modello effettivamente utilizzato e un dettaglio del consumo di token. Prendi l’abitudine di registrare queste tre informazioni fin dai tuoi primi script. È ciò che ti permetterà di rispondere in seguito alla domanda: «Perché la fattura è raddoppiata questo mese?».
response = client.responses.create(
model="gpt-5.6-terra",
input="Hello, how are you?"
)
# Il testo della risposta (scorciatoia)
print(response.output_text)
# L'ID univoco della risposta
print(f"ID: {response.id}")
# Il modello utilizzato
print(f"Model: {response.model}")
# Token consumati
print(f"Input tokens: {response.usage.input_tokens}")
print(f"Output tokens: {response.usage.output_tokens}")
print(f"Total tokens: {response.usage.total_tokens}")
# Result:
# Hello! I'm doing very well, thank you. How can I help you?
# ID: resp_abc123xyz
# Model: gpt-5.6-terra
# Input tokens: 14
# Output tokens: 19
# Total tokens: 33
I parametri che contano
temperature governa la variabilità della generazione. A 0.0, il modello sceglie sistematicamente la continuazione più probabile: è l’impostazione ideale per domande fattuali, estrazione di dati e tutto ciò che deve essere riprodotto in modo identico. A 1.0, esplora di più, ed è ciò che desideri per trovare nomi, scrivere testi creativi o generare varianti.
# Bassa temperatura (0.0) = deterministico, fattuale
response_factual = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input="What is the capital of Germany?",
temperature=0.0
)
print(response_factual.output_text)
# Result: The capital of Germany is Berlin.
# Alta temperatura (1.0) = creativo, vario
response_creative = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input="Invent a name for a literary café.",
temperature=1.0
)
print(response_creative.output_text)
# Result: "The Wandering Pages"—a café where every table bears
# the name of a famous chapter.
Il parametro instructions svolge il ruolo del vecchio messaggio di sistema: definisce il ruolo, il tono e i vincoli che il modello deve mantenere durante tutto lo scambio, indipendentemente dalla domanda posta. Nell’esempio seguente, la stessa domanda posta senza istruzioni produrrebbe un elenco di consigli generali; con le istruzioni, produce invece delle ricette.
response = client.responses.create(
model="gpt-5.6-terra",
instructions="You are an expert in French cuisine. "
"Always respond with recipe suggestions.",
input="I don't know what to do with zucchini."
)
print(response.output_text)
# Result: Here are three ideas for your zucchini:
# 1. Zucchini gratin with goat cheese...
# 2. Provençal ratatouille...
# 3. Cold zucchini velouté with mint...
Infine, max_output_tokens limita la lunghezza della risposta. Si tratta di una salvaguardia di budget, non di un’istruzione di scrittura: la risposta viene troncata bruscamente una volta raggiunto il limite. Se desideri una risposta breve e ben formata, chiedilo esplicitamente anche nel prompt.
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain general relativity.",
max_output_tokens=100
)
print(response.output_text)
print(f"Tokens used: {response.usage.output_tokens}")
# The response will be truncated at approximately 100 tokens
Passare a un input strutturato
Quando una semplice stringa non basta, input accetta un elenco di messaggi. La forma minima contiene un singolo turno, ma il vantaggio emerge non appena fornisci una cronologia: il modello ha così accesso a quanto già detto e risponde di conseguenza. Qui, «progresso» va inteso nel contesto di Python, non in senso astratto.
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": "Translate to English: Hello world"
}
]
)
print(response.output_text)
# Result: Hello world
# Con il contesto della conversazione
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": "My favorite language is Python."
},
{
"role": "assistant",
"content": "Python is an excellent choice! It is very versatile."
},
{
"role": "user",
"content": "Give me a tip to improve."
}
]
)
print(response.output_text)
# Result: To improve in Python, I recommend that you...
Non lasciare mai una chiamata senza protezione
Le chiamate di rete falliscono e le chiavi scadono. Tre eccezioni coprono la maggior parte dei casi quando si inizia: AuthenticationError per una chiave mancante o non valida, RateLimitError quando superi la throughput consentita e APIError come rete di sicurezza generica. Un’intera lezione tornerà sulla strategia completa, ma fin da oggi, avvolgi le tue chiamate in blocchi di gestione errori.
from openai import OpenAI, APIError, AuthenticationError, RateLimitError
client = OpenAI()
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
except AuthenticationError:
print("Error: Invalid or missing API key")
except RateLimitError:
print("Error: Too many requests, wait a moment")
except APIError as e:
print(f"API Error: {e.message}")
Per consolidare tutto ciò, scrivi uno script che ponga tre domande e accumuli i token consumati. Combinerai il ciclo di chiamata, una temperatura di 0.0 per risposte stabili e la lettura di usage: i tre riflessi di base.
from openai import OpenAI
client = OpenAI()
questions = [
"What is the largest ocean in the world?",
"Who painted the Mona Lisa?",
"How many planets are in the solar system?"
]
total_tokens = 0
for question in questions:
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=question,
temperature=0.0
)
tokens = response.usage.total_tokens
total_tokens += tokens
print(f"Q: {question}")
print(f"A: {response.output_text}")
print(f" ({tokens} tokens)\n")
print(f"Total: {total_tokens} tokens consumed")
Punti chiave
- Una chiamata di base richiede solo
modeleinput response.output_textfornisce il testo della rispostaresponse.usagedettaglia il consumo di tokentemperaturecontrolla la creatività (0.0 = fattuale, 1.0 = creativo)instructionssostituisce il messaggio di sistema delle Chat Completions- Gestisci sempre gli errori con blocchi try/except