Documentazione

Riferimento API

Crea un'attività immagine persistente

POST/v1/image-tasks

quote_id valido e Idempotency-Key devono corrispondere. Esecuzione singola in background con contabilità/archiviazione; niente reinvii alla cieca per unknown o billing_review. Richiesta massima 128 KiB, campi sconosciuti rifiutati.

Dal preventivo al risultato

Prepara prima input disponibili, ottieni il preventivo e, dopo conferma esplicita, invia quote_id insieme ai parametri originali. Il preventivo non blocca le risorse. Se l'utente le elimina prima di confermare, la creazione può fallire; correggi allora gli input e richiedi un nuovo preventivo.

L'applicazione deve conservare sia la chiave di richiesta aziendale sia l'ID dell'attività. Dopo una disconnessione del client recupera tramite la chiave originale, senza rigenerare per uno stato sconosciuto. Anche in caso di successo parziale, verifica ogni risultato e il suo stato di salvataggio prima di decidere il download. Vedi Attività asincrone e idempotenza.

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
modelpromptsize
Proprietà aggiuntive
false

Corpo della richiesta obbligatorio

  • modelstringObbligatorio

    ID pubblico del modello nel catalogo della Key corrente.

    Lunghezza massima
    191
  • promptstringObbligatorio

    Non vuoto, massimo 32000 byte UTF-8. OpenAPI maxLength conta i caratteri; non viene inventato un limite di caratteri.

  • sizestringObbligatorio

    Dimensione restituita da image-models per il modello scelto; capacità e dimensioni validate separatamente per modello.

  • nintegerFacoltativo

    Omesso o 0 è normalizzato a 1. Il massimo effettivo è max_n di image-models; il limite globale non è una capacità del modello.

    Valore predefinito
    1
    Minimo
    1
    Massimo
    6
  • referencesarrayFacoltativo

    Ogni elemento sceglie solo file_id, asset_id oppure url; quantità effettiva secondo max_references.

    Numero massimo di elementi
    14
    Campi figli di references (1)
    • []objectFacoltativo
      Campi figli di [] (3)
      • file_idstringFacoltativo

        ID pubblico del file ospitato dello stesso account e della stessa Key.

      • asset_idstringFacoltativo

        ID risorsa caricata dello stesso account e della stessa Key.

      • urlstringFacoltativo

        URL HTTPS pubblico, senza userinfo o fragment; soggetto a verifica SSRF.

        Formato
        "uri"
      Ramo oneOf 1

      Obbligatorio in questo ramo: file_id

      Ramo oneOf 2

      Obbligatorio in questo ramo: asset_id

      Ramo oneOf 3

      Obbligatorio in questo ramo: url

  • source_task_idstringFacoltativo

    Attività sorgente facoltativa della stessa Key, solo per tracciabilità; non sostituisce references.

    Lunghezza massima
    64
  • quote_idstringFacoltativo

    Alla creazione deve essere un preventivo valido e corrispondente alla richiesta; ignorato nelle richieste di preventivo.

Risposte ed errori

HTTP 202

Attività immagine persistente creata

application/json

Tipo
object
Campi obbligatori
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringObbligatorio

    ID pubblico del modello nel catalogo della Key corrente.

  • promptstringObbligatorio

    Prompt di generazione.

  • sizestringObbligatorio

    Dimensione restituita da image-models per il modello scelto; capacità e dimensioni validate separatamente per modello.

  • nintegerObbligatorio

    Numero di immagini richiesto, sempre soggetto al massimo del modello.

  • referencesarrayObbligatorio

    Elenco delle immagini di riferimento per la generazione.

    Campi figli di references (1)
    • []objectFacoltativo
      Campi figli di [] (3)
      • file_idstringFacoltativo

        ID pubblico del file ospitato dello stesso account e della stessa Key.

      • asset_idstringFacoltativo

        ID risorsa caricata dello stesso account e della stessa Key.

      • urlstringFacoltativo

        URL HTTPS pubblico, senza userinfo o fragment; soggetto a verifica SSRF.

        Formato
        "uri"
      Ramo oneOf 1

      Obbligatorio in questo ramo: file_id

      Ramo oneOf 2

      Obbligatorio in questo ramo: asset_id

      Ramo oneOf 3

      Obbligatorio in questo ramo: url

  • source_task_idstringFacoltativo

    ID pubblico dell'attività sorgente, solo per tracciabilità.

  • quote_idstringFacoltativo

    ID pubblico del preventivo; alla creazione deve rispettare i vincoli di prezzo/richiesta.

  • idstringObbligatorio

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

  • statusstringObbligatorio

    unknown non viene reinviato automaticamente; la prenotazione contabile può restare pending.

    Enumerazione
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerObbligatorio

    Ora di creazione in secondi Unix.

  • updated_atintegerObbligatorio

    Ultimo aggiornamento in secondi Unix.

  • reserved_quotaintegerObbligatorio

    Prenotazione in unità quota della piattaforma, non in dollari.

  • final_quotaintegerObbligatorio

    Costo finale in unità quota della piattaforma; null indica non determinato.

  • billing_statusstringObbligatorio

    Stato di prenotazione/addebito/rimborso, da verificare separatamente dall'attività e dall'archiviazione.

  • error_codestringFacoltativo

    Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

  • error_messagestringFacoltativo

    Spiegazione per l'utente secondo la classificazione pubblica degli errori.

  • resultsarrayObbligatorio

    Elementi generati in uscita; archiviazione indipendente per ciascuno.

    Campi figli di results (1)
    • []objectFacoltativo
      Campi figli di [] (7)
      • file_idstringFacoltativo

        ID pubblico del file ospitato dello stesso account e della stessa Key.

      • storage_statusstringFacoltativo

        Stato di archiviazione del file; il download ospitato è garantito solo dopo ready.

      • storage_errorstringFacoltativo

        Categoria pubblica dell'errore di archiviazione del file.

      • expires_atintegerFacoltativo

        Scadenza in secondi Unix; 0 indica nessuna scadenza fissa.

      • urlstringFacoltativo

        URL di accesso al risultato o riferimento; gli URL firmati sono temporanei.

      • b64_jsonstringFacoltativo

        Stringa Base64 dell'immagine; non richiederla come URL.

      • revised_promptstringFacoltativo

        Prompt rivisto restituito dal servizio, se presente.

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