Documentazione

Riferimento API

Crea un'attività di generazione video

POST/v1/videos

Il worker persistente gestisce in background invio, interrogazioni, contabilità e salvataggio; il client osserva senza attivare l'addebito. Richieste ordinarie e persistent seguono i rispettivi vincoli di modello/fotogrammi ospitati/preventivo. Con unknown/submission_state_unknown non cambiare chiave per reinviare alla cieca.

Flussi ordinari e persistenti

I video ordinari usano gli input HTTPS pubblici previsti dal modello. I video persistenti usano retention=persistent, un preset completo del catalogo, fotogrammi ospitati e un preventivo valido. Non inserire i campi dei fotogrammi dell'area di lavoro nelle richieste ordinarie e non ricombinare parametri di preset diversi.

Il background gestisce esecuzione, contabilità e salvataggio; le interrogazioni del client osservano soltanto il record. La prenotazione stimata può comportare ulteriori addebiti o restituzioni. Se il salvataggio fallisce dopo il successo, riprova l'archiviazione del risultato originale senza rigenerarlo. Per invii sconosciuti, recupera prima tramite la chiave di richiesta originale. 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
    Lunghezza minima
    1
    Lunghezza massima
    191
    Pattern
    "^[\\x20-\\x7E]{1,191}$"

Corpo della richiesta · application/json

Tipo
object
Campi obbligatori
modelprompt
Proprietà aggiuntive
false

Corpo della richiesta obbligatorio

  • modestringFacoltativo

    Obbligatorio per persistent.

    Enumerazione
    ["text_to_video","image_to_video"]
  • retentionstringFacoltativo

    persistent usa l'area persistente; se omesso, attività ordinaria.

  • quote_idstringFacoltativo

    Una nuova richiesta persistent richiede prima la conferma di un preventivo valido di video-quotes.

  • start_frameobjectFacoltativo

    Obbligatorio per immagine-video persistent: file ospitato della stessa Key. Vietato per testo-video.

    Campi figli di start_frame (1)
    • file_idstringObbligatorio

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

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: file_id

    • file_idstringObbligatorio

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

  • end_frameobjectFacoltativo

    Fotogramma finale facoltativo per persistent, se supportato.

    Campi figli di end_frame (1)
    • file_idstringObbligatorio

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

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: file_id

    • file_idstringObbligatorio

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

  • webhook_endpoint_idstringFacoltativo

    Le attività ordinarie possono riferire un ricevitore configurato nella console; vietato per persistent.

  • modelstringObbligatorio

    ID pubblico del modello nel catalogo della Key corrente; non garantisce la disponibilità di vecchi modelli del servizio.

  • promptstringObbligatorio

    Prompt di generazione.

    Lunghezza minima
    1
    Lunghezza massima
    2500
  • durationintegerFacoltativo

    Durata secondo modello; usa la combinazione completa di video-models mode.presets, senza prodotto cartesiano. Wan Turbo non supporta questo campo; nessun valore predefinito uniforme.

  • image_urlstringFacoltativo

    Fotogramma iniziale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

  • end_image_urlstringFacoltativo

    Fotogramma finale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

  • resolutionstringFacoltativo

    Risoluzione del preset del modello.

  • aspect_ratiostringFacoltativo

    Rapporto d'aspetto del preset del modello.

  • generate_audiobooleanFacoltativoConsente null

    Dipende dal modello; usa la politica audio e i presets della modalità. Non presumere che tutti i modelli generino audio.

Risposte ed errori

HTTP 202

Attività accettata, non necessariamente completata.

application/json

Tipo
object
Campi obbligatori
idmodelstatuscreated_at
  • updated_atintegerFacoltativo

    Ultimo aggiornamento in secondi Unix.

  • retentionstringFacoltativo

    Politica di conservazione dei risultati; persistent indica l'area persistente.

  • inputobjectFacoltativo

    Input originale dell'attività o input del contratto dello strumento.

    Campi figli di input (14)
    • modestringFacoltativo

      Obbligatorio per persistent.

      Enumerazione
      ["text_to_video","image_to_video"]
    • retentionstringFacoltativo

      persistent usa l'area persistente; se omesso, attività ordinaria.

    • quote_idstringFacoltativo

      Una nuova richiesta persistent richiede prima la conferma di un preventivo valido di video-quotes.

    • start_frameobjectFacoltativo

      Obbligatorio per immagine-video persistent: file ospitato della stessa Key. Vietato per testo-video.

      Campi figli di start_frame (1)
      • file_idstringObbligatorio

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

      Ramo allOf 1

      Tipo: object

      Obbligatorio in questo ramo: file_id

      • file_idstringObbligatorio

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

    • end_frameobjectFacoltativo

      Fotogramma finale facoltativo per persistent, se supportato.

      Campi figli di end_frame (1)
      • file_idstringObbligatorio

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

      Ramo allOf 1

      Tipo: object

      Obbligatorio in questo ramo: file_id

      • file_idstringObbligatorio

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

    • webhook_endpoint_idstringFacoltativo

      Le attività ordinarie possono riferire un ricevitore configurato nella console; vietato per persistent.

    • modelstringObbligatorio

      ID pubblico del modello nel catalogo della Key corrente; non garantisce la disponibilità di vecchi modelli del servizio.

    • promptstringObbligatorio

      Prompt di generazione.

      Lunghezza minima
      1
      Lunghezza massima
      2500
    • durationintegerFacoltativo

      Durata secondo modello; usa la combinazione completa di video-models mode.presets, senza prodotto cartesiano. Wan Turbo non supporta questo campo; nessun valore predefinito uniforme.

    • image_urlstringFacoltativo

      Fotogramma iniziale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

    • end_image_urlstringFacoltativo

      Fotogramma finale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

    • resolutionstringFacoltativo

      Risoluzione del preset del modello.

    • aspect_ratiostringFacoltativo

      Rapporto d'aspetto del preset del modello.

    • generate_audiobooleanFacoltativoConsente null

      Dipende dal modello; usa la politica audio e i presets della modalità. Non presumere che tutti i modelli generino audio.

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: model, prompt

    Proprietà aggiuntive: false

    • modestringFacoltativo

      Obbligatorio per persistent.

      Enumerazione
      ["text_to_video","image_to_video"]
    • retentionstringFacoltativo

      persistent usa l'area persistente; se omesso, attività ordinaria.

    • quote_idstringFacoltativo

      Una nuova richiesta persistent richiede prima la conferma di un preventivo valido di video-quotes.

    • start_frameobjectFacoltativo

      Obbligatorio per immagine-video persistent: file ospitato della stessa Key. Vietato per testo-video.

      Campi figli di start_frame (1)
      • file_idstringObbligatorio

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

      Ramo allOf 1

      Tipo: object

      Obbligatorio in questo ramo: file_id

      • file_idstringObbligatorio

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

    • end_frameobjectFacoltativo

      Fotogramma finale facoltativo per persistent, se supportato.

      Campi figli di end_frame (1)
      • file_idstringObbligatorio

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

      Ramo allOf 1

      Tipo: object

      Obbligatorio in questo ramo: file_id

      • file_idstringObbligatorio

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

    • webhook_endpoint_idstringFacoltativo

      Le attività ordinarie possono riferire un ricevitore configurato nella console; vietato per persistent.

    • modelstringObbligatorio

      ID pubblico del modello nel catalogo della Key corrente; non garantisce la disponibilità di vecchi modelli del servizio.

    • promptstringObbligatorio

      Prompt di generazione.

      Lunghezza minima
      1
      Lunghezza massima
      2500
    • durationintegerFacoltativo

      Durata secondo modello; usa la combinazione completa di video-models mode.presets, senza prodotto cartesiano. Wan Turbo non supporta questo campo; nessun valore predefinito uniforme.

    • image_urlstringFacoltativo

      Fotogramma iniziale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

    • end_image_urlstringFacoltativo

      Fotogramma finale HTTPS secondo modello, solo attività ordinarie; vietato per persistent.

    • resolutionstringFacoltativo

      Risoluzione del preset del modello.

    • aspect_ratiostringFacoltativo

      Rapporto d'aspetto del preset del modello.

    • generate_audiobooleanFacoltativoConsente null

      Dipende dal modello; usa la politica audio e i presets della modalità. Non presumere che tutti i modelli generino audio.

  • billingobjectFacoltativo

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

    Campi figli di billing (7)
    • currencystringObbligatorio

      Valuta del preventivo/della contabilità.

    • error_codestringFacoltativo

      Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

    • statusstringObbligatorio

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

    • reserved_quotaintegerObbligatorio

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

    • final_quotaintegerObbligatorioConsente null

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

    • reserved_amountstringObbligatorio

      Prenotazione massima, stringa nella valuta del preventivo.

    • final_amountstringObbligatorioConsente null

      Costo finale come stringa; null indica contabilità non chiusa.

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: currency, status, reserved_quota, final_quota, reserved_amount, final_amount

    • currencystringObbligatorio

      Valuta del preventivo/della contabilità.

    • error_codestringFacoltativo

      Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

    • statusstringObbligatorio

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

    • reserved_quotaintegerObbligatorio

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

    • final_quotaintegerObbligatorioConsente null

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

    • reserved_amountstringObbligatorio

      Prenotazione massima, stringa nella valuta del preventivo.

    • final_amountstringObbligatorioConsente null

      Costo finale come stringa; null indica contabilità non chiusa.

  • storageobjectFacoltativo

    Stato indipendente di salvataggio del file.

    Campi figli di storage (3)
    • file_idstringFacoltativo

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

    • statusstringObbligatorio

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

    • error_codestringFacoltativo

      Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: status

    • file_idstringFacoltativo

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

    • statusstringObbligatorio

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

    • error_codestringFacoltativo

      Codice errore pubblico utilizzabile per scegliere il ramo di gestione.

  • availabilityobjectFacoltativo

    Funzionalità attuali dell'operazione.

    Campi figli di availability (4)
    • can_cancelbooleanObbligatorio

      Indica se è possibile richiedere l'annullamento dell'attività corrente.

    • can_deletebooleanObbligatorio

      Indica se l'attività corrente può essere eliminata.

    • can_retry_storagebooleanObbligatorio

      Indica se è possibile riprovare il salvataggio dell'attività.

    • reasonstringFacoltativo

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

    Ramo allOf 1

    Tipo: object

    Obbligatorio in questo ramo: can_cancel, can_delete, can_retry_storage

    • can_cancelbooleanObbligatorio

      Indica se è possibile richiedere l'annullamento dell'attività corrente.

    • can_deletebooleanObbligatorio

      Indica se l'attività corrente può essere eliminata.

    • can_retry_storagebooleanObbligatorio

      Indica se è possibile riprovare il salvataggio dell'attività.

    • reasonstringFacoltativo

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

  • idstringObbligatorio

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

  • modelstringObbligatorio

    ID pubblico del modello nel catalogo della Key corrente.

  • statusstringObbligatorio

    Stato delle attività ordinarie e persistenti: pending_dispatch/submitting/queued/processing/succeeded/failed/cancelled/unknown. Uno stato terminale non implica contabilità definitiva o archiviazione ready.

  • created_atintegerObbligatorio

    Ora di creazione in secondi Unix.

  • resultobjectFacoltativo

    Metadati del risultato pronto, eventualmente assenti prima del completamento.

    Campi figli di result (8)
    • 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.

    • deliverystringFacoltativo

      authenticated_content richiede il percorso del contenuto; non presumere un URL diretto.

    • content_pathstringFacoltativo

      Percorso del contenuto autenticato della piattaforma; richiedi i byte con la stessa Key.

    • urlstringFacoltativo

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

    • content_typestringFacoltativo

      Tipo MIME del risultato.

    • file_namestringFacoltativo

      Nome pubblico del file scaricato.

    • file_sizeintegerFacoltativo

      Dimensione del file risultato in byte.

    Ramo allOf 1

    Tipo: object

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

    • deliverystringFacoltativo

      authenticated_content richiede il percorso del contenuto; non presumere un URL diretto.

    • content_pathstringFacoltativo

      Percorso del contenuto autenticato della piattaforma; richiedi i byte con la stessa Key.

    • urlstringFacoltativo

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

    • content_typestringFacoltativo

      Tipo MIME del risultato.

    • file_namestringFacoltativo

      Nome pubblico del file scaricato.

    • file_sizeintegerFacoltativo

      Dimensione del file risultato in byte.

  • errorstringFacoltativo

    Categoria di errore o oggetto errore pubblico.

HTTP 400

Parametri della richiesta errati.

application/json

Tipo
object
Campi obbligatori
error
  • errorobjectObbligatorio
    Campi figli di error (3)
    • messagestringObbligatorio
    • typestringObbligatorio
      Enumerazione
      ["new_api_error"]
    • codestringObbligatorio

HTTP 401

Key assente, non valida, scaduta o revocata.

application/json

Tipo
object
Campi obbligatori
error

HTTP 402

Quota disponibile dell'account o della Key insufficiente.

application/json

Tipo
object
Campi obbligatori
error
  • errorobjectObbligatorio
    Campi figli di error (3)
    • messagestringObbligatorio
    • typestringObbligatorio
      Enumerazione
      ["new_api_error"]
    • codestringObbligatorio

HTTP 403

Key corrente non autorizzata.

application/json

Tipo
object
Campi obbligatori
error
  • errorobjectObbligatorio
    Campi figli di error (3)
    • messagestringObbligatorio
    • typestringObbligatorio
      Enumerazione
      ["new_api_error"]
    • codestringObbligatorio

HTTP 409

Conflitto, risultato non pronto o invio sconosciuto: consulta prima il record originale, senza reinvii alla cieca.

application/json

Tipo
object
Campi obbligatori
error
  • errorobjectObbligatorio
    Campi figli di error (3)
    • messagestringObbligatorio
    • typestringObbligatorio
      Enumerazione
      ["new_api_error"]
    • codestringObbligatorio

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, storage, prezzi temporaneamente non disponibile.

application/json

Tipo
object
Campi obbligatori
error
  • errorobjectObbligatorio
    Campi figli di error (3)
    • messagestringObbligatorio
    • typestringObbligatorio
      Enumerazione
      ["new_api_error"]
    • codestringObbligatorio