> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestire esecuzione e fatturazione

> Esecuzione asincrona, tentativi idempotenti, prenotazioni, addebiti e recupero degli artefatti.

## Panoramica

Questa pagina descrive preventivo, prenotazione, esecuzione asincrona, addebito e artefatti. Segui i processi lunghi tramite ID senza mantenere aperta la connessione HTTP.

## Comprendere esecuzione e fatturazione

`POST /tools/quote` restituisce versione prezzi, costo minimo e prenotazione massima per l’input. È gratuito, non invoca servizi esterni né prenota fondi.

Mantieni `tool` e `arguments` del preventivo e aggiungi:

* `priceVersion` — Versione prezzi del preventivo
* `maximumChargeMicros` — Prenotazione massima del preventivo

Se i prezzi cambiano o il limite è insufficiente, la richiesta viene rifiutata prima dell’avvio. Ottieni e verifica un nuovo preventivo.

## Prenotare e addebitare i costi

All’accettazione viene temporaneamente riservato il massimo dal saldo prepagato in USD. Al completamento viene addebitato il costo reale e restituita la quota inutilizzata.

| Campo | Significato |
| - | - |
| `reservedMicros` | Massimo riservato all’accettazione; conserva il valore iniziale dopo il completamento. |
| `chargedMicros` | Costo definitivo dopo completamento o errore. `0` durante l’elaborazione indica addebito ancora da finalizzare. |
| `currency` | `usd`. 1 USD equivale a 1,000,000 micros. |

Anche in caso di errore o annullamento vengono addebitati i costi esterni già sostenuti. Nessun addebito automatico supera il massimo riservato.

## Consultare lo stato

L’accettazione restituisce HTTP 202 e un ID. Segui `Retry-After: 5` e interroga lo stesso ID a intervalli di almeno cinque secondi.

| Stato | Significato | Azione |
| - | - | - |
| `queued` | In coda | Attendere almeno cinque secondi e riprovare |
| `running` | In elaborazione | Interrogare lo stesso ID |
| `waiting` | In attesa di elaborazione esterna | Interrogare lo stesso ID |
| `succeeded` | Completato e contabilizzato | Leggere `output` e `chargedMicros` |
| `failed` | Fallito; costi sostenuti addebitati | Leggere `errorCode` e costo definitivo |
| `cancelled` | Annullamento completato | Verificare costo definitivo |
| `needs_review` | Risultato o costo da verificare | Non rieseguire; contattare l’assistenza con l’ID |

## Evitare duplicati con l’idempotenza

La chiave di idempotenza impedisce che invii accidentali ripetuti creino esecuzioni separate. Le richieste a pagamento `POST /tools/{tool}` richiedono `Idempotency-Key`.

La chiave contiene 8–128 caratteri: lettere, cifre, `.`, `_`, `:` o `-`. Generane una per richiesta logica e salvala con l’ID di esecuzione.

* Stessa chiave API, stesso corpo e stessa chiave di idempotenza restituiscono la stessa esecuzione.
* Cambiare corpo o chiave API mantenendo la chiave di idempotenza restituisce HTTP 409.
* Dopo un’interruzione, reinvia senza modificare corpo o chiave di idempotenza.
* Reinviare un processo `needs_review` con una nuova chiave crea un’altra esecuzione a pagamento.

> [!WARNING]
>
> L’assenza di risposta non prova che la richiesta non sia stata accettata. Non creare una nuova chiave quando l’esito è sconosciuto.

## Annullare un’esecuzione

`POST /tools/executions/{id}/cancel` richiede di fermare attività non ancora iniziate. Può usarlo la chiave creatrice o un `ADMIN` del progetto.

Se l’elaborazione esterna è già iniziata, la cancellazione può non annullare lavoro e costi. Controlla `cancelRequested`, `status` finale e `chargedMicros`.

## Recuperare gli artefatti

Immagini, audio e video generati compaiono in `output.artifacts` con ID, formato, dimensione, hash e scadenza. Il risultato non include file completi né URL permanenti.

`GET /tools/executions/{id}/artifacts/{artifactId}/download` restituisce un URL valido fino a cinque minuti. I file memorizzati scadono dopo 30 giorni.

Anche gli URL temporanei danno accesso a dati privati. Non registrarli né pubblicarli, e non aggiungere la chiave Developer Platform.

## Pagine correlate

Queste pagine illustrano prima esecuzione ed endpoint.

* [Primi passi](https://docs.noimosai.com/it/developers/api/getting-started.md)
* [Riferimento API](https://docs.noimosai.com/it/developers/api/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.