La tua prima chiamata API a un LLM: guida pratica in Python
C'è un momento preciso in cui smetti di "usare l'AI" e inizi a "costruire con l'AI": è la prima volta che una tua riga di codice, e non un box di testo in un browser, ottiene una risposta da un modello. Ricordo la sensazione della prima chiamata andata a buon fine — tre righe di Python, invio, e nel terminale compare una frase generata da un modello che gira su un server dall'altra parte del mondo. Non c'era nessuna interfaccia, nessun bottone: solo il tuo codice che parla direttamente con il modello. Da lì in poi puoi automatizzare, integrare, ripetere mille volte quello che nella chat facevi a mano una volta sola.
Questo articolo ti porta esattamente a quel momento. Niente teoria di troppo: capiamo cos'è davvero un'API di un LLM, prendiamo una chiave, installiamo l'SDK, scriviamo la chiamata minima, leggiamo la risposta e la mettiamo in sicurezza. Gli esempi sono in Python perché è il linguaggio più usato per questo, ma il ragionamento vale identico in qualsiasi altro linguaggio: cambia la sintassi, non il meccanismo.
Cos'è un'API di un LLM (e perché non è la chat)
Quando scrivi a ChatGPT o Claude nel browser stai usando un'applicazione: qualcuno ha costruito un'interfaccia comoda sopra il modello. L'API — Application Programming Interface — è la porta di servizio sotto quell'interfaccia: un indirizzo a cui il tuo programma manda una richiesta e da cui riceve una risposta, in un formato che il codice sa leggere.
La differenza pratica è enorme. Nella chat sei tu a scrivere, aspettare, copiare. Con l'API il tuo programma può mandare cento richieste mentre bevi un caffè, inserire la risposta dentro un altro sistema, o ripetere lo stesso compito su mille file. La chat è per gli umani; l'API è per il software.
Un'altra differenza che conviene interiorizzare subito: l'API non ha memoria della conversazione. Il box di chat sembra "ricordarsi" cosa hai detto prima perché l'interfaccia rimanda ogni volta tutta la cronologia al modello. Via API quel lavoro tocca a te: se vuoi una conversazione a più turni, sei tu a rimandare i messaggi precedenti a ogni chiamata. È lo stesso principio della finestra di contesto — il modello legge solo ciò che gli passi in quella richiesta, niente di più.
Il pezzo che serve prima del codice: la chiave API
Per usare l'API ti serve una chiave: una lunga stringa segreta che identifica il tuo account e a cui vengono addebitati i consumi. La ottieni dalla dashboard del fornitore che scegli (i due ecosistemi più comuni per iniziare sono quelli di OpenAI e di Anthropic; il procedimento è quasi identico).
Tre cose da sapere subito sulla chiave, perché sono le tre da cui nascono i guai:
La chiave è come una password: chi ce l'ha può spendere i tuoi soldi. Non va mai scritta dentro il codice che poi finisce su GitHub, né incollata in una chat pubblica. Ci torniamo tra poco con il modo giusto di gestirla.
La chiave è legata a un budget. L'uso dell'API si paga a consumo, in base a quanti token entrano ed escono. Le cifre per iniziare sono piccolissime — una chiamata come quella di questo articolo costa una frazione di centesimo — ma conviene impostare fin da subito un limite di spesa nella dashboard, così dormi tranquillo.
La chiave si può revocare e rigenerare. Se la esponi per sbaglio, la cancelli dalla dashboard e ne crei una nuova: la vecchia smette di funzionare all'istante. È la tua rete di sicurezza, usala senza esitare.
Installare l'SDK
Potresti chiamare l'API "a mano" costruendo una richiesta HTTP, ma nessuno lo fa: ogni fornitore pubblica un SDK, una libreria che nasconde i dettagli e ti lascia scrivere poche righe leggibili. Si installa con pip, il gestore di pacchetti di Python. In un terminale:
pip install openai
(oppure pip install anthropic se scegli quell'ecosistema). Se lavori su un progetto serio conviene farlo dentro un ambiente virtuale, ma per la prima prova va bene anche così. Se pip non è riconosciuto, quasi sempre manca Python o non è nel PATH: è il primo scoglio che la dispensa del Livello 2 ti aiuta a superare.
La chiamata minima
Ecco il codice più corto che ottiene una risposta da un modello. Lo commento riga per riga subito dopo.
from openai import OpenAI
client = OpenAI() # legge la chiave dalla variabile d'ambiente OPENAI_API_KEY
risposta = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Sei un assistente conciso, rispondi in italiano."},
{"role": "user", "content": "Spiega cos'è un'API in una frase."}
],
)
print(risposta.choices[0].message.content)
Cosa succede, in ordine. La prima riga importa l'SDK. La seconda crea un client, l'oggetto che parla con il server: non gli passiamo la chiave direttamente nel codice (vedremo perché) — la legge da solo da una variabile d'ambiente. Poi c'è il cuore: create manda la richiesta. Le due informazioni che contano sono model, cioè quale modello vuoi (di solito conviene partire da uno piccolo ed economico), e messages, la lista di messaggi.
Quella lista merita attenzione perché è il concetto centrale dell'API di un LLM. Ogni messaggio ha un ruolo: system è l'istruzione di fondo che imposta il comportamento ("chi sei, come rispondi"); user è ciò che chiede l'utente; e nelle conversazioni a più turni compare anche assistant, cioè le risposte precedenti del modello che rimandi indietro per dare continuità. Costruire bene questa lista è il 90% del lavoro: il resto è idraulica.
Leggere la risposta
Il modello non ti restituisce una stringa e basta, ma un oggetto strutturato con parecchie informazioni. Il testo vero e proprio è annidato: risposta.choices[0].message.content. Quel choices[0] esiste perché in teoria puoi chiedere più risposte alternative alla stessa domanda; quasi sempre ne vuoi una, quindi prendi la prima.
Nell'oggetto trovi anche un campo usage con il conteggio dei token consumati (utile per stimare i costi) e un finish_reason che ti dice perché il modello ha smesso di scrivere: stop significa che ha finito il suo discorso, length che ha toccato il tetto di lunghezza che gli avevi dato. Imparare a guardare questi campi ti risparmia ore di debugging più avanti.
Mettere la chiave al sicuro
Torniamo alla regola d'oro: la chiave non si scrive nel codice. Il modo standard è metterla in una variabile d'ambiente. Il più comodo per un progetto è un file chiamato .env, con dentro una riga:
OPENAI_API_KEY=sk-la-tua-chiave-qui
Poi aggiungi .env al tuo .gitignore così non finisce mai in un repository, e lo carichi all'avvio del programma (con il pacchetto python-dotenv, oppure esportando la variabile nel terminale). L'SDK, come hai visto, la trova da solo. Il vantaggio è doppio: il codice resta pulito e condivisibile, e la chiave vive in un posto solo, facile da cambiare. Questa singola abitudine è la differenza tra chi lavora bene con le API e chi prima o poi si ritrova la chiave bloccata per abuso.
Gli errori che vedrai (e cosa vogliono dire)
Le prime chiamate raramente vanno lisce, ed è normale. I tre errori più comuni all'inizio hanno cause banali. Un errore di autenticazione (401) quasi sempre vuol dire chiave mancante, sbagliata o non caricata: controlla la variabile d'ambiente. Un errore di quota o pagamento (429 o simili) vuol dire che non hai credito o hai superato un limite: si risolve dalla dashboard. Un errore sul nome del modello vuol dire che hai scritto un identificativo che non esiste o a cui il tuo account non ha accesso: controlla la lista dei modelli disponibili. Nessuno di questi è un problema del tuo codice: sono configurazione.
Quando le chiamate diventano tante, aggiungerai anche gestione dei timeout e dei retry — perché la rete a volte inciampa — ma per la prima chiamata non ti serve: fanne una, falla funzionare, poi complica.
Prova subito
Prenditi quindici minuti e chiudi il cerchio. Crea una chiave nella dashboard del fornitore che preferisci e imposta un limite di spesa basso (bastano pochi euro). Mettila in un file .env. Installa l'SDK con pip. Copia il codice minimo qui sopra, cambia la domanda dell'utente con qualcosa che ti serve davvero — "riassumi questo testo in tre punti", incollandoci sotto un tuo paragrafo — e lancialo. Quando vedi la risposta comparire nel terminale, cambia il messaggio system ("rispondi come se parlassi a un bambino di dieci anni") e rilancia: guarderai lo stesso modello comportarsi in modo diverso solo perché hai cambiato una riga. Quella è la leva che d'ora in poi avrai in mano.
Per il quadro completo — la struttura di ogni campo della richiesta, come gestire la cronologia dei messaggi e come tenere d'occhio i costi — ci sono i capitoli "La prima chiamata API" e "I costi delle API" nella dispensa del Livello 2. E se ti sei chiesto perché il modello "dimentica" quando la conversazione si allunga, la risposta è nell'articolo sulla finestra di contesto: via API quella gestione diventa esplicitamente un tuo compito.