Dopo aver dedicato due guide alle API di Claude e di Gemini, completiamo il trittico dei grandi modelli con OpenAI. In questo tutorial impari a usare le API di OpenAI in Python partendo da zero: dalla prima chiamata allo streaming, dal "function calling" alle risposte in formato strutturato, fino al controllo dei costi e agli errori più frequenti. Alla fine avrai gli strumenti per integrare GPT nei tuoi script e nelle tue applicazioni.

A chi serve e cosa ti serve prima di iniziare

Questa guida è per chi conosce le basi di Python e vuole costruire qualcosa con l'IA: automazioni, chatbot, strumenti di analisi del testo. Non servono competenze di machine learning. I prerequisiti sono concreti:

  • Python 3.8 o superiore installato sul tuo sistema (Windows, macOS o Linux).
  • Un account su platform.openai.com con un metodo di pagamento attivo: le API sono a consumo e, a differenza di ChatGPT, non sono incluse nell'abbonamento. Si parte da pochi dollari di credito.
  • Una chiave API, che generi dalla sezione "API keys" del tuo account. Copiala subito: viene mostrata una sola volta.

Quale modello scegliere e quanto costa

OpenAI offre una gamma di modelli con un compromesso tra capacità, velocità e prezzo. Per i compiti complessi (ragionamento, codice difficile) c'è il modello di punta della famiglia GPT-5; per la maggior parte dei compiti pratici — riassunti, classificazioni, estrazione di dati, risposte a domande — conviene una variante più piccola e veloce, di gran lunga più economica. La regola d'oro: parti dal modello più piccolo e sali solo se la qualità non basta.

I prezzi si misurano in dollari per milione di token (un token equivale grosso modo a 4 caratteri, ovvero circa tre quarti di una parola in inglese). Si paga sia per i token in ingresso, cioè il tuo prompt, sia per quelli in uscita generati dal modello. Tenere prompt concisi e limitare la lunghezza delle risposte è il primo modo per contenere la spesa. La prima scelta per iniziare a sperimentare è quindi una variante economica e veloce: costa pochissimo e copre la grande maggioranza dei casi d'uso.

Le API di OpenAI si usano in pochi minuti con la libreria ufficiale per Python.

Passo 1: installare la libreria e impostare la chiave

Apri il terminale e installa la libreria ufficiale:

pip install openai

Non scrivere mai la chiave dentro il codice, soprattutto se lo condividi o lo pubblichi su GitHub. Impostala invece come variabile d'ambiente. Su macOS e Linux:

export OPENAI_API_KEY="la-tua-chiave"

Su Windows (PowerShell):

setx OPENAI_API_KEY "la-tua-chiave"

La libreria leggerà automaticamente questa variabile, così la chiave resta fuori dal codice.

Passo 2: la prima chiamata

Creiamo lo script di base. La libreria moderna usa l'interfaccia responses, semplice e consigliata per i nuovi progetti:

from openai import OpenAI

client = OpenAI()  # legge la chiave dalla variabile d'ambiente

risposta = client.responses.create(
    model="gpt-5-mini",
    input="Spiega in 3 frasi cosa sono i token in un modello linguistico.",
)

print(risposta.output_text)

Il risultato atteso è una spiegazione di tre frasi in italiano. Se vuoi guidare il comportamento del modello con un'istruzione di sistema (il "ruolo" che deve interpretare), usa il parametro instructions:

risposta = client.responses.create(
    model="gpt-5-mini",
    instructions="Sei un divulgatore tecnologico. Rispondi in italiano semplice, senza tecnicismi inutili.",
    input="Cos'e' un'API?",
)
print(risposta.output_text)

Passo 3: lo streaming, per risposte in tempo reale

Se costruisci una chat o un'interfaccia, aspettare l'intera risposta dà una sensazione di lentezza. Con lo streaming il testo arriva pezzo per pezzo, come accade in ChatGPT:

stream = client.responses.create(
    model="gpt-5-mini",
    input="Scrivi una breve poesia sull'estate italiana.",
    stream=True,
)

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

Vedrai la poesia comparire parola dopo parola nel terminale. È lo stesso meccanismo che rende fluide le applicazioni conversazionali.

Lo streaming fa apparire la risposta gradualmente, migliorando l'esperienza utente.

Passo 4: function calling, far agire il modello

Il "function calling" (o tool use) è ciò che trasforma un chatbot in un assistente capace di agire: il modello, invece di rispondere a parole, può decidere di chiamare una tua funzione, per esempio per consultare un meteo, un database o un'API esterna. Tu definisci gli strumenti disponibili, il modello sceglie quando usarli.

tools = [{
    "type": "function",
    "name": "get_meteo",
    "description": "Restituisce il meteo attuale per una citta",
    "parameters": {
        "type": "object",
        "properties": {
            "citta": {"type": "string", "description": "Nome della citta"}
        },
        "required": ["citta"],
    },
}]

risposta = client.responses.create(
    model="gpt-5-mini",
    input="Che tempo fa a Milano?",
    tools=tools,
)

# Il modello non inventa il meteo: chiede di eseguire get_meteo con citta="Milano"
print(risposta.output)

Nell'output troverai la richiesta del modello di chiamare get_meteo con l'argomento citta="Milano". Sta a te eseguire la funzione reale (per esempio interrogando un servizio meteo), restituire il risultato al modello e ottenere la risposta finale in linguaggio naturale. È il mattone fondamentale di qualunque agente.

Passo 5: ottenere risposte in formato strutturato

Spesso non vuoi testo libero, ma dati pronti da usare nel programma, in JSON. Con i "structured outputs" puoi imporre uno schema preciso, così la risposta è sempre nel formato atteso:

risposta = client.responses.create(
    model="gpt-5-mini",
    input="Estrai nome, eta e citta da: 'Mi chiamo Anna, ho 34 anni e vivo a Torino.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "persona",
            "schema": {
                "type": "object",
                "properties": {
                    "nome": {"type": "string"},
                    "eta": {"type": "integer"},
                    "citta": {"type": "string"},
                },
                "required": ["nome", "eta", "citta"],
                "additionalProperties": False,
            },
        }
    },
)
print(risposta.output_text)

Il risultato atteso è esattamente {"nome": "Anna", "eta": 34, "citta": "Torino"}, che puoi caricare con json.loads() e usare direttamente. È utilissimo per estrazione dati, classificazioni e qualsiasi pipeline automatica.

Errori comuni e come risolverli

  • 401 - "Incorrect API key provided": la chiave è sbagliata o la variabile d'ambiente non è impostata. Verifica con echo $OPENAI_API_KEY e rigenera la chiave se necessario.
  • 429 - "Rate limit" o "insufficient_quota": hai superato il limite di richieste o esaurito il credito. Aggiungi credito all'account o rallenta le chiamate; in caso di picchi, implementa un breve ritardo crescente tra i tentativi.
  • 404 - "model not found": il nome del modello è errato o non disponibile per il tuo account. Controlla l'elenco aggiornato dei modelli nella documentazione.
  • Risposte troncate: imposta un limite di token di output più alto con max_output_tokens se le risposte si interrompono a metà.

Come contenere i costi e quando scegliere un'alternativa

Per spendere poco: usa il modello più piccolo adeguato, accorcia i prompt, limita la lunghezza delle risposte e attiva il "prompt caching" quando ripeti spesso istruzioni lunghe e identiche. Tieni d'occhio il cruscotto dei consumi sul sito di OpenAI e imposta un limite di spesa mensile per evitare sorprese.

Le API di OpenAI sono un'ottima scelta per qualità, ricchezza dell'ecosistema e documentazione. Ma non sono l'unica: per costi ancora più bassi puoi guardare a DeepSeek o ai modelli aperti cinesi, per la massima privacy a un modello locale con Ollama, per compiti specifici a Claude (ottimo sul codice) o Gemini (forte sul multimodale e sui contesti lunghissimi). Il bello è che quasi tutti questi servizi adottano un'interfaccia compatibile con quella di OpenAI: il codice che hai scritto qui ti servirà, con minime modifiche, anche con gli altri. Da qui puoi proseguire costruendo un vero agente che combina function calling e structured output, oppure un'applicazione web che usa lo streaming per una chat fluida.