API per l’intelligenza artificiale: come funziona una richiesta?

Il formato è determinato dal percorso della richiesta, non dal modello. Lo stesso modello Claude può essere chiamato tramite OpenAI Chat, OpenAI Responses o Anthropic Messages — la risposta arriva nel formato del percorso chiamato.

• Prima di inviare una nuova richiesta testuale, Ailoot riserva l’importo stimato per l’input e una risposta tipica, tenendo conto del limite (max_tokens) e delle condizioni del modello specifico. Se la riserva non rientra nel saldo libero o nel limite della chiave, il limite trasmesso può essere ridotto solo per un modello e un metodo che lo rispettano effettivamente, senza scendere sotto 256 token né sotto il minimo di output previsto. Per immagini, video e audio in output rimane riservato l’intero costo del risultato.
• Dopo la risposta — un solo addebito sul consumo effettivo. La riserva inutilizzata torna subito sul saldo.
• Se la risposta costa più della riserva, la differenza viene presa dal saldo libero. Il saldo non diventa mai negativo.
• Se il saldo non basta nemmeno per la riserva minima, la richiesta non viene inviata: ricevi un errore 402 chiaro e non viene addebitato nulla.
• Un errore che non produce un risultato non viene addebitato.

Dettagli ed esempio di calcolo sono nella pagina Riserva e addebito.

Ogni risposta riceve un identificatore della richiesta nell’header X-Request-ID e nel testo dell’errore. Gli errori arrivano in JSON nel formato chiamato, quindi gli SDK li riconoscono correttamente. Se qualcosa va storto, invia il Request ID al servizio di assistenza — così troviamo la richiesta in un minuto.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

Le risposte in streaming (stream: true) arrivano come Server-Sent Events. Ailoot restituisce la risposta testuale a pagamento dopo il calcolo del costo. Quindi con stream: true il formato resta in streaming (SSE), ma il testo arriva in un unico blocco quando il modello termina, non parola per parola. Se la risposta richiede più di circa 15 secondi, nei flussi Chat Completions, Responses e Messages arrivano prima le righe di servizio : ping (circa ogni 10 secondi), poi la riga : ailoot-charged-usd … con l’importo addebitato e i dati. Gli SDK ignorano queste righe.

Nel formato Gemini non ci sono righe di servizio: la risposta :streamGenerateContent arriva intera dopo il calcolo. Per i modelli di ragionamento lascia un margine nel timeout del client: qualche minuto è normale.

X-Request-ID arriva in ogni risposta. Ailoot aggiunge gli altri header alle risposte testuali a pagamento:

Se il flusso è già iniziato con righe di servizio, queste informazioni arrivano come riga di commento prima dei dati, non come header.

Se il modello supporta il caching, un prefisso lungo reinviato (istruzione di sistema, documenti) può costare meno. I prezzi di lettura e scrittura della cache sono mostrati nella scheda del modello nel catalogo. Il cache hit è deciso dallo sviluppatore del modello; Ailoot non lo garantisce.