Source: https://ailoot.ai/docs/it/how-it-works/
Canonical: https://ailoot.ai/docs/it/how-it-works/
Language: it

[Introduzione](https://ailoot.ai/docs/it/) 

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

[Markdown](https://ailoot.ai/docs/it/how-it-works/index.md)

Come funziona

Cosa succede alla richiesta tra il tuo programma e il modello.

Invii una richiesta ad Ailoot API come la invieresti direttamente a OpenAI, Anthropic o Google. Ailoot controlla chiave e saldo, inoltra la richiesta al modello, restituisce la risposta nello stesso formato e addebita il consumo effettivo.

<em>01</em><strong>Richiesta</strong>Il tuo client invia una richiesta a api.ailoot.ai con la chiave sk-…

<em>02</em><strong>Verifica e riserva</strong>Chiave, limiti, saldo. Un importo viene riservato per la durata della risposta.

<em>03</em><strong>Modello</strong>Il modello risponde e la risposta torna nel tuo formato.

<em>04</em><strong>Addebito</strong>Un solo addebito sui token effettivi; il resto della riserva viene liberato.

## [](https://ailoot.ai/docs/it/how-it-works/#formats)Una chiave — tre formati

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.

| Formato | Percorso | Chi lo usa |
| --- | --- | --- |
| OpenAI Chat Completions | `/v1/chat/completions` | OpenAI SDK, la maggior parte delle chat e degli editor, n8n, LangChain |
| OpenAI Responses | `/v1/responses` | Codex CLI, OpenAI Agents SDK, nuove versioni degli SDK |
| Anthropic Messages | `/v1/messages` | Claude Code, Anthropic SDK, Zed, Cline |
| Gemini | `/v1beta/models/{model}:generateContent` | Gemini CLI, Google GenAI SDK |

## [](https://ailoot.ai/docs/it/how-it-works/#money)Costi: riserva e un solo addebito

- 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](https://ailoot.ai/docs/it/billing/reserve/).

## [](https://ailoot.ai/docs/it/how-it-works/#errors)Errori con Request ID

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](https://ailoot.ai/docs/it/support/) — così troviamo la richiesta in un minuto.

401 Unauthorized

```json
{
  "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. …"
}
```

## [](https://ailoot.ai/docs/it/how-it-works/#streaming)Streaming e timeout

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.

## [](https://ailoot.ai/docs/it/how-it-works/#headers)Header della risposta

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

| Header | Contenuto |
| --- | --- |
| `X-Request-ID` | Identificatore della richiesta — viene chiesto dall’assistenza |
| `X-Ailoot-Charged-USD` | Importo addebitato per questa richiesta, in dollari |
| `X-Ailoot-Output-Tokens` | Numero di token della risposta pagati |
| `X-Ailoot-Max-Tokens-Capped` | Limite di risposta ridotto perché il saldo non copriva l’intera riserva |
| `X-Ailoot-Notice-Code`, `X-Ailoot-Notice` | Spiegazione se la risposta si è fermata al limite di lunghezza |

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

## [](https://ailoot.ai/docs/it/how-it-works/#cache)Cache dei prompt

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](https://ailoot.ai/models/it/). Il cache hit è deciso dallo sviluppatore del modello; Ailoot non lo garantisce.

Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.[Contatta l’assistenza](mailto:support@ailoot.ai)

## Domande sul funzionamento dell’API

### Cosa fa Ailoot quando invio una richiesta all’API?

Invii una richiesta ad Ailoot API come la invieresti direttamente a OpenAI, Anthropic o Google. Ailoot controlla chiave e saldo, inoltra la richiesta al modello, restituisce la risposta nello stesso formato e addebita il consumo effettivo.

## Ailoot · L’azienda e il suo portafoglio di progetti





Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI.





L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese.





Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.