Vai al contenuto principale
La generazione video è asincrona. Invia un job, salva il queue_id, poi fai polling su /video/retrieve finché la risposta non è video/mp4.

Endpoint

Passo 1: Metti in coda la generazione

Richiesta:
Risposta (200):
Per i modelli Grok Imagine Private, la risposta della queue include un campo extra download_url:
download_url è un URL pre-firmato che usi per scaricare il video completato invece di leggerlo dalla risposta di retrieve. Viene restituito solo una volta nella risposta della queue, quindi conservalo insieme al queue_id. Questo si applica a tutte e quattro le varianti Grok Imagine Private:
  • grok-imagine-text-to-video-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
A differenza delle varianti pubbliche grok-imagine-*-video, i modelli Grok Imagine Private non vengono addebitati per i rifiuti di content moderation, quindi paghi solo per le generazioni andate a buon fine. Salva model, queue_id e download_url (se presente) per tutte le chiamate successive. Per i modelli privati, download_url è il modo in cui recuperi il file completato una volta che il job è terminato. Il link è a vita breve e monouso: serve per consegnarti l’MP4, non come URL a lungo termine o ampiamente condiviso. Se un download viene interrotto, puoi riprovare la stessa GET un paio di volte dallo stesso ambiente finché il file non termina. Quei retry servono per recuperare da intoppi di rete, non per fare polling indefinito sullo stesso link, condividerlo tra molti client o incorporarlo come URL multimediale permanente. Pattern di quel tipo spesso si manifestano come 429 o 410, il che può sorprendere se ti aspettavi che il link si comportasse come un normale file hosting. Per affidabilità, le richieste GET dovrebbero originare da una sola rete client. C’è una certa flessibilità se il tuo IP cambia una volta (per esempio se disconnetti una VPN e riprovi), ma una grande variazione di IP sorgente di solito non funzionerà. L’URL rimane valido fino a 24 ore, o finché l’oggetto non viene rimosso.
Se hai bisogno di un URL stabile, di playback pubblico o di accesso ripetuto nel tempo, salva il file prima nel tuo storage e servilo da lì.
Privacy: revoca il link con DELETE Quando hai finito di recuperare il file, o se decidi di non conservarlo, puoi chiamare DELETE sullo stesso download_url. Non è richiesta alcuna Venice API key su quella richiesta. Questo è opzionale ma consigliato quando la privacy è importante, perché alcuni proxy e middlebox al di fuori di Venice mantengono log degli URL completi, e cancellare il link è il modo più semplice per restringere la finestra in cui l’URL pre-firmato esiste.
Flusso: poll su /video/retrieve finché COMPLETEDGET sul download_url (riprova con leggerezza se il trasferimento cade) → salva il file dove ti serve → DELETE sul download_url se vuoi invalidare il link → opzionalmente chiama /video/complete se usi ancora la pulizia basata su queue.

Passo 2: Fai polling per il completamento

Richiesta:
La risposta dipende dallo stato: Risposta di elaborazione (200, application/json):
I tempi sono in millisecondi. Usa average_execution_time per stimare il tempo di attesa rimanente. Risposta completata (200, video/mp4): Il corpo della risposta è dato video binario raw. Salvalo in un file. Risposta completata (200, application/json con "COMPLETED"): Per i modelli che hanno restituito un download_url al momento della queue, retrieve restituisce sempre JSON. Recupera il video con GET download_url (senza header di auth). Vedi Link di download privati per il funzionamento di questi URL, i retry e il DELETE opzionale.

Passo 3: Pulizia (opzionale)

O auto-elimina al recupero:
O chiama /video/complete dopo il salvataggio:
Risposta (200):

Esempio completo


Parametri della richiesta

Queue Request

La validazione della queue è specifica per ogni modello. Controlla /models?type=video per i campi di richiesta supportati da ogni modello prima di chiamare /video/queue.

Quote Request

Retrieve Request

Complete Request


Image to Video

Per i modelli image-to-video, passa l’immagine sorgente tramite image_url. Il prompt descrive il movimento desiderato, non il contenuto dell’immagine.
Oppure con base64:

Preventivo del prezzo

Ottieni il costo esatto prima di generare. Invia solo gli input di pricing (model, duration e opzionali resolution, aspect_ratio, audio): Richiesta:
Risposta:
Il preventivo è in USD.

Errori


Strategia di polling

  1. Fai polling su /video/retrieve a intervalli (per esempio, ogni 5 secondi)
  2. Se il Content-Type è application/json e lo status è "PROCESSING", attendi e fai di nuovo polling. Usa average_execution_time ed execution_duration (millisecondi) per stimare il tempo rimanente
  3. Se il Content-Type è video/mp4, salva il corpo della risposta come file di output
  4. Se il Content-Type è application/json e lo status è "COMPLETED", GET sul download_url dalla risposta della queue per recuperare il video (vedi Link di download privati)
  5. Se hai usato download_url, considera di fare DELETE su quell’URL quando hai finito per restringere quanto a lungo l’URL pre-firmato esiste; poi opzionalmente imposta delete_media_on_completion: true su retrieve o chiama /video/complete per la pulizia basata su queue
  6. Gestisci 404 come media non valido, scaduto o eliminato; gestisci 500/503 con retry/backoff

Modelli disponibili

Consulta Modelli video per la lista attuale dei modelli e i prezzi.