queue_id e depois faça polling em /video/retrieve até a resposta ser video/mp4.
Endpoints
Passo 1: Coloque a geração na fila
Requisição:download_url:
download_url é uma URL pré-assinada que você usa para baixar o vídeo finalizado em vez de lê-lo na resposta de retrieve. É retornado apenas uma vez na resposta de fila, então persista-o ao lado do queue_id. Isso se aplica às quatro variantes 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, modelos Grok Imagine Private não são cobrados por rejeições de moderação de conteúdo, então você só paga por gerações bem-sucedidas.
Salve model, queue_id e download_url (se presente) para todas as chamadas subsequentes.
Links de download privados
Para modelos privados,download_url é como você busca o arquivo finalizado quando o job está concluído. O link é de curta duração e propósito único: está ali para entregar o MP4 a você, não para servir como URL de longo prazo ou amplamente compartilhada.
Se um download for interrompido, você pode repetir o mesmo GET algumas vezes do mesmo ambiente até o arquivo concluir. Essas tentativas são para recuperar de instabilidades de rede — não para fazer polling do mesmo link indefinidamente, compartilhá-lo entre muitos clientes ou embuti-lo como uma URL de mídia permanente. Padrões assim normalmente aparecem como 429 ou 410, o que pode ser surpreendente se você esperava que o link se comportasse como hospedagem de arquivos normal.
Para confiabilidade, as requisições GET devem ter origem de uma única rede cliente. Há alguma flexibilidade se seu IP mudar uma vez (por exemplo, você desconecta uma VPN e tenta de novo), mas grande variação nos IPs de origem geralmente não funciona.
A URL permanece válida por até 24 horas ou até o objeto ser removido.
Se você precisa de uma URL estável, reprodução pública ou acesso repetido ao longo do tempo, salve o arquivo no seu próprio storage primeiro e sirva a partir de lá.
DELETE
Quando terminar de buscar o arquivo — ou se decidir não mantê-lo — você pode chamar DELETE na mesma download_url. Nenhuma chave de API Venice é necessária nessa requisição. Isso é opcional, mas recomendado quando a privacidade importa, porque alguns proxies e middleboxes fora da Venice mantêm logs de URLs completas, e excluir o link é a maneira mais simples de reduzir a janela em que a URL pré-assinada existe.
/video/retrieve até COMPLETED → faça GET no download_url (tente novamente de leve se a transferência cair) → salve o arquivo onde você precisa → DELETE no download_url se quiser invalidar o link → opcionalmente chame /video/complete se ainda usa limpeza baseada em fila.
Passo 2: Polling para conclusão
Requisição:
Resposta de processamento (200, application/json):
average_execution_time para estimar a espera restante.
Resposta de conclusão (200, video/mp4):
O corpo da resposta é dado binário cru de vídeo. Salve no arquivo.
Resposta de conclusão (200, application/json com "COMPLETED"):
Para modelos que retornaram um download_url na fila, o retrieve sempre retorna JSON. Busque o vídeo com GET download_url (sem cabeçalho de autenticação). Veja Links de download privados para como essas URLs funcionam, retries e DELETE opcional.
Passo 3: Limpeza (opcional)
Ou exclua automaticamente na recuperação:/video/complete após salvar:
Exemplo completo
Parâmetros da requisição
Requisição de fila
A validação da fila é específica do modelo. Verifique
/models?type=video para os campos de requisição suportados por cada modelo antes de chamar /video/queue.
Requisição de cotação
Requisição de retrieve
Requisição de complete
Image to Video
Para modelos image-to-video, passe a imagem de origem viaimage_url. O prompt descreve o movimento desejado, não o conteúdo da imagem.
Cotação de preço
Obtenha o custo exato antes de gerar. Envie apenas inputs de preço (model, duration e opcionalmente resolution, aspect_ratio, audio):
Requisição:
Erros
Estratégia de polling
- Faça polling de
/video/retrieveem um intervalo (por exemplo, a cada 5 segundos) - Se
Content-Typeforapplication/jsonestatusfor"PROCESSING", aguarde e faça polling novamente. Useaverage_execution_timeeexecution_duration(milissegundos) para estimar o tempo restante - Se
Content-Typeforvideo/mp4, salve o corpo da resposta como seu arquivo de saída - Se
Content-Typeforapplication/jsonestatusfor"COMPLETED", façaGETnodownload_urlda resposta de fila para buscar o vídeo (veja Links de download privados) - Se você usou
download_url, considereDELETEnessa URL quando terminar para reduzir por quanto tempo a URL pré-assinada existe; depois opcionalmente definadelete_media_on_completion: trueno retrieve ou chame/video/completepara limpeza baseada em fila - Trate
404como mídia inválida, expirada ou excluída; trate500/503com retries/backoff