Vai al contenuto principale

​
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. 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.

​
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.
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.