Che cos'è un'API di LLM?

Un’API di LLM è un endpoint HTTP verso un modello di linguaggio ospitato: si invia un prompt, si riceve testo generato, fatturato a token. È un’API ordinaria con tre proprietà inusuali – è stateless (l’intera conversazione va rispedita a ogni chiamata), misurata in token (input e output tariffati separatamente) e non deterministica (lo stesso prompt può restituire testi diversi). Padroneggiati questi tre punti, il resto è la disciplina operativa che le pagine meglio posizionate saltano: dove sta la chiamata, quanto costa e come fallisce.

Punti chiave

Una chiamata reale, lato server

// JavaScript — Cloud Code (cloud/main.js)
// The LLM call belongs server-side — the key never reaches the client
Parse.Cloud.define('summarize', async (req) => {
  const res = await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://api.llm-provider.example/v1/chat/completions',
    headers: {
      Authorization: `Bearer ${process.env.LLM_KEY}`, // server-side secret
      'Content-Type': 'application/json',
    },
    body: {
      model: 'default-chat',
      messages: [
        { role: 'system', content: 'Summarize in one sentence.' },
        { role: 'user', content: req.params.text },
      ],
      max_tokens: 80, // cost + latency guardrail, enforced by YOU
    },
  });
  return res.data.choices[0].message.content;
});

// Flutter / Dart — Back4app Flutter SDK
// The client calls YOUR function, never the LLM API directly
final summary = await ParseCloudFunction('summarize')
    .execute(parameters: {'text': longArticle});
print(summary.result);
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the binary — one decompile from theft.

// iOS / Swift — Back4app Swift SDK
// The client calls YOUR function, never the LLM API directly
let summary: String = try await Cloud.run(
    name: "summarize", parameters: ["text": longArticle])
print(summary)
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the IPA — one decompile from theft.

// Android / Kotlin — Back4app Android SDK
// The client calls YOUR function, never the LLM API directly
val summary = ParseCloud.callFunction<String>(
    "summarize", mapOf("text" to longArticle))
println(summary)
// The model key stays on the server. If this app called the LLM API
// itself, the key would ship in the APK — one decompile from theft.

Il formato è portabile – la maggior parte dei provider accetta lo stesso formato chat-completions, così la richiesta e la risposta qui sotto si leggono allo stesso modo qualunque sia il modello puntato:

POST /v1/chat/completions            Authorization: Bearer <key>
{ "model": "default-chat",
  "messages": [
    { "role": "system", "content": "You are concise." },   ← definisce il comportamento
    { "role": "user",   "content": "Explain tokens." } ],   ← l'istruzione
  "max_tokens": 200, "temperature": 0.7, "stream": false }

→ { "choices": [ { "message": { "role": "assistant",
                                "content": "A token is…" },
                   "finish_reason": "stop" } ],
    "usage": { "prompt_tokens": 24, "completion_tokens": 118,
               "total_tokens": 142 } }        ← ciò che viene fatturato

I token sono la valuta

Un token è un frammento di testo – circa quattro caratteri, o tre quarti di una parola inglese. Tutto il costo di un’API di LLM si riduce a contarli, e due fatti sorprendono. L’output costa più dell’input – spesso diverse volte tanto – perché leggere il prompt è economico, mentre generare ogni token della risposta è intensivo in calcolo, una previsione alla volta su tutto il vocabolario. E il contesto si paga a ogni chiamata: il modello è stateless, quindi la “memoria” consiste nel rispedire i turni precedenti, e una cronologia lunga o un grosso passaggio recuperato viene fatturato di nuovo a ogni richiesta. La formula mensile approssimativa che vale la pena interiorizzare:

costo mensile ≈ ( richieste/giorno
                  × (avg_input_tokens  × input_price_per_M  / 1_000_000
                   + avg_output_tokens × output_price_per_M / 1_000_000) )
                × 30

Le leve che la muovono: limitare max_tokens, ridurre il contesto rispedito,
scegliere un modello più piccolo per i compiti facili e mettere in cache i prefissi di prompt riusati.

I parametri che contano

Streaming: perché le interfacce di chat sembrano rapide

Basta attivare un flag stream e la risposta arriva in modo incrementale come Server-Sent Events – righe data:, un frammento di token alla volta, chiuse da un marcatore [DONE] – invece che in un unico blocco dopo diversi secondi. Il motivo è percettivo: il tempo fino al primo token è una frazione del tempo fino alla risposta completa, quindi si guardano le parole comparire invece di uno spinner che gira. È testo unidirezionale dal server al client su semplice HTTP, cioè esattamente la forma di SSE e precisamente il motivo per cui lo streaming dei LLM la usa invece dei WebSocket. La conseguenza lato backend: il proxy deve far passare il flusso da un capo all’altro – leggere lo stream di eventi del provider e inoltrarlo – invece di mettere in buffer l’intera risposta, vanificando lo scopo.

Tool calling e output strutturato

Due funzionalità trasformano “testo in ingresso, testo in uscita” in qualcosa di programmabile. Tool calling: nella richiesta si descrivono le funzioni disponibili (nome + schema JSON) e il modello – invece della prosa – restituisce una chiamata JSON strutturata che nomina un tool e i suoi argomenti; il codice applicativo la esegue e restituisce il risultato (la spiegazione passo a passo di Fowler è il riferimento più chiaro). Il modello non esegue mai la funzione; si limita a chiederla. L’output strutturato, distinto dal tool calling e spesso confuso con esso, sono tre cose che vale la pena separare:

Il tool calling è il meccanismo che rende possibile un agente IA – la stessa coppia richiesta/risposta, eseguita in un ciclo finché il modello smette di chiedere tool.

API di LLM vs. self-hosting di un modello aperto

La lettura onesta: un’API vince per quasi tutti e quasi sempre – zero infrastruttura, partenza immediata e costi minori finché il volume non è davvero grande e regolare. Ospitare in proprio un modello aperto (con Ollama, vLLM o llama.cpp) ripaga il proprio costo operativo solo oltre un punto di pareggio elevato, oppure quando la residenza dei dati è un requisito ferreo. La maggior parte dei prodotti parte dall’API e riesamina la questione soltanto se la scala lo impone.

Affidabilità: gli endpoint di LLM sono capricciosi

L’API di LLM va trattata come una dipendenza remota lenta, soggetta a rate limiting e che di tanto in tanto fallisce, perché è esattamente questo. I limiti arrivano come richieste al minuto e token al minuto; superato uno dei due, arriva un 429. La disciplina è la stessa che pretende qualsiasi API soggetta a rate limiting: su un 429 o un 5xx conviene ritentare con backoff esponenziale più jitter e rispettare Retry-After; su un 4xx – autenticazione sbagliata, richiesta malformata, rifiuto per policy sui contenuti – non si ritenta, perché fallirà in modo identico. Vanno aggiunti timeout per richiesta (la generazione può bloccarsi), e va ricordato che una chiamata non idempotente ritentata costa token due volte. Nulla di tutto questo è specifico dei LLM; tutto questo viene saltato dai tutorial che si fermano al curl del caso ideale.

La regola che i tutorial seppelliscono: mai chiamarla dal client

Il fatto operativo più importante, e quello che le pagine di glossario omettono: la chiamata all’API di LLM sta sul server, mai nel browser o nell’app. Una chiave API del modello spedita al client dista uno sguardo alla scheda di rete o una decompilazione del binario dal furto – e, a differenza di una chiave pubblicabile che esce, una chiave del modello rubata è un estraneo con un budget di token e nessun limite oltre la fattura. Il pattern è la stessa disciplina di proxy che richiede ogni servizio con chiave segreta: il client chiama l’endpoint applicativo, il backend tiene la chiave nella configurazione lato server e chiama il modello, e la risposta torna passando da lì. Quel proxy è anche il posto in cui vivono tutti gli altri controlli di questo articolo – tetti di costo, ritentativi, streaming, riduzione dei prompt – ed è per questo che la domanda “dove va la chiamata?” ha una sola risposta.

Casi d’uso tipici

• Riassunto ed estrazione – trasformare testo lungo in dati brevi e strutturati, temperature: 0.
• Chat e assistenti – risposte in streaming su una cronologia di conversazione rispedita.
• Classificazione ed etichettatura – Structured Outputs che impongono lo schema delle etichette.
• Risposte RAG – generazione ancorata al contesto recuperato, con il costo tenuto a bada riducendo quel contesto.
• Azioni agentiche – tool calling in un ciclo, dove ogni tool è una funzione del backend soggetta ai permessi.

Conviene usare un’API di LLM? Matrice decisionale

Limiti e trade-off

• Il non determinismo è la condizione predefinita. Lo stesso prompt varia da un’esecuzione all’altra; tutto ciò che richiede ripetibilità esatta ha bisogno di temperature: 0 e, spesso, di una validazione dell’output.
• Il costo cresce con i token, in silenzio. Un contesto generoso o un max_tokens senza tetto rende costosa su larga scala una feature economica – il consumo va misurato, non supposto.
• La latenza si misura in secondi, non in millisecondi. Le chiamate ai LLM sono lente secondo gli standard del web; va progettata di conseguenza, con streaming, pattern asincroni e stati di caricamento onesti.
• La dipendenza è esterna e soggetta a rate limiting. I disservizi e il throttling del provider diventano disservizi propri; ritentativi, soluzioni di ripiego e cache sono resilienza, non rifinitura.
• Gli output possono essere sbagliati e sicuri di sé. L’API restituisce testo scorrevole a prescindere dalla verità; l’ancoraggio (RAG) e la validazione sono ciò che permette di fidarsi.

Le API di LLM su Back4app

Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Qui la domanda “dove sta la chiamata?” si risolve da sé: dentro una Cloud Function, esattamente come mostrano le schede di codice – il client chiama la propria summarize, la funzione tiene la chiave del modello nella configurazione lato server e chiama l’API di LLM, e la chiave non tocca mai il dispositivo. Quella sola collocazione colma in un colpo l’intera lista delle lacune: tetti di costo (la funzione imposta max_tokens e sceglie il modello), ritentativi e backoff (nella funzione, contro l’endpoint capriccioso) e consegna in due modi – restituire la risposta in modo sincrono per una risposta singola, oppure scriverla nel database e lasciare che i client la guardino riempirsi con le Live Queries, cioè streaming senza un socket da costruire. L’API di LLM smette di essere un rischio di integrazione e diventa una chiamata lato server in più, che il backend sa già fare in sicurezza.