Integrare un modello di OpenAI in un proprio programma e' oggi questione di poche righe di Python, ma per farlo bene – controllando costi, errori e formato delle risposte – serve conoscere qualche accorgimento. In questa guida partiamo dalla creazione della chiave API e arriviamo a costruire chiamate avanzate ai modelli della famiglia GPT-5.6: risposte in streaming, output strutturato in JSON e chiamata di strumenti (function calling). Tutto con codice funzionante e pronto da adattare.

A chi serve, prerequisiti e una premessa sui costi

La guida e' per sviluppatori, anche alle prime armi, che vogliono usare i modelli di OpenAI dentro app, script o automazioni. Ti serve: Python 3.9 o superiore; un account su platform.openai.com; una chiave API; e un metodo di pagamento configurato, perche' le API sono a consumo (si paga per token elaborati) e sono separate dall'abbonamento di ChatGPT. Una premessa importante: prima di lanciare cicli automatici imposta un tetto di spesa nella dashboard, cosi' eviti sorprese. La famiglia GPT-5.6 offre piu' livelli – il modello di punta Sol, l'intermedio Terra e l'economico Luna – con prezzi molto diversi: la scelta del modello e' la leva principale sul costo.

Passo 1: creare la chiave API e proteggerla

Accedi a platform.openai.com, vai nella sezione delle API key e generane una nuova. Copiala subito: non sara' piu' visibile per intero. Regola d'oro: non scrivere mai la chiave nel codice sorgente e non caricarla su GitHub. Salvala invece in una variabile d'ambiente. Su macOS/Linux:

export OPENAI_API_KEY="la-tua-chiave"

Su Windows (PowerShell):

setx OPENAI_API_KEY "la-tua-chiave"

In alternativa, per un progetto, crea un file .env (da aggiungere a .gitignore) e caricalo con la libreria python-dotenv.

Passo 2: installare l'SDK e la prima chiamata

Installa la libreria ufficiale:

pip install openai

La prima chiamata: il client legge automaticamente la chiave dalla variabile d'ambiente. Qui usiamo il modello di fascia intermedia; sostituisci l'identificativo del modello con quello indicato nella documentazione per la versione che vuoi usare.

from openai import OpenAI

client = OpenAI()   # legge OPENAI_API_KEY dall'ambiente

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

Il messaggio system definisce il comportamento dell'assistente; quello user contiene la domanda. La risposta si trova in choices[0].message.content. Se ottieni un testo sensato, l'integrazione funziona.

Poche righe bastano per la prima chiamata; il resto e' controllo di costi, formato ed errori.

Passo 3: risposte in streaming

Per le interfacce conversazionali conviene mostrare il testo mentre viene generato, invece di attendere la risposta completa. Basta attivare stream=True e iterare sui frammenti:

flusso = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Scrivi una breve poesia sull'estate."}],
    stream=True
)
for pezzo in flusso:
    delta = pezzo.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Passo 4: ottenere output in JSON

Quando la risposta deve essere elaborata da un programma, il testo libero e' scomodo. Puoi chiedere un output in JSON valido impostando response_format. Ricorda di istruire il modello, anche nel prompt, sulla struttura desiderata.

import json

risposta = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "Rispondi solo con JSON valido."},
        {"role": "user", "content": "Estrai nome, citta' e professione da: 'Sono Luca, faccio il medico a Bologna'."}
    ],
    response_format={"type": "json_object"}
)
dati = json.loads(risposta.choices[0].message.content)
print(dati["citta"])   # -> Bologna

Il risultato atteso e' un oggetto come {"nome": "Luca", "citta": "Bologna", "professione": "medico"}, direttamente utilizzabile nel codice.

Passo 5: far chiamare strumenti al modello (function calling)

La funzione piu' potente e' il tool calling: descrivi al modello alcune funzioni del tuo codice, e lui decide quando invocarle passandoti gli argomenti giusti. E' la base degli agenti. Ecco lo schema essenziale:

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

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

chiamata = risposta.choices[0].message.tool_calls[0]
print(chiamata.function.name)        # -> meteo_attuale
print(chiamata.function.arguments)   # -> {"citta": "Napoli"}

A questo punto sta al tuo codice eseguire davvero la funzione meteo_attuale, prendere il risultato e rimandarlo al modello in un secondo giro affinche' formuli la risposta finale all'utente. Il modello non esegue nulla da solo: si limita a dirti quale strumento userebbe e con quali parametri.

Controllare i costi e scegliere il modello giusto

Ogni chiamata consuma token in ingresso (il tuo prompt) e in uscita (la risposta), e si paga per entrambi. Alcune buone pratiche: usa il modello piu' economico che risolve il compito (Luna per compiti semplici e ad alto volume, Terra come compromesso, Sol solo quando serve il massimo ragionamento); limita la lunghezza della risposta con max_tokens; accorcia i prompt e non inviare cronologie inutilmente lunghe; e monitora la spesa nella dashboard. Puoi anche leggere il consumo effettivo di ogni chiamata nel campo usage della risposta.

Errori comuni e come risolverli

  • AuthenticationError: la chiave e' errata o non caricata. Controlla la variabile d'ambiente e di aver riavviato il terminale.
  • RateLimitError: troppe richieste in poco tempo o credito esaurito. Introduci una pausa tra le chiamate (backoff) e verifica il saldo.
  • Model not found: l'identificativo del modello e' sbagliato o non disponibile per il tuo account. Controlla il nome esatto nella documentazione.
  • JSON non valido: se non usi response_format, il modello puo' aggiungere testo attorno al JSON. Attiva la modalita' JSON e sii esplicito nel prompt.

Alternative e quando non usare le API di OpenAI

Le API di OpenAI non sono l'unica scelta. Per compiti diversi puo' convenire Claude di Anthropic (forte su testi lunghi e ragionamento), Gemini di Google (quota gratuita generosa e ottima integrazione con l'ecosistema Google) o, quando contano privacy e costi, modelli aperti eseguiti in locale con Ollama. Evita le API a consumo se tratti dati altamente sensibili senza le opportune garanzie contrattuali, se hai bisogno di funzionare offline, o se il volume e' cosi' alto da rendere piu' conveniente un modello ospitato in proprio. Per i dettagli sempre aggiornati su modelli, prezzi e parametri, fai riferimento alla documentazione ufficiale e al repository openai-python.