API di OpenAI in Python: la guida pratica da zero

Saper chiamare un modello di OpenAI da Python apre un mondo: puoi costruire chatbot, automatizzare la scrittura di email, estrarre dati da documenti, creare piccoli assistenti su misura. La buona notizia e' che servono poche righe di codice. In questa guida partiamo da zero — chiave API, prima chiamata — e arriviamo a streaming e function calling, con esempi che puoi copiare e far girare subito.

A chi serve e cosa ti occorre

La guida e' pensata per chi conosce le basi di Python (variabili, funzioni, un minimo di terminale) e vuole iniziare a usare i modelli GPT in modo programmatico, non solo dall'interfaccia di ChatGPT. Ti serviranno tre cose:

• Python 3.8 o superiore.
• Un account su platform.openai.com e una chiave API (la crei dalla sezione «API keys»).
• Crediti sul tuo account: l'uso delle API e' a pagamento, a consumo. Attenzione: e' diverso dall'abbonamento a ChatGPT, che non include l'accesso alle API.

Sui costi: si paga per «token» (frammenti di parole), distinguendo tra input e output. I modelli piu' piccoli della famiglia (le varianti «mini») costano una frazione di quelli di punta e sono piu' che sufficienti per la maggior parte dei compiti. Imposta sempre un limite di spesa nelle impostazioni dell'account per evitare sorprese.

Quale modello scegliere

OpenAI aggiorna spesso il catalogo: i nomi esatti cambiano nel tempo, quindi la regola d'oro e' consultare la pagina Models della documentazione e scegliere l'identificativo aggiornato. Come criterio: per chat e compiti generali usa il modello di punta della famiglia GPT-5; per compiti semplici, ad alto volume o sensibili al costo, scegli la variante «mini», molto piu' economica e quasi sempre adeguata. Negli esempi useremo una costante MODELLO che puoi cambiare con il nome corrente.

Passo 1: installazione e chiave API

Installa la libreria ufficiale in un ambiente virtuale:

python -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, cosi' non finisce per sbaglio su GitHub. Su macOS/Linux:

export OPENAI_API_KEY="la-tua-chiave"

Su Windows (PowerShell):

setx OPENAI_API_KEY "la-tua-chiave"

La libreria legge automaticamente questa variabile.

Passo 2: la prima chiamata

OpenAI offre due interfacce. La piu' recente e' la Responses API, consigliata per i nuovi progetti. Ecco l'esempio minimo:

from openai import OpenAI

client = OpenAI()
MODELLO = "gpt-5.1-mini"  # sostituisci con il modello corrente

risposta = client.responses.create(
    model=MODELLO,
    input="Spiega in tre frasi semplici cos'e' un token in un modello linguistico."
)

print(risposta.output_text)

L'attributo output_text contiene la risposta gia' pronta come stringa. Se lo esegui, otterrai una spiegazione concisa in italiano. Questa e' di fatto la «Hello World» delle API di OpenAI.

Passo 3: conversazioni e ruoli con Chat Completions

Molti progetti usano ancora la storica Chat Completions API, perfetta per gestire conversazioni a piu' turni con i ruoli system (le istruzioni di fondo), user (l'utente) e assistant (le risposte precedenti del modello):

from openai import OpenAI

client = OpenAI()
MODELLO = "gpt-5.1-mini"

messaggi = [
    {"role": "system", "content": "Sei un assistente che risponde in italiano, conciso e professionale."},
    {"role": "user", "content": "Scrivimi tre idee di titolo per un articolo sull'auto elettrica."},
]

risposta = client.chat.completions.create(model=MODELLO, messages=messaggi)
print(risposta.choices[0].message.content)

Per continuare la conversazione, aggiungi la risposta del modello alla lista messaggi con ruolo assistant e poi il nuovo messaggio dell'utente: e' cosi' che il modello «ricorda» il contesto, perche' ogni chiamata e' di per se' senza memoria.

Passo 4: risposte in streaming (come ChatGPT)

Per far comparire il testo parola per parola, invece di attendere l'intera risposta, attiva lo streaming. Con la Responses API:

stream = client.responses.create(
    model=MODELLO,
    input="Racconta una breve storia sulla nascita di Internet.",
    stream=True,
)

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

Il testo appare progressivamente, migliorando l'esperienza nelle interfacce interattive. Lo streaming non riduce il costo, ma riduce la percezione di attesa.

Passo 5: function calling, far «agire» il modello

Il salto di qualita' e' il function calling: dichiari delle funzioni e il modello, quando serve, ti dice quale chiamare e con quali argomenti. E' la base degli agenti e dei chatbot collegati a dati reali. Esempio con una funzione meteo fittizia:

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

risposta = client.chat.completions.create(
    model=MODELLO,
    messages=[{"role": "user", "content": "Che tempo fa a Milano?"}],
    tools=strumenti,
)

chiamata = risposta.choices[0].message.tool_calls[0]
print(chiamata.function.name)       # get_meteo
print(chiamata.function.arguments)  # {"citta": "Milano"}

Il modello non esegue la funzione: ti restituisce nome e argomenti. Tocca al tuo codice eseguirla (chiamando una vera API meteo), poi rimandi il risultato al modello, che produce la risposta finale in linguaggio naturale. E' questo schema — il modello decide, il tuo codice agisce — a rendere possibili gli assistenti utili.

Tre prompt utili da provare subito

Cambiando solo il contenuto del messaggio user, puoi riutilizzare gli esempi sopra per compiti concreti. Eccone tre da copiare:

Riassumi il seguente testo in 5 punti elenco, in italiano, mantenendo i dati numerici: [incolla qui il testo]

Estrai da questa email nome, azienda, richiesta e urgenza (alta/media/bassa) e restituiscili in formato JSON: [incolla qui l'email]

Agisci da revisore: correggi gli errori di grammatica e migliora la scorrevolezza di questo paragrafo, senza cambiarne il significato: [testo]

Per il secondo, in particolare, conviene istruire il modello (nel ruolo system) a rispondere solo con JSON valido: e' il modo piu' semplice per integrare l'output nel tuo programma.

Errori comuni e soluzioni

• «AuthenticationError» / 401: la chiave non e' impostata o e' sbagliata. Verifica la variabile d'ambiente e di aver riaperto il terminale.
• «RateLimitError» / 429: troppe richieste, oppure credito esaurito. Controlla il saldo e, nel codice, inserisci una breve attesa e un nuovo tentativo.
• «model not found»: il nome del modello non e' valido o non e' disponibile per il tuo account. Controlla l'elenco aggiornato nella documentazione.
• Costi piu' alti del previsto: stai usando un modello di punta per compiti banali. Passa alla variante «mini» e accorcia i prompt.

Alternative e quando preferirle

Le API di OpenAI non sono l'unica strada. Se ti servono finestre di contesto enormi o un buon rapporto qualita'-prezzo, valuta le API di Anthropic (Claude) o di Google (Gemini); se vuoi spendere poco o lavorare con modelli aperti, DeepSeek e i modelli eseguibili in locale con Ollama sono ottime opzioni, e su AI Notizie trovi guide dedicate a entrambe. La logica del codice resta molto simile: cambiano la libreria e i nomi dei modelli. Iniziare da OpenAI ha pero' il vantaggio di una documentazione ricca e di una community enorme, ideale per imparare.

Da qui puoi proseguire costruendo una piccola interfaccia web (con Streamlit o Flask), aggiungendo la memoria delle conversazioni in un database, o collegando il function calling a strumenti reali per creare il tuo primo agente. La documentazione ufficiale e il repository openai-python su GitHub sono i riferimenti da tenere sempre aperti.