Cos'è un'API REST
Un'API (Application Programming Interface) è il modo in cui due programmi si parlano. REST è lo stile più diffuso per le API web: usa il protocollo HTTP, ogni richiesta è indipendente dalle altre (stateless) e i dati viaggiano in JSON. Detto in pratica: mandi un pacchetto di testo a un indirizzo, ti torna un pacchetto di testo.
Nel contesto dell'AI, le API REST sono il modo standard per accedere a modelli linguistici, di embedding, di visione e di generazione senza doverli eseguire in locale. Provider come OpenAI, Anthropic, Google e Cohere espongono i loro modelli tramite API che chiunque può integrare nelle proprie applicazioni.
Punti chiave
- Una API REST usa HTTP, è stateless e scambia dati in JSON: è il modo standard per usare l'AI senza eseguire i modelli in locale.
- Le richieste a un LLM viaggiano in POST verso un endpoint, con parametri come
model,messages,temperatureemax_tokens. - L'autenticazione avviene tramite API key nell'header
Authorization: mai metterle nel codice, sempre in variabili d'ambiente. - I provider applicano rate limit (RPM e TPM): gestire gli errori 429 con retry e backoff esponenziale è essenziale in produzione.
- OpenAI e Anthropic offrono interfacce simili ma con differenze concrete su system prompt, struttura dei messaggi e funzionalità avanzate.
Le API democratizzano l'accesso all'AI: non servono GPU da migliaia di euro o competenze di infrastruttura ML. Una semplice richiesta HTTP è sufficiente per sfruttare i modelli più potenti al mondo.
HTTP methods e endpoint
I metodi HTTP corrispondono alle operazioni:
| Metodo | Azione | Esempio AI |
|---|---|---|
| GET | Leggere una risorsa | Elencare i modelli disponibili |
| POST | Creare/inviare dati | Inviare un prompt e ricevere la risposta |
| PUT | Aggiornare una risorsa | Aggiornare un dataset di fine-tuning |
| DELETE | Eliminare una risorsa | Eliminare un modello fine-tunato |
Un endpoint è l'URL specifico che espone una funzionalità. Per le API AI, gli endpoint principali sono: completions (generazione di testo), embeddings (vettorizzazione), images (generazione immagini) e fine-tuning (addestramento personalizzato).
Nella pratica quotidiana, chi integra l'AI in un prodotto usa quasi sempre il metodo POST verso l'endpoint di chat: è qui che si invia il prompt e si riceve la risposta del modello. GET serve invece per attività di gestione (elencare i modelli, controllare lo stato di un job di fine-tuning), mentre PUT e DELETE entrano in gioco solo quando si amministrano risorse persistenti come dataset o file caricati.
Capire la distinzione tra i metodi aiuta anche a leggere la documentazione dei provider: ogni endpoint indica quale verbo HTTP accetta e quale struttura di payload si aspetta. Per un'applicazione di marketing, ad esempio un generatore di testi o un assistente che risponde ai clienti, nel 90% dei casi basta padroneggiare bene la singola chiamata POST verso le chat completions.
Request e response JSON
Le API di AI scambiano JSON. Una richiesta tipica a un modello di linguaggio contiene il modello scelto, i messaggi e i parametri di generazione:
Struttura della request
{"model": "gpt-4o", "messages": [{"role": "system", "content": "Sei un assistente."}, {"role": "user", "content": "Cos'e il machine learning?"}], "max_tokens": 500, "temperature": 0.7}
I parametri che contano:
- model: quale modello usare (gpt-4o, claude-sonnet-4-20250514, gemini-1.5-pro).
- messages: la conversazione, con ruoli system/user/assistant.
- temperature (0-2): controlla la casualità. 0 = deterministico, 1+ = creativo.
- max_tokens: limite massimo di token nella risposta.
- top_p: nucleus sampling, alternativa alla temperature.
Nella risposta trovi il testo generato, i dati sulla chiamata (identificativo, modello usato) e il conteggio dei token consumati in ingresso e in uscita. Quest'ultimo campo è quello da guardare, perché è la tua bolletta.
Leggere il campo usage è una competenza pratica che quasi nessuno si prende la briga di imparare: moltiplichi i token per il prezzo del modello e hai il costo esatto di quella chiamata. Da lì sai in anticipo quanto ti costerà generare mille descrizioni prodotto o rispondere a un certo numero di richieste, e puoi decidere se il progetto sta in piedi prima di scriverlo. Per tenere i costi bassi le due leve sono il max_tokens e un prompt che non ripeta il contesto mille volte.
Autenticazione e API key
Ogni chiamata va firmata con una chiave API, che identifica te e addebita a te. Va nell'header HTTP Authorization, e non va mai messa nel codice che finisce nel browser o su GitHub: è il primo errore che fanno tutti, e le chiavi rubate vengono usate in poche ore.
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Sicurezza delle API key
Mai inserire API key nel codice sorgente o in repository Git.
Usa variabili d'ambiente: OPENAI_API_KEY, ANTHROPIC_API_KEY.
Ruota le key periodicamente e limita i permessi al minimo necessario.
Monitora l'utilizzo nella dashboard del provider per rilevare abusi.
Alcuni provider offrono autenticazione avanzata con OAuth 2.0 per applicazioni che agiscono per conto di utenti terzi, ma per l'uso diretto delle API le API key restano lo standard.
Rate limiting e gestione errori
I provider impongono limiti di utilizzo (rate limit) per garantire la stabilita del servizio. I limiti si applicano tipicamente su due dimensioni: richieste per minuto (RPM) e token per minuto (TPM).
Gli errori che vedrai:
- 401 Unauthorized: API key mancante o non valida.
- 429 Too Many Requests: rate limit superato. Implementa retry con backoff esponenziale.
- 500 Internal Server Error: problema lato server. Riprova dopo qualche secondo.
- 400 Bad Request: parametri non validi (es. prompt troppo lungo per la context window).
La pratica corretta è il retry con attesa crescente: aspetti 1 secondo, poi 2, poi 4, fino a tre o cinque tentativi. In Python con tenacity lo scrivi in due righe, e ti risparmia le chiamate perse quando il servizio è sotto carico.
Esempio: API OpenAI
OpenAI offre l'ecosistema API più maturo, con endpoint per chat completions, embeddings, immagini (DALL-E), audio (Whisper, TTS) e fine-tuning.
Chiamata base con Python
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Ciao!"}])
print(response.choices[0].message.content)
Funzionalità avanzate: function calling (il modello può invocare funzioni definite dall'utente), streaming (risposte token per token per ridurre la latenza percepita), vision (analisi di immagini) e JSON mode (output strutturato garantito).
Esempio: API Anthropic
Anthropic offre le API della famiglia Claude, con un'interfaccia che somiglia molto e qualche differenza nella struttura dei messaggi:
Chiamata base con Python
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(model="claude-sonnet-4-20250514", max_tokens=1024, messages=[{"role": "user", "content": "Ciao!"}])
print(message.content[0].text)
Differenze chiave rispetto a OpenAI: il system prompt è un parametro separato (non un messaggio), il content è strutturato come lista di blocchi (testo, immagini), supporto nativo per contesti molto lunghi (fino a 200K token).
Le API REST sono il ponte tra i modelli AI e le applicazioni reali. Che si tratti di un chatbot, di un sistema RAG o di un pipeline di analisi dati, la competenza nell'uso delle API è la competenza pratica più richiesta per chi lavora con l'AI. Per iniziare a programmare, consulta Python per l'AI.
Vuoi imparare ad applicarlo davvero?
Scopri i corsi e la formazione di Federico Boggia su AI, dati e digitale.
