Sapere usare ChatGPT dall'interfaccia web e' un conto; integrare i modelli di OpenAI dentro un proprio programma e' tutt'altra cosa, e apre possibilita' enormi: chatbot su misura, analisi automatica di documenti, estrazione di dati, agenti che usano strumenti. Questa guida mostra, con codice copiabile, come chiamare le API di OpenAI da Python, dal primo "ciao" fino a funzioni avanzate come output strutturato e tool calling.

A chi serve e cosa ti serve prima di iniziare

La guida e' pensata per chi sa programmare un minimo in Python ma non ha mai usato le API di un modello linguistico. Prerequisiti reali:

  • Python 3.9 o superiore installato sul vostro computer (Windows, macOS o Linux).
  • Un account OpenAI con un metodo di pagamento attivo: le API non sono incluse nell'abbonamento ChatGPT Plus e si pagano a consumo, in base ai token elaborati.
  • Una chiave API, da creare nella sezione "API keys" della dashboard su platform.openai.com.

Una nota sui costi: si paga per i token in ingresso e in uscita, con prezzi che variano molto da modello a modello. Prima di andare in produzione, controllate sempre i prezzi e i nomi dei modelli aggiornati sulla pagina ufficiale, perche' il catalogo cambia spesso. In questa guida useremo nomi di modello come esempio: sostituiteli con quelli attualmente disponibili nel vostro account.

Installazione e prima chiamata

Conviene lavorare in un ambiente virtuale per non sporcare il sistema:

python3 -m venv venv
source venv/bin/activate        # su Windows: venv\Scripts\activate
pip install --upgrade openai

Non scrivete mai la chiave dentro il codice: salvatela in una variabile d'ambiente, cosi' non rischiate di pubblicarla per errore su GitHub.

export OPENAI_API_KEY="la-tua-chiave"   # su Windows: setx OPENAI_API_KEY "la-tua-chiave"

La prima chiamata con l'SDK ufficiale. Il client legge automaticamente la variabile d'ambiente:

from openai import OpenAI

client = OpenAI()

resp = client.chat.completions.create(
    model="gpt-5.1",  # sostituisci con un modello disponibile nel tuo account
    messages=[
        {"role": "system", "content": "Sei un assistente conciso che risponde in italiano."},
        {"role": "user", "content": "Spiega in tre frasi cos'e' un'API."},
    ],
)
print(resp.choices[0].message.content)

Il system definisce il comportamento, lo user e' la domanda. La risposta del modello sta in resp.choices[0].message.content.

Tutto parte da un ambiente virtuale e dalla chiave salvata come variabile d'ambiente.

Streaming: la risposta che appare parola per parola

Per le applicazioni interattive (chat, assistenti) conviene ricevere la risposta in streaming, cosi' l'utente vede il testo comparire man mano invece di attendere tutto in blocco:

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

Output JSON: dati strutturati e affidabili

Quando vi serve un risultato che il programma deve elaborare - non testo libero ma dati - chiedete un output JSON conforme a uno schema. Cosi' il modello e' costretto a rispettare la struttura che indicate:

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

resp = client.chat.completions.create(
    model="gpt-5.1",
    messages=[{"role": "user", "content": "Analizza questa recensione: 'Ottimo prodotto, spedizione lenta.'"}],
    response_format={"type": "json_schema",
                     "json_schema": {"name": "analisi", "schema": schema, "strict": True}},
)
import json
print(json.loads(resp.choices[0].message.content))

Il risultato sara' un oggetto JSON con titolo, sentiment e parole chiave, pronto da usare nel resto del codice.

Tool calling: far usare strumenti al modello

Il tool calling (o function calling) permette al modello di chiedere al vostro programma di eseguire una funzione - per esempio consultare una banca dati o un servizio meteo - e di usare il risultato nella risposta. Si dichiarano gli strumenti disponibili e si gestisce la richiesta del modello:

tools = [{
    "type": "function",
    "function": {
        "name": "meteo_oggi",
        "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.1",
    messages=[{"role": "user", "content": "Che tempo fa a Torino?"}],
    tools=tools,
)
call = resp.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
# -> esegui la tua funzione con quegli argomenti e rimanda il risultato al modello

Il flusso completo prevede di eseguire la funzione e poi rinviare l'esito al modello con un messaggio di ruolo tool, in modo che formuli la risposta finale in linguaggio naturale.

Analisi di immagini (visione)

I modelli multimodali accettano anche immagini. Si passa un contenuto di tipo immagine, tramite URL o file codificato:

resp = client.chat.completions.create(
    model="gpt-5.1",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Cosa c'e' in questa foto?"},
            {"type": "image_url", "image_url": {"url": "https://esempio.it/foto.jpg"}},
        ],
    }],
)
print(resp.choices[0].message.content)

Errori comuni e come risolverli

  • 401 Unauthorized: la chiave e' errata o assente. Verificate la variabile d'ambiente con echo $OPENAI_API_KEY e di aver riavviato il terminale.
  • 429 Too Many Requests / insufficient_quota: avete superato il limite di frequenza oppure il credito e' esaurito. Aggiungete credito, oppure inserite un'attesa con backoff esponenziale tra i tentativi.
  • model_not_found: il nome del modello non esiste o non e' abilitato per il vostro account. Elencate i modelli disponibili con client.models.list() e usate un nome valido.
  • Risposte JSON non valide: se non usate response_format con schema, il modello puo' produrre testo intorno al JSON. Usate sempre lo schema con strict: True per i dati strutturati.

Quando NON usare le API e come proseguire

Se vi serve solo chattare occasionalmente, l'interfaccia web e' piu' semplice ed economica: le API hanno senso quando volete automatizzare, integrare in un prodotto o elaborare volumi. Per controllare la spesa, impostate un limite di budget mensile nella dashboard e tenete d'occhio i token. Da qui potete crescere verso la nuova Responses API (pensata per agenti e strumenti), l'uso degli embedding per la ricerca semantica e la costruzione di sistemi RAG sui vostri documenti. Il consiglio finale e' lo stesso valido per ogni modello: validate sempre l'output prima di usarlo in produzione, perche' un modello puo' sbagliare anche quando sembra sicuro.