Documentazione

Riferimento API

Crea un'esecuzione dello strumento

POST/v1/tool-runs

Supporta flat (prezzo costante per chiamata), input (precalcolo sugli input) e usage (utilizzo finale). pricing.quote_required determina l'obbligo di preventivo; requires_usage determina l'obbligo di limite di costo e attesa dell'utilizzo finale autorevole; nessuno dei due si deduce da schema_version. Se metered_pricing è disabilitato, sono limitate solo nuove chiamate che richiedono utilizzo finale; regole costanti/input senza tale requisito restano disponibili. La Key corrente deve avere autorizzazione per lo strumento; identità e risultati dell'esecuzione sono vincolati alla Key originale. Se gli strumenti sono globalmente disabilitati, il catalogo è vuoto; quello anonimo non autorizza l'esecuzione. Una nuova chiamata richiede version/input non vuoti e Idempotency-Key. Se la risposta di creazione va persa senza run_id, ripeti con API Key, Idempotency-Key e corpo completo originali per recuperare l'esecuzione esistente, senza nuovo preventivo o modifica del limite. La ripetizione di un'esecuzione accettata non dipende da abilitazioni correnti o validità del preventivo. Con run_id consulta solo l'esecuzione originale; non cambiare chiave per invii sconosciuti.

Esecuzione dopo il preventivo

Ottieni version, input_schema e pricing esatti dai dettagli dello strumento. mode=flat è un prezzo costante per chiamata, mode=input un precalcolo basato sull'input e mode=usage un calcolo sull'utilizzo finale. schema_version della regola indica soltanto il formato di archiviazione.

Una nuova chiamata con quote_required=true richiede prima un preventivo. Verifica tool_id/version riportati nella risposta e conserva quote_id e richiesta originale. Con requires_usage=true devi anche fornire max_cost_usd non inferiore a maximum_usd. Per le altre esecuzioni il limite di costo è facoltativo, ma viene comunque controllato se fornito. Le esecuzioni a prezzo costante senza utilizzo finale possono procedere direttamente; le regole basate sull'input richiedono un preventivo ma possono non richiedere utilizzo finale per l'addebito.

Il preventivo fissa la fonte originale. Se la fonte predefinita cambia, il preventivo continua a usare quella originale finché fonte e configurazione restano valide. Per nuove chiamate non ancora inviate, quote_expired, quote_stale o invalid_quote consentono un nuovo preventivo dopo la verifica degli input. Se l'esecuzione riesce ma billing resta reserved, continua a interrogare l'utilizzo finale; il successo dell'output non dimostra la chiusura contabile.

Recupero quando la risposta va persa

Prima dell'invio conserva identità API Key, Idempotency-Key e corpo completo originali. Se la risposta di creazione va persa senza run_id, ripeti POST /v1/tool-runs con la stessa Key, la stessa chiave di richiesta e la richiesta completa originale. Mantieni quote_id e max_cost_usd, senza nuovo preventivo o cambio di chiave. Le esecuzioni esistenti restituiscono prioritariamente il record originale senza chiamare nuovamente il servizio, anche se il preventivo è poi scaduto o le nuove chiamate sono disabilitate. Dopo aver ottenuto run_id, usa solo GET sull'esecuzione originale.

Un conflitto di idempotenza richiede il controllo della richiesta originale. Non cambiare automaticamente chiave creando una nuova operazione a pagamento. Vedi Gestione degli errori, Fatturazione e Recupero asincrono.

Autenticazione e autorizzazioni

Usa la chiave GloopAPI corrente. Modelli, funzionalità e autorizzazioni disponibili dipendono dal relativo catalogo e dalla documentazione dell'endpoint.

Authorization: Bearer $GLOOP_API_KEY

Schemi di autenticazione: BearerAuth

Richiesta

Header della richiesta

  • Idempotency-KeystringObbligatorio

    Conserva l'intento originale con la stessa Key. Dopo un'interruzione di rete, consulta prima il recupero; niente reinvii alla cieca per stati sconosciuti.

    Lunghezza minima
    1
    Lunghezza massima
    191

Corpo della richiesta · application/json

Tipo
object
Campi obbligatori
tool_idversioninput
Proprietà aggiuntive
false

Corpo della richiesta obbligatorio

  • quote_idstringFacoltativo

    Con pricing.quote_required=true serve un preventivo valido per nuove esecuzioni; facoltativo per prezzo costante senza utilizzo finale. I vincoli di ogni preventivo fornito vengono sempre verificati.

  • tool_idstringObbligatorio

    ID dello strumento nel catalogo eseguibile della Key corrente.

  • versionstringObbligatorio

    Versione di contratto, funzionalità o strumento; le esecuzioni usano la versione restituita dal catalogo.

    Lunghezza minima
    1
    Pattern
    ".*\\S.*"
  • inputunknownObbligatorio

    Deve rispettare input_schema di questa version dello strumento. Solo JSON normalizzato; vietati campi aggiuntivi come route_id amministrativo.

  • max_cost_usdstringFacoltativoConsente null

    Con pricing.requires_usage=true serve un budget decimale valido in dollari, non null e almeno pari a maximum_usd del preventivo. Negli altri casi è facoltativo ma verificato se fornito. Controllo solo alla creazione.

Risposte ed errori

HTTP 200

Restituisce 200 per succeeded o failed, nella prima risposta sincrona o nel recupero idempotente. succeeded può ancora avere billing.status=reserved in attesa dell'utilizzo finale; HTTP 200 non implica contabilità chiusa.

application/json

Tipo
object
Campi obbligatori
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObbligatorio

    Identificatore pubblico dell'oggetto, usato nel relativo percorso dei dettagli.

  • tool_idstringObbligatorio

    ID dello strumento nel catalogo eseguibile della Key corrente.

  • versionstringObbligatorio

    Versione di contratto, funzionalità o strumento; le esecuzioni usano la versione restituita dal catalogo.

  • statusstringObbligatorio

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica invio dall'esito sconosciuto: non cambiare Idempotency-Key per ripetere.

  • outputunknownObbligatorio

    JSON definito da output_schema dello strumento; non presumere che il risultato esista dopo la scadenza.

  • error_codestringFacoltativo

    Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

  • billingobjectObbligatorio

    Stato contabile indipendente, da non sostituire con quello di generazione.

    Campi figli di billing (7)
    • review_requiredbooleanFacoltativo

      Le prove contabili richiedono revisione manuale.

    • reasonstringFacoltativo

      Motivo pubblico dell'azione non disponibile o della revisione contabile.

    • usageunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • breakdownunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • statusstringObbligatorio

      Stato attuale dell'oggetto; valutare separatamente contabilità e salvataggio.

    • reserved_usdstringObbligatorio

      Prenotazione massima in dollari, come stringa.

    • charged_usdstringObbligatorio

      Importo attualmente confermato in dollari, come stringa.

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: status, reserved_usd, charged_usd

    • review_requiredbooleanFacoltativo

      Le prove contabili richiedono revisione manuale.

    • reasonstringFacoltativo

      Motivo pubblico dell'azione non disponibile o della revisione contabile.

    • usageunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • breakdownunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • statusstringObbligatorio

      Stato attuale dell'oggetto; valutare separatamente contabilità e salvataggio.

    • reserved_usdstringObbligatorio

      Prenotazione massima in dollari, come stringa.

    • charged_usdstringObbligatorio

      Importo attualmente confermato in dollari, come stringa.

  • result_expiredbooleanObbligatorio

    Indica se il risultato è scaduto; contabilità e idempotenza restano conservate.

  • created_atintegerObbligatorio

    Ora di creazione in secondi Unix.

  • updated_atintegerObbligatorio

    Ultimo aggiornamento in secondi Unix.

HTTP 202

Stato submitting, running o submission_unknown: richiesta accettata, ma contabilità da valutare separatamente tramite billing.

application/json

Tipo
object
Campi obbligatori
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObbligatorio

    Identificatore pubblico dell'oggetto, usato nel relativo percorso dei dettagli.

  • tool_idstringObbligatorio

    ID dello strumento nel catalogo eseguibile della Key corrente.

  • versionstringObbligatorio

    Versione di contratto, funzionalità o strumento; le esecuzioni usano la versione restituita dal catalogo.

  • statusstringObbligatorio

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica invio dall'esito sconosciuto: non cambiare Idempotency-Key per ripetere.

  • outputunknownObbligatorio

    JSON definito da output_schema dello strumento; non presumere che il risultato esista dopo la scadenza.

  • error_codestringFacoltativo

    Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

  • billingobjectObbligatorio

    Stato contabile indipendente, da non sostituire con quello di generazione.

    Campi figli di billing (7)
    • review_requiredbooleanFacoltativo

      Le prove contabili richiedono revisione manuale.

    • reasonstringFacoltativo

      Motivo pubblico dell'azione non disponibile o della revisione contabile.

    • usageunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • breakdownunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • statusstringObbligatorio

      Stato attuale dell'oggetto; valutare separatamente contabilità e salvataggio.

    • reserved_usdstringObbligatorio

      Prenotazione massima in dollari, come stringa.

    • charged_usdstringObbligatorio

      Importo attualmente confermato in dollari, come stringa.

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: status, reserved_usd, charged_usd

    • review_requiredbooleanFacoltativo

      Le prove contabili richiedono revisione manuale.

    • reasonstringFacoltativo

      Motivo pubblico dell'azione non disponibile o della revisione contabile.

    • usageunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • breakdownunknownFacoltativo

      Valore JSON definito dallo schema o protocollo dello strumento scelto; non presumere campi fissi.

    • statusstringObbligatorio

      Stato attuale dell'oggetto; valutare separatamente contabilità e salvataggio.

    • reserved_usdstringObbligatorio

      Prenotazione massima in dollari, come stringa.

    • charged_usdstringObbligatorio

      Importo attualmente confermato in dollari, come stringa.

  • result_expiredbooleanObbligatorio

    Indica se il risultato è scaduto; contabilità e idempotenza restano conservate.

  • created_atintegerObbligatorio

    Ora di creazione in secondi Unix.

  • updated_atintegerObbligatorio

    Ultimo aggiornamento in secondi Unix.

HTTP 400

Campi o parametri della richiesta non validi.

application/json

Tipo
object
Campi obbligatori
error

HTTP 401

Key assente, non valida, scaduta o revocata.

application/json

Tipo
object
Campi obbligatori
error

HTTP 403

Autorizzazioni IP, account, modello o strumento insufficienti.

application/json

Tipo
object
Campi obbligatori
error

HTTP 404

Oggetto/funzionalità non disponibile o disabilitata.

application/json

Tipo
object
Campi obbligatori
error

HTTP 409

Conflitto di idempotenza/preventivo, oggetto non pronto o ancora referenziato.

application/json

Tipo
object
Campi obbligatori
error

HTTP 429

Limite di frequenza delle richieste/della coda.

application/json

Tipo
object
Campi obbligatori
error

HTTP 500

Errore interno di autenticazione o storage dei dati.

application/json

Tipo
object
Campi obbligatori
error

HTTP 503

Servizio, prezzi o storage non disponibile.

application/json

Tipo
object
Campi obbligatori
error

Note sull'endpoint

Esempio per uno strumento requires_usage=true: sostituisci quote_id e max_cost_usd; il budget deve essere una stringa decimale valida in dollari, almeno pari a maximum_usd del preventivo. 0.01 è solo illustrativo. Per regole input con preventivo ma senza utilizzo finale, il budget è facoltativo; per prezzi costanti senza utilizzo finale, preventivo e budget sono facoltativi. Prima dell'invio conserva identità della Key, chiave di richiesta e corpo completo; riusali se la risposta va persa.