Usare le API di OpenAI (GPT-5.6) in Python: guida pratica

Le API di OpenAI sono il modo piu' diretto per integrare i modelli GPT-5.6 nelle proprie applicazioni: un chatbot, uno strumento che riassume documenti, un classificatore, un agente che chiama funzioni. Questa guida ti porta dalla prima chiamata fino a tecniche avanzate come lo streaming, l'output in JSON strutturato e il function calling, con codice Python che puoi copiare e adattare.

A chi serve e cosa ti serve prima di iniziare

La guida e' pensata per chi ha una conoscenza di base di Python (sai cos'e' una funzione e come si installa un pacchetto) e vuole costruire qualcosa con l'IA. Prerequisiti concreti:

• Python 3.9 o superiore installato (verifica con python3 --version).
• Un account OpenAI su platform.openai.com e una chiave API.
• Credito disponibile: le API sono a pagamento a consumo. La famiglia GPT-5.6 (nelle varianti Luna, Terra e Sol) parte da circa 1 dollaro per milione di token in ingresso per la piu' economica, fino a circa 5 dollari per la piu' potente, con una finestra di contesto di 1 milione di token.

Passo 1: installazione e chiave API

Crea una cartella di progetto, un ambiente virtuale e installa la libreria ufficiale:

python3 -m venv venv
source venv/bin/activate        # su Windows: venv\Scripts\activate
pip install openai

Non scrivere mai la chiave dentro il codice. Impostala come variabile d'ambiente:

export OPENAI_API_KEY="sk-..."   # su Windows: setx OPENAI_API_KEY "sk-..."

La libreria la legge in automatico. Cosi' eviti di pubblicare per errore la chiave su GitHub, l'errore piu' comune e piu' costoso di chi inizia.

Passo 2: la prima richiesta

Ecco l'esempio minimo. Chiediamo al modello un breve testo e stampiamo la risposta:

from openai import OpenAI

client = OpenAI()   # legge OPENAI_API_KEY dall'ambiente

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[
        {"role": "system", "content": "Sei un assistente conciso che risponde in italiano."},
        {"role": "user", "content": "Spiega in due frasi cos'e' un token in un LLM."}
    ]
)
print(resp.choices[0].message.content)

Il system message definisce il comportamento generale, il user message e' la domanda. Il risultato atteso e' una spiegazione di due frasi in italiano. Il campo resp.usage ti dice quanti token hai speso: tienilo d'occhio per controllare i costi.

Passo 3: streaming, per mostrare la risposta man mano

Nelle chat conviene mostrare il testo mentre viene generato, invece di far aspettare l'utente. Basta attivare lo streaming:

stream = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Scrivi una filastrocca di 4 versi sull'estate."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Il testo compare pezzo dopo pezzo, come nell'interfaccia di ChatGPT. E' la differenza tra un'app che sembra reattiva e una che sembra bloccata.

Passo 4: output in JSON strutturato

Se il testo libero va bene per un essere umano, un programma ha bisogno di dati ordinati. Con l'output strutturato obblighi il modello a rispondere secondo uno schema preciso. Esempio: estrarre nome, prezzo e disponibilita' da una descrizione di prodotto.

from pydantic import BaseModel

class Prodotto(BaseModel):
    nome: str
    prezzo_eur: float
    disponibile: bool

completion = client.chat.completions.parse(
    model="gpt-5.6",
    messages=[
        {"role": "system", "content": "Estrai i dati del prodotto dal testo."},
        {"role": "user", "content": "Zaino trekking 40L, 79,90 euro, ora esaurito."}
    ],
    response_format=Prodotto,
)
p = completion.choices[0].message.parsed
print(p.nome, p.prezzo_eur, p.disponibile)

Il risultato atteso e' un oggetto con nome="Zaino trekking 40L", prezzo_eur=79.9, disponibile=False. Niente parsing fragile del testo: ottieni direttamente dati tipizzati.

Passo 5: function calling, l'IA che usa i tuoi strumenti

Il function calling permette al modello di richiedere l'esecuzione di una tua funzione — cercare in un database, interrogare un'API meteo, inviare un'email — passando i parametri giusti. Il modello non esegue nulla: ti dice cosa chiamare e con quali argomenti, poi il tuo codice esegue e restituisce il risultato.

tools = [{
    "type": "function",
    "function": {
        "name": "meteo",
        "description": "Restituisce il meteo di una citta'",
        "parameters": {
            "type": "object",
            "properties": {"citta": {"type": "string"}},
            "required": ["citta"]
        }
    }
}]

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Che tempo fa a Milano?"}],
    tools=tools,
)
call = resp.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
# -> meteo {"citta": "Milano"}

Da qui esegui la tua funzione meteo("Milano"), rimandi il risultato al modello con un messaggio di ruolo tool e ottieni la risposta finale in linguaggio naturale. E' il meccanismo alla base degli agenti IA.

Passo 6: una conversazione con memoria

Le API sono "senza stato": ogni chiamata non ricorda le precedenti. Per costruire un chatbot che tiene il filo del discorso devi rimandare tu, ogni volta, l'intera cronologia dei messaggi. Ecco un ciclo minimo di conversazione da terminale:

from openai import OpenAI

client = OpenAI()
storia = [{"role": "system", "content": "Sei un tutor di italiano paziente."}]

while True:
    testo = input("Tu: ")
    if testo.strip() == "esci":
        break
    storia.append({"role": "user", "content": testo})
    resp = client.chat.completions.create(model="gpt-5.6", messages=storia)
    risposta = resp.choices[0].message.content
    print("Assistente:", risposta)
    storia.append({"role": "assistant", "content": risposta})

Il trucco e' la lista storia: a ogni giro aggiungi il messaggio dell'utente, ottieni la risposta e la riaggiungi. Attenzione pero': piu' lunga diventa la conversazione, piu' token invii ogni volta, e piu' spendi. Nelle app reali si limita la cronologia (per esempio agli ultimi N scambi) o se ne fa un riassunto periodico.

Consiglio pratico: scegliere la variante e regolare il costo

La famiglia GPT-5.6 offre varianti di potenza e prezzo diversi (Luna, Terra, Sol). Il consiglio e' iniziare a sviluppare con la variante piu' economica: se i risultati bastano, hai risparmiato; se non bastano, sali di livello solo per i compiti che lo richiedono. Un altro parametro utile e' la lunghezza massima della risposta, che limita quanti token il modello puo' generare ed evita output (e costi) fuori controllo:

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Riassumi in massimo 3 righe."}],
    max_completion_tokens=200,
)

Combinare la variante giusta, un tetto ai token in uscita e l'output strutturato dove serve e' la ricetta per tenere insieme qualita' e budget.

Errori comuni e come risolverli

• AuthenticationError / 401: la chiave non e' impostata o e' errata. Verifica echo $OPENAI_API_KEY e rigenera la chiave se necessario.
• RateLimitError / 429: troppe richieste o credito esaurito. Aggiungi attese progressive (backoff) tra i tentativi e controlla il credito residuo nel cruscotto.
• Il modello non rispetta il formato: usa l'output strutturato (Passo 4) invece di chiedere "rispondi in JSON" nel prompt; e' molto piu' affidabile.
• Costi a sorpresa: imposta un limite di spesa mensile nelle impostazioni dell'account e monitora resp.usage.

Buone pratiche per prompt affidabili

La qualita' delle risposte dipende molto da come formuli le istruzioni. Alcune regole che fanno la differenza in produzione:

• Sii esplicito sul formato: se ti serve un elenco, chiedi "rispondi con un elenco puntato di massimo 5 voci". Per dati destinati a un programma, usa sempre l'output strutturato del Passo 4.
• Metti le istruzioni nel system message: il ruolo, il tono, i vincoli (lingua, lunghezza, cosa non fare) vanno nel messaggio di sistema, non ripetuti a ogni domanda.
• Dai esempi: mostrare uno o due esempi di input e output desiderato (la tecnica "few-shot") migliora molto la coerenza su compiti ripetitivi.
• Chiedi di ragionare quando serve: per problemi complessi, invitare il modello a procedere per passi prima di dare la risposta finale riduce gli errori; per compiti semplici, invece, e' spreco di token.

Un esempio di system message robusto per un classificatore:

Sei un classificatore di ticket di assistenza. Assegna a ogni messaggio una sola categoria tra: FATTURAZIONE, TECNICO, COMMERCIALE, ALTRO. Rispondi esclusivamente con la categoria in maiuscolo, senza spiegazioni.

Con istruzioni cosi' nette, unite all'output strutturato, ottieni risposte prevedibili e facili da elaborare nel resto del programma.

Alternative e quando non usare OpenAI

Le API OpenAI sono un ottimo punto di partenza, ma non l'unica scelta. Per ridurre i costi su grandi volumi valuta modelli aperti come DeepSeek via API o eseguiti in locale con Ollama; per restare nell'ecosistema Google ci sono le API di Gemini, per Anthropic quelle di Claude. La buona notizia e' che molti fornitori adottano un'interfaccia compatibile con quella di OpenAI: spesso basta cambiare base_url e chiave per puntare a un altro modello, riusando lo stesso codice. Se i tuoi dati sono particolarmente sensibili e non possono uscire dalla tua rete, l'esecuzione in locale e' la strada da preferire.

Come proseguire

Con questi cinque mattoni — richiesta base, streaming, JSON strutturato e function calling — hai gia' tutto per costruire strumenti reali. I passi successivi naturali sono la gestione della cronologia della conversazione (per chatbot con memoria), l'aggiunta di una base di conoscenza tramite RAG per rispondere sui tuoi documenti, e l'orchestrazione di piu' chiamate a funzione per creare un agente autonomo. La documentazione ufficiale di OpenAI resta il riferimento da tenere sempre aperto, perche' modelli e funzioni evolvono in fretta.