queue_id, poi fai polling su /video/retrieve finché la risposta non è video/mp4.
Endpoint
Passo 1: Metti in coda la generazione
Richiesta: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-privategrok-imagine-image-to-video-privategrok-imagine-reference-to-video-privategrok-imagine-video-to-video-private
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.
Link di download privati
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ì.
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.
/video/retrieve finché COMPLETED → GET 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:
Risposta di elaborazione (200, application/json):
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:/video/complete dopo il salvataggio:
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 tramiteimage_url. Il prompt descrive il movimento desiderato, non il contenuto dell’immagine.
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:
Errori
Strategia di polling
- Fai polling su
/video/retrievea intervalli (per esempio, ogni 5 secondi) - Se il
Content-Typeèapplication/jsone lostatusè"PROCESSING", attendi e fai di nuovo polling. Usaaverage_execution_timeedexecution_duration(millisecondi) per stimare il tempo rimanente - Se il
Content-Typeèvideo/mp4, salva il corpo della risposta come file di output - Se il
Content-Typeèapplication/jsone lostatusè"COMPLETED",GETsuldownload_urldalla risposta della queue per recuperare il video (vedi Link di download privati) - Se hai usato
download_url, considera di fareDELETEsu quell’URL quando hai finito per restringere quanto a lungo l’URL pre-firmato esiste; poi opzionalmente impostadelete_media_on_completion: truesu retrieve o chiama/video/completeper la pulizia basata su queue - Gestisci
404come media non valido, scaduto o eliminato; gestisci500/503con retry/backoff