Le API di OpenAI permettono di costruire applicazioni che usano modelli come GPT direttamente nel proprio codice: chatbot, classificatori, estrattori di dati, assistenti integrati nei prodotti. In questa guida partiamo da zero in Python e arriviamo a tre funzioni che fanno la differenza in un'applicazione reale: gli output strutturati (per ottenere dati in JSON affidabile), lo streaming (per mostrare la risposta mentre viene generata) e il function calling (per far chiamare al modello le tue funzioni). Tutto il codice è copiabile e commentato.

A chi serve e cosa ti serve prima di iniziare

La guida è adatta a chi sa scrivere un po' di Python e vuole integrare l'IA in uno script o in un servizio. Ti serviranno:

  • Un account su platform.openai.com e una chiave API (API key) generata dalla sezione dedicata.
  • Un metodo di pagamento configurato: le API sono a consumo, si paga per token elaborati. Esiste un sistema di crediti e limiti di spesa che conviene impostare subito.
  • Python 3.9 o superiore.

Quale modello usare? OpenAI offre una gamma di modelli: i più capaci (la famiglia GPT di punta, come GPT-5.5) per compiti complessi, e varianti più piccole ed economiche (i modelli «mini» e «nano») per compiti ad alto volume. Come prima scelta consigliamo di iniziare con un modello «mini»: costa poco, è veloce e basta per la maggior parte dei casi; si passa al modello grande solo se la qualità non è sufficiente. I nomi esatti e aggiornati dei modelli sono sulla pagina «Models» della documentazione: verificali lì prima di andare in produzione.

Passo 1: installazione e prima chiamata

Installa la libreria ufficiale e imposta la chiave come variabile d'ambiente (non scriverla mai nel codice):

pip install openai# Imposta la chiave (macOS/Linux):export OPENAI_API_KEY="la-tua-chiave"# Windows PowerShell:# setx OPENAI_API_KEY "la-tua-chiave"

La prima chiamata, con l'interfaccia Chat Completions:

from openai import OpenAIclient = OpenAI()  # legge automaticamente OPENAI_API_KEYresp = client.chat.completions.create(    model="gpt-5.4-mini",    messages=[        {"role": "system", "content": "Sei un assistente conciso che risponde in italiano."},        {"role": "user", "content": "Spiega cos'e' un token in due frasi."},    ],)print(resp.choices[0].message.content)

Il messaggio system definisce il comportamento dell'assistente, quello user è la domanda. La risposta è in resp.choices[0].message.content.

Bastano poche righe per la prima chiamata alle API di OpenAI.

Passo 2: streaming, per mostrare la risposta in tempo reale

Nelle interfacce di chat la risposta compare parola per parola. Si ottiene con stream=True, iterando sui frammenti man mano che arrivano:

stream = client.chat.completions.create(    model="gpt-5.4-mini",    messages=[{"role": "user", "content": "Scrivi una filastrocca di quattro versi sul mare."}],    stream=True,)for chunk in stream:    delta = chunk.choices[0].delta.content    if delta:        print(delta, end="", flush=True)print()

Lo streaming non riduce il costo, ma migliora molto l'esperienza percepita perché l'utente non resta davanti a una schermata vuota.

Passo 3: output strutturati, per ottenere JSON affidabile

Spesso non vuoi testo libero ma dati pronti da usare nel programma. Gli output strutturati garantiscono che la risposta rispetti uno schema preciso. Il modo più comodo in Python è definire lo schema con Pydantic e usare l'helper parse:

from pydantic import BaseModelclass Contatto(BaseModel):    nome: str    azienda: str    email: strresp = client.chat.completions.parse(    model="gpt-5.4-mini",    messages=[        {"role": "system", "content": "Estrai i dati di contatto dal testo."},        {"role": "user", "content": "Scrive Mario Rossi di Acme Srl, mario.rossi@acme.it"},    ],    response_format=Contatto,)contatto = resp.choices[0].message.parsedprint(contatto.nome, contatto.azienda, contatto.email)

Il risultato atteso è un oggetto Contatto già tipizzato: niente più parsing fragile del testo né errori di formato. È la base per estrarre dati da email, documenti, recensioni e trasformarli in righe di database.

Con gli output strutturati il modello restituisce dati validati secondo il tuo schema.

Passo 4: function calling, per far agire il modello

Il function calling permette al modello di decidere quando chiamare una tua funzione (per esempio per leggere il meteo, interrogare un database o inviare un'email) e con quali argomenti. Tu descrivi gli strumenti disponibili; il modello restituisce la richiesta di chiamata, tu la esegui e gli restituisci il risultato.

import jsondef meteo(citta):    # qui chiameresti una vera API meteo    return {"citta": citta, "gradi": 22, "cielo": "sereno"}tools = [{    "type": "function",    "function": {        "name": "meteo",        "description": "Restituisce il meteo attuale di una citta'",        "parameters": {            "type": "object",            "properties": {"citta": {"type": "string"}},            "required": ["citta"],        },    },}]messages = [{"role": "user", "content": "Che tempo fa a Bologna?"}]r = client.chat.completions.create(model="gpt-5.4-mini", messages=messages, tools=tools)call = r.choices[0].message.tool_calls[0]args = json.loads(call.function.arguments)risultato = meteo(**args)messages.append(r.choices[0].message)messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(risultato)})finale = client.chat.completions.create(model="gpt-5.4-mini", messages=messages, tools=tools)print(finale.choices[0].message.content)

Il modello capisce che deve chiamare meteo con citta="Bologna", tu esegui la funzione e gli passi i dati, lui formula la risposta finale in linguaggio naturale. È il meccanismo alla base degli «agenti».

Tenere sotto controllo i costi (e quando usare la Responses API)

Alcune buone pratiche per non avere sorprese in bolletta:

  • Usa il modello più piccolo che funziona: prova prima un «mini» o «nano», sali solo se serve.
  • Limita la lunghezza con max_tokens e tieni i prompt essenziali: paghi sia l'input sia l'output.
  • Imposta un limite di spesa nelle impostazioni dell'account.
  • Per grandi volumi non urgenti valuta la Batch API, che esegue le richieste in modo asincrono a costo ridotto.

Oltre a Chat Completions, OpenAI offre la più recente Responses API (client.responses.create), pensata per applicazioni agentiche e con strumenti integrati. Per iniziare, Chat Completions resta la via più semplice e documentata; la Responses API conviene quando costruisci agenti complessi con più strumenti.

Errori comuni e alternative

  • 401 Unauthorized: chiave mancante o errata. Verifica la variabile d'ambiente OPENAI_API_KEY.
  • 429 Too Many Requests / quota: hai superato i limiti o esaurito il credito. Aggiungi fondi o rallenta le richieste con una breve attesa tra l'una e l'altra.
  • «model not found»: il nome del modello non è corretto o non è disponibile sul tuo account. Controlla la pagina Models.
  • Risposte non valide come JSON: usa gli output strutturati invece di chiedere «rispondi in JSON» nel prompt: è molto più affidabile.

Quando NON usare le API di OpenAI? Se i dati sono particolarmente sensibili e non possono uscire dalla tua infrastruttura, valuta un modello aperto eseguito in locale (con Ollama o LM Studio); se cerchi il minor costo assoluto su grandi volumi, confronta anche modelli concorrenti come quelli di Anthropic, Google o i modelli aperti cinesi. La libreria openai ha comunque il vantaggio di un'interfaccia standard adottata anche da molti provider compatibili. Per approfondire, fai riferimento alla documentazione ufficiale di OpenAI.