API di OpenAI in Python: guida pratica per iniziare

Dopo le guide alle API di Claude e di Gemini, completiamo il quadro con la piattaforma piu' usata: le API di OpenAI in Python. Al termine di questo tutorial saprai fare la tua prima chiamata a un modello GPT, gestire lo streaming delle risposte, far chiamare funzioni al modello (tool use) e ottenere output in JSON strutturato, con attenzione ai costi e agli errori piu' comuni. E' una guida pratica di livello intermedio.

A chi serve e prerequisiti

Questa guida e' per sviluppatori e appassionati che vogliono integrare i modelli di OpenAI nelle proprie applicazioni: chatbot, automazioni, estrazione di dati, assistenti. Ti servono:

• Un account OpenAI e una chiave API creata dalla dashboard (platform.openai.com). Le API sono a pagamento a consumo: serve del credito caricato.
• Python 3.9 o superiore e un minimo di dimestichezza con il terminale.
• Consapevolezza dei costi: si paga per token (parti di parola) in ingresso e in uscita. Controlla sempre la pagina prezzi ufficiale prima di lanciare processi grossi.

Quale modello scegliere

OpenAI offre piu' modelli con costi e capacita' diversi. Ad agosto 2026 la famiglia di punta e' GPT-5.6, con varianti ottimizzate per compiti rapidi o per il ragionamento. La regola pratica: usa un modello piu' piccolo ed economico per compiti semplici (classificazione, estrazione, riassunti brevi) e riserva quelli piu' capaci ai compiti complessi. I nomi esatti dei modelli cambiano nel tempo: verifica sempre l'identificatore corrente nella pagina "Models" della documentazione e sostituiscilo negli esempi qui sotto.

Installazione e prima chiamata

Installa la libreria ufficiale:

pip install -U openai

Non scrivere mai la chiave API nel codice. Impostala come variabile d'ambiente:

# Linux/Mac
export OPENAI_API_KEY="sk-..."
# Windows (PowerShell)
setx OPENAI_API_KEY "sk-..."

Ora la prima chiamata. La libreria legge la chiave dall'ambiente automaticamente:

from openai import OpenAI

client = OpenAI()

resp = client.chat.completions.create(
    model="gpt-5.6",  # sostituisci con il modello attuale
    messages=[
        {"role": "system", "content": "Sei un assistente conciso che risponde in italiano."},
        {"role": "user", "content": "Elenca 3 vantaggi dell'energia solare."},
    ],
)
print(resp.choices[0].message.content)

Risultato atteso: un elenco di tre vantaggi (per esempio fonte rinnovabile, costi in calo, bassa manutenzione). Il messaggio "system" definisce il comportamento, quello "user" e' la domanda.

Streaming: risposte in tempo reale

Per far comparire il testo man mano che viene generato, come in ChatGPT, attiva lo streaming:

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

Risultato atteso: la poesia appare parola dopo parola nel terminale, migliorando l'esperienza percepita nelle interfacce interattive.

Function calling: far agire il modello

Il modello puo' decidere di chiamare una tua funzione, per esempio per cercare dati o interrogare un servizio. Tu descrivi gli strumenti disponibili; il modello, se serve, risponde con la richiesta di eseguirli.

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

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Che tempo fa a Milano?"}],
    tools=tools,
)
call = resp.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

Risultato atteso: il modello non inventa il meteo, ma restituisce il nome della funzione meteo e gli argomenti in JSON, per esempio {"citta": "Milano"}. A quel punto esegui tu la funzione reale e reinvii il risultato al modello in un secondo giro di conversazione.

Output strutturato in JSON

Quando ti serve una risposta che il tuo programma possa leggere senza ambiguita', chiedi un formato JSON vincolato a uno schema:

schema = {
    "type": "object",
    "properties": {
        "titolo": {"type": "string"},
        "sentiment": {"type": "string", "enum": ["positivo", "neutro", "negativo"]},
    },
    "required": ["titolo", "sentiment"],
    "additionalProperties": False,
}

resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "Analizza: 'Il servizio clienti e' stato eccellente!'"}],
    response_format={"type": "json_schema", "json_schema": {"name": "analisi", "schema": schema}},
)
print(resp.choices[0].message.content)

Risultato atteso: un JSON valido del tipo {"titolo": "...", "sentiment": "positivo"}, pronto da caricare con json.loads(). E' il modo affidabile per usare l'IA dentro pipeline automatiche.

Conversazioni con memoria (multi-turno)

I modelli non ricordano nulla tra una chiamata e l'altra: la "memoria" la costruisci tu, accodando i messaggi precedenti nella lista che invii. Ogni volta rimandi l'intera cronologia, cosi' il modello ha il contesto completo. Ecco lo schema di un piccolo assistente conversazionale da terminale:

from openai import OpenAI

client = OpenAI()
history = [{"role": "system", "content": "Sei un tutor di italiano paziente e chiaro."}]

while True:
    domanda = input("Tu: ")
    if domanda.strip().lower() in {"esci", "quit"}:
        break
    history.append({"role": "user", "content": domanda})
    resp = client.chat.completions.create(model="gpt-5.6", messages=history)
    risposta = resp.choices[0].message.content
    print("Assistente:", risposta)
    history.append({"role": "assistant", "content": risposta})

Risultato atteso: un dialogo in cui l'assistente ricorda cosa e' stato detto prima, perche' a ogni giro gli reinvii tutta la cronologia. Attenzione pero': piu' lunga e' la cronologia, piu' token consumi a ogni chiamata. Nelle applicazioni reali si "riassume" o si tagliano i messaggi piu' vecchi per tenere sotto controllo costi e limiti di contesto.

Costi, errori comuni e buone pratiche

• AuthenticationError: la chiave e' assente o sbagliata. Verifica la variabile d'ambiente OPENAI_API_KEY.
• RateLimitError / insufficient_quota: hai superato i limiti o finito il credito. Aggiungi fondi o gestisci i tentativi con attese progressive (backoff).
• Costi che salgono: limita la lunghezza delle risposte con max_tokens, accorcia i prompt e scegli il modello piu' piccolo adatto al compito.
• Sicurezza: mai committare la chiave su GitHub; usa variabili d'ambiente o un gestore di segreti. Ruota la chiave se sospetti che sia stata esposta.

Alternative e come proseguire

Le API di OpenAI non sono l'unica scelta: per molti compiti Claude di Anthropic e Gemini di Google offrono qualita' e prezzi competitivi, e la struttura del codice e' molto simile (trovi le nostre guide dedicate sul sito). Se ti serve un modello gratuito o eseguito in locale, valuta modelli aperti con Ollama. Da qui, i passi successivi naturali sono: usare gli embeddings per la ricerca semantica e i sistemi RAG, gestire conversazioni con memoria, e costruire agenti che combinano piu' strumenti. La documentazione ufficiale di OpenAI e' il riferimento da tenere sempre aperto, perche' modelli, prezzi e funzioni cambiano di frequente.