Cos’è un’API? Spiegazione con l’AI e prima chiamata curl

👁 116 letture

Un’API è un accordo tra due programmi: uno invia una richiesta in un formato prestabilito e l’altro restituisce una risposta, anch’essa in un formato stabilito. Quando il tuo script chiede a un modello di intelligenza artificiale di riassumere un’email, non clicca su una finestra di chat: trasmette via internet un pacchetto di testo in formato JSON e riceve indietro un altro JSON. Questo articolo è il primo passo del percorso API AI da zero, in cui mostro il funzionamento pratico partendo da richieste reali eseguite sul mio computer.

L’API spiegata in modo semplice: lo sportello per i moduli

Il modo più intuitivo per immaginare un’API è pensare a uno sportello pubblico che accetta esclusivamente moduli compilati. Non vedi cosa succede sul retro né chi elabora la pratica. Tuttavia, sai tre cose:

• A quale sportello rivolgerti - questo è l’indirizzo, ovvero l’endpoint, come ad esempio https://openrouter.ai/api/v1/chat/completions;
• Come compilare il modulo - è il formato della richiesta descritto nella documentazione: quali campi sono obbligatori e quali facoltativi;
• Come identificarti - è la chiave API (API key), che alleghi a ogni richiesta.

L’addetto allo sportello ti restituisce la richiesta completata oppure un foglio con un codice di errore: “firma mancante”, “troppe richieste oggi”, “il sistema è fuori servizio”. Nel mondo delle API questi messaggi corrispondono ai codici di stato HTTP, descritti più avanti.

La differenza fondamentale tra una chat e un’API risiede nel fatto che la chat (come ChatGPT, Claude o Gemini) è un’applicazione pronta all’uso per le persone, mentre l’API offre l’accesso al medesimo modello per altri software. Tramite API il modello non memorizza la cronologia della conversazione e non ha pulsanti. In compenso, puoi richiamarlo migliaia di volte da un foglio di calcolo, da un bot o da uno script automatico pianificato di notte. Non si paga un abbonamento fisso, ma solo i token utilizzati, ossia porzioni di testo, spiegati nell’approfondimento Token AI: cosa sono e quanto costano.

Richiesta e risposta (request e response)

Ogni comunicazione con un’API è composta da due elementi. La richiesta (request) contiene:

1. Il metodo - cosa desideri fare. Con i modelli di AI si utilizza quasi sempre POST, perché si inviano contenuti da elaborare.
2. L’indirizzo - l’endpoint specifico per una determinata funzione, ad esempio la generazione del testo o l’elenco dei modelli disponibili.
3. Gli header (intestazioni) - i metadati: la chiave API (Authorization: Bearer ...) e il tipo di contenuto (Content-Type: application/json).
4. Il corpo (body) - i dati effettivi: il modello scelto, i messaggi inseriti e i vari parametri.

La risposta (response) presenta un codice di stato (come 200, che indica un esito positivo) e un corpo con il testo generato e il conteggio dei token consumati. Ecco una risposta reale ricevuta il 4 ottobre 2026 dal modello GPT-6 Luna tramite OpenRouter (ridotta ai campi principali):

{
  "id": "gen-1791114764-uKPpeyAgJg4GJmOQhMp4",
  "object": "chat.completion",
  "model": "openai/gpt-6-luna",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Traduzione dell'originale polacco: Cracovia affascina con la sua storica Piazza del Mercato, le sue stradine suggestive e la sua ricca storia."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 36,
    "total_tokens": 52,
    "cost": 0.0000196
  }
}

Come interpretare questi dati: il modello ha fornito la risposta (content, che nella prova originale in polacco recita “Cracovia affascina con la sua storica Piazza del Mercato, i vicoli suggestivi e la ricca storia”), ha completato l’operazione regolarmente (finish_reason: stop), ha consumato 16 token in input e 36 in output, e l’intera richiesta ha avuto un costo di circa 0,0000175 EUR (0,0000196 USD; tasso BCE del 12/10/2026 da ecb.europa.eu), ovvero una frazione infinitesimale di centesimo.

JSON in due minuti

Il JSON (JavaScript Object Notation) è un formato di testo per la strutturazione dei dati leggibile sia dagli esseri umani che da qualsiasi linguaggio di programmazione. È sufficiente comprendere cinque elementi di base:

• { } - oggetto: un insieme di coppie “chiave: valore”, come {"model": "openai/gpt-6-luna"};
• [ ] - array (elenco): ad esempio l’elenco dei messaggi in un dialogo;
• "testo" - stringa: sempre racchiusa tra virgolette doppie (l’uso delle virgolette singole genera un errore);
• numeri senza virgolette: 0.7, 1024 (separati con il punto decimale, non con la virgola);
• true, false, null - vero, falso, valore nullo.

Una richiesta standard inviata a un modello di AI è un oggetto contenente il campo model e la lista messages. Ciascun messaggio definisce un ruolo (system per le istruzioni generali, user per l’utente, assistant per i precedenti interventi del modello) e il rispettivo contenuto:

{
  "model": "openai/gpt-6-luna",
  "messages": [
    {"role": "user", "content": "Scrivi una frase su Cracovia."}
  ]
}

Nota: il testo della richiesta riportato sopra è una traduzione dell’originale testato in polacco (“Napisz jedno zdanie o Krakowie.”).

L’errore più comune commesso da chi inizia è lasciare una virgola dopo l’ultimo elemento di una lista o di un oggetto. Il JSON non consente questo refuso e il server restituirà un errore 400. Se hai bisogno che il modello risponda direttamente in JSON anziché accettarlo soltanto, puoi consultare la guida Structured output: come ottenere risposte in JSON dai modelli AI.

Metodi HTTP: GET, POST e gli altri

All’inizio utilizzerai quasi esclusivamente due metodi: GET per consultare cosa offre il servizio e POST per generare contenuti.

Stati ed errori: 401, 429, 500 e altri

Il codice di stato HTTP è un numero di tre cifre posizionato all’inizio della risposta. La prima cifra specifica la natura dell’esito: 2xx indica successo, 4xx segnala un errore lato client (da parte tua), 5xx evidenzia un problema lato server.

Ho verificato cosa restituisce concretamente il server quando si omette la chiave API. Inviando una richiesta a OpenRouter priva dell’header Authorization:

$ curl -s https://openrouter.ai/api/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"hej"}]}'
{"error":{"message":"No cookie auth credentials found","code":401}}

Ed ecco come appaiono due errori intercettati tramite uno script in Python: chiave errata e modello inesistente. Da notare che OpenRouter restituisce 400 invece di 404 per un modello non trovato; è quindi buona norma non basare la logica del codice su presupposti rigidi relativi a un singolo codice numerico.

401: controlla la chiave API (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})

400: correggi la richiesta (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})

Per la gestione programmatica di questi codici e la configurazione di tentativi automatici in caso di errore 429, consulta l’articolo La prima richiesta alle API AI con Python.

Prima chiamata curl: interrogare l’API dal terminale

curl è un’utilità da riga di comando per inviare richieste HTTP. È integrata nativamente in Windows 10 e 11 (come curl.exe), in macOS e in Linux, perciò non occorre installare software aggiuntivo. Per iniziare, proviamo una richiesta GET che non richiede credenziali: l’elenco dei modelli su OpenRouter.

{"data":[{"id":"inclusionai/ling-3.1-flash","canonical_slug":"inclusionai/ling-3.1-flash-20261002","hugging_face_id":null,"name":"inclusionAI: Ling 3.1 Flash","created":1790950024,"description":"Ling 3.1 Flash is a hybrid reasoning mixture-of-experts model from inclusionAI, with 25B active parameters out of 560B total.","context

La risposta contiene un oggetto con l’array data, che al 4 ottobre contava 466 modelli disponibili. Passiamo ora a una richiesta POST per interrogare effettivamente il modello. Ti servirà una chiave API (la procedura per quattro fornitori diversi è illustrata in Chiave API: come ottenerla e usarla in sicurezza). Su Git Bash, Linux o macOS:

#!/usr/bin/env bash
# Prima richiesta tramite curl (Git Bash, Linux, macOS). Prima: export OPENROUTER_API_KEY=sk-or-v1-...
# Nota: il prompt nel body è tradotto dal test originale in lingua polacca ("Napisz jedno zdanie o Krakowie.")
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "messages": [{"role": "user", "content": "Scrivi una frase su Cracovia."}]
  }'

In PowerShell la gestione delle virgolette nel JSON può causare conflitti di parsing. Risulta più pratico salvare il payload in un file separato (ad esempio richiesta.json) e farlo caricare a curl. Su PowerShell è preferibile digitare esplicitamente curl.exe invece di curl, per evitare che venga richiamato l’alias di un altro comando nelle versioni datate:

# Windows PowerShell: payload salvato nel file richiesta.json per evitare problemi con le virgolette
# Da eseguire prima nella stessa finestra: $env:OPENROUTER_API_KEY = "sk-or-v1-..."
curl.exe -s https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d "@richiesta.json"

Abbiamo testato entrambe le modalità su Windows 11 (utilizzando Git Bash con curl 8.22 e Windows PowerShell). Il test è stato condotto in polacco e il modello ha risposto con una frase descrittiva sulla città, con un costo di circa 0,0000179 EUR (circa 0,00002 USD; tasso BCE del 12/10/2026 da ecb.europa.eu) per richiesta. I file completi sono disponibili all’interno del pacchetto di avvio in API AI da zero.

Passaggi successivi

1. Crea un account e ottieni la tua chiave: Chiave API su OpenAI, Anthropic, Google AI Studio e OpenRouter.
2. Crea il tuo primo programma: La prima richiesta alle API AI con Python.
3. Calcola i consumi: Token AI e calcolatore dei costi.
4. Approfondisci flussi di lavoro più avanzati: Agenti AI da zero.

Domande frequenti

Cos’è un’API in parole semplici?

È un meccanismo che permette a un programma di richiedere informazioni o operazioni a un altro software: invia dati in un formato strutturato e ottiene una risposta formattata nello stesso modo, senza dover sapere come sia implementato il sistema ricevente.

Cosa significa l’acronimo API?

Application Programming Interface, ossia interfaccia di programmazione delle applicazioni. Si definisce interfaccia perché funge da punto di contatto e comunicazione tra due software, così come lo schermo e i comandi fisici rappresentano l’interfaccia verso una persona.

Serve saper programmare per usare un’API?

Per inviare un comando iniziale di prova no: basta curl e un’istruzione pronta da copiare nel terminale. Per applicazioni continuative è consigliabile apprendere le basi di Python o impiegare piattaforme di automazione come n8n o Zapier, che gestiscono le chiamate in autonomia.

Che differenza c’è tra un’API e ChatGPT?

ChatGPT è un’applicazione completa dotata di interfaccia utente, cronologia delle conversazioni e formula in abbonamento. L’API di OpenAI fornisce l’accesso diretto ai modelli per altri software, viene tariffata a consumo in base ai token elaborati, non include un’interfaccia a finestra né conserva lo storico delle sessioni. L’abbonamento standard a ChatGPT non include le chiamate API: profili e fatturazione sono del tutto separati.

Cos’è un’API REST?

È lo stile architetturale più diffuso per la creazione di servizi web: ogni risorsa è identificata da un URL specifico, le azioni vengono definite tramite metodi HTTP standard (GET, POST, DELETE) e i dati vengono scambiati prevalentemente in formato JSON. La quasi totalità delle API per modelli di AI adotta questo approccio.

Fonti e dettagli di verifica

Le richieste di prova sono state eseguite il 4 ottobre 2026 su Windows 11 tramite la piattaforma OpenRouter. Il costo complessivo per tutti i test descritti nell’articolo è stato inferiore a 0,000089 EUR (0,0001 USD; tasso BCE del 12/10/2026 da ecb.europa.eu).

• OpenRouter - Guida rapida
• OpenRouter - Elenco codici di errore
• MDN - Codici di stato HTTP
• json.org - Specifiche del formato JSON
• Anthropic - Documentazione errori API (incluso 529)

// continua a leggereEmbedding e database vettoriali spiegati in modo sempliceGuideBenchmark Muse Wonder: i 14 test di Meta spiegatiBenchmarkSupabase tutorial: prima tabella, sicurezza e connessione appMagazine

Kinetyra