Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La tua prima chiamata API

Lezione 5 di 22 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. La tua prima chiamata API
  2. La chiamata più semplice
  3. Cosa contiene realmente la risposta
  4. I parametri che contano
  5. Passare a un input strutturato
  6. Non lasciare mai una chiamata senza protezione
  7. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato su none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_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 model e input
  • response.output_text fornisce il testo della risposta
  • response.usage dettaglia il consumo di token
  • temperature controlla la creatività (0.0 = fattuale, 1.0 = creativo)
  • instructions sostituisce il messaggio di sistema delle Chat Completions
  • Gestisci sempre gli errori con blocchi try/except