Chiamare i modelli di OpenAI dal proprio codice e' il primo passo per costruire qualsiasi cosa: un assistente, un classificatore di email, un generatore di descrizioni prodotto, un piccolo agente. In questa guida vediamo, in modo concreto e con codice funzionante, come usare le API di OpenAI in Python: dalla chiave fino a streaming, output in JSON e chiamata di funzioni.

A chi serve e cosa ti serve prima di iniziare

La guida e' pensata per chi sa un minimo di Python (aprire un terminale, installare un pacchetto, lanciare uno script) e vuole integrare l'IA in un progetto. Serve:

  • Python 3.9 o superiore installato.
  • Un account su platform.openai.com con credito attivo (le API sono a pagamento, a consumo: si paga per numero di token elaborati; non basta l'abbonamento a ChatGPT).
  • Una chiave API, che si crea dalla sezione API keys del profilo.

Perche' OpenAI e non altri. I modelli GPT-5 restano tra i piu' solidi per compiti generici, ragionamento e uso di strumenti, con una documentazione ottima e un ecosistema enorme. Se pero' il tuo obiettivo e' spendere meno o lavorare in locale, valuta alternative come DeepSeek (molto economico e con SDK compatibile), i modelli aperti via Ollama, o Claude e Gemini per casi specifici. Qui restiamo su OpenAI perche' e' lo standard di riferimento e la sintassi che imparerai vale, con piccole modifiche, anche per gli altri.

1. Installazione e configurazione della chiave

Installa la libreria ufficiale e imposta la chiave come variabile d'ambiente (non scriverla mai dentro il codice che condividi):

pip install openai

# Linux / macOS
export OPENAI_API_KEY="sk-...la-tua-chiave..."

# Windows (PowerShell)
setx OPENAI_API_KEY "sk-...la-tua-chiave..."

La libreria legge automaticamente la variabile OPENAI_API_KEY, quindi non dovrai passarla a mano.

2. La prima chiamata

OpenAI offre due interfacce: la piu' recente Responses API e la classica Chat Completions. Partiamo dalla Responses API, oggi consigliata:

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5",           # usa l'ID del modello attuale dal tuo pannello
    input="Spiega in 3 frasi cos'e' un token in un modello linguistico."
)
print(resp.output_text)

Il campo output_text contiene la risposta pronta da stampare. Nota sui nomi dei modelli: gli identificativi cambiano nel tempo (gpt-5, versioni «mini» piu' economiche, ecc.). Controlla sempre la pagina Models del tuo account per l'ID esatto e i prezzi aggiornati.

Se preferisci la sintassi piu' diffusa negli esempi in rete, la Chat Completions funziona cosi':

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "Sei un assistente conciso e preciso."},
        {"role": "user", "content": "Dammi 3 idee per un titolo su un articolo dedicato all'IA."}
    ],
)
print(resp.choices[0].message.content)

3. Streaming: la risposta parola per parola

Per un'esperienza tipo «ChatGPT che scrive», attiva lo streaming e stampa i pezzi man mano che arrivano:

stream = client.responses.create(
    model="gpt-5",
    input="Scrivi una breve poesia sull'estate.",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Lo streaming migliora la percezione di velocita' e permette di mostrare subito qualcosa all'utente, utile nelle app con interfaccia.

4. Output in JSON strutturato

Quando ti serve un risultato che il programma deve leggere (non testo libero), chiedi un JSON con uno schema. Cosi' eviti di dover «ripulire» la risposta a mano:

from pydantic import BaseModel

class Estrazione(BaseModel):
    nome: str
    azienda: str
    sentiment: str

resp = client.responses.parse(
    model="gpt-5",
    input="Marco Rossi di Acme e' entusiasta del nuovo prodotto.",
    text_format=Estrazione,
)
dati = resp.output_parsed
print(dati.nome, dati.azienda, dati.sentiment)
# Atteso: Marco Rossi Acme positivo

Definendo lo schema con Pydantic, il modello e' vincolato a restituire esattamente quei campi: perfetto per estrarre informazioni da testi, popolare un database o alimentare un'altra funzione.

5. Tool calling: far usare al modello le tue funzioni

Il vero salto di qualita' e' dare al modello degli strumenti. Tu descrivi una funzione, il modello decide quando chiamarla e con quali argomenti, poi tu la esegui e restituisci il risultato:

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

resp = client.responses.create(
    model="gpt-5",
    input="Che tempo fa a Milano?",
    tools=tools,
)
# La risposta conterra' una chiamata a 'meteo' con {"citta": "Milano"}:
# la esegui tu nel tuo codice e reinvii il risultato al modello.

E' il mattone su cui si costruiscono gli agenti: il modello ragiona, sceglie lo strumento, tu lo esegui, e il ciclo continua finche' il compito e' completo.

6. Immagini in ingresso (visione)

I modelli GPT-5 leggono anche le immagini. Puoi passare un URL o un'immagine codificata e chiedere di descriverla o analizzarla:

resp = client.responses.create(
    model="gpt-5",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Cosa c'e' in questa foto?"},
            {"type": "input_image", "image_url": "https://esempio.it/foto.jpg"}
        ],
    }],
)
print(resp.output_text)

Errori comuni e come risolverli

  • «AuthenticationError»: la chiave non e' impostata o e' sbagliata. Verifica la variabile d'ambiente e rigenera la chiave se necessario.
  • «RateLimitError» o «insufficient_quota»: hai finito il credito o superato il limite di richieste. Controlla il saldo e imposta un piccolo retry con attesa progressiva.
  • «model_not_found»: l'ID del modello non e' corretto o non e' abilitato sul tuo account. Copialo dalla pagina Models.
  • Risposte troncate: aumenta il limite di token in uscita (parametro max_output_tokens) o accorcia il prompt.

Consigli per spendere meno e andare in produzione

Per contenere i costi: usa modelli piu' piccoli e veloci per i compiti semplici, tenendo il modello di punta solo dove serve; accorcia i prompt e riusa le istruzioni di sistema; attiva la prompt caching quando ripeti gli stessi contesti. Prima di andare online, gestisci sempre gli errori con blocchi try/except e un meccanismo di ripetizione, non registrare mai la chiave nei log e imposta un tetto di spesa mensile dal pannello. Da qui puoi proseguire integrando il tutto in un'app web con FastAPI, oppure collegando gli strumenti a un vero flusso agentico. La documentazione ufficiale su platform.openai.com/docs resta il riferimento per parametri e novita'.