Cos'e un'API REST
Un'API (Application Programming Interface) e un'interfaccia che permette a due software di comunicare tra loro. REST (Representational State Transfer) e lo stile architetturale piu diffuso per le API web: usa il protocollo HTTP, e stateless (ogni richiesta e indipendente) e scambia dati in formato JSON.
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 puo integrare nelle proprie applicazioni.
Le API democratizzano l'accesso all'AI: non servono GPU da migliaia di euro o competenze di infrastruttura ML. Una semplice richiesta HTTP e sufficiente per sfruttare i modelli piu potenti al mondo.
HTTP methods e endpoint
Le API REST usano i metodi HTTP standard per le diverse 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 e l'URL specifico che espone una funzionalita. Per le API AI, gli endpoint principali sono: completions (generazione di testo), embeddings (vettorizzazione), images (generazione immagini) e fine-tuning (addestramento personalizzato).
Request e response JSON
Le API AI scambiano dati in formato JSON (JavaScript Object Notation). Una richiesta tipica a un LLM include il modello, 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}
Parametri chiave della richiesta:
- 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 casualita. 0 = deterministico, 1+ = creativo.
- max_tokens: limite massimo di token nella risposta.
- top_p: nucleus sampling, alternativa alla temperature.
La response contiene la risposta generata, i metadati (ID, modello usato) e le informazioni di utilizzo (token consumati per input e output), fondamentali per monitorare i costi.
Autenticazione e API key
Le API AI richiedono un'API key per identificare l'utente, tracciare l'utilizzo e addebitare i costi. La key viene inviata nell'header HTTP Authorization:
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).
Codici di errore comuni:
- 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 best practice e implementare un sistema di retry con exponential backoff: attendere 1s, poi 2s, poi 4s tra i tentativi, fino a un massimo di 3-5 retry. Librerie come tenacity in Python semplificano questa logica.
Esempio: API OpenAI
OpenAI offre l'ecosistema API piu 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)
Funzionalita avanzate: function calling (il modello puo 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 API per la famiglia Claude con un'interfaccia simile ma con differenze nella struttura dei messaggi e nelle funzionalita specifiche:
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 e un parametro separato (non un messaggio), il content e 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 e la skill pratica piu richiesta per chi lavora con l'AI. Per iniziare a programmare, consulta Python per l'AI.