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:
Os parâmetros de cotação são apenas inputs de preço. Os campos que você envia para
/video/quote — incluindo aspect_ratio, audio e reference_video_total_duration — são usados exclusivamente para calcular o preço. Eles não são encaminhados para /video/queue e não afetam o vídeo gerado. Enviar aspect_ratio para a cotação é aceito mesmo para modelos (como seedance-2-0-image-to-video) que rejeitam aspect_ratio no momento da geração, já que modelos image-to-video derivam o aspect ratio de saída a partir da imagem de entrada.Preços de reference-to-video
Para modelos R2V (por exemplo, Seedance 2.0 R2V), passereference_video_total_duration — a duração agregada em segundos de todos os clipes de referência que você planeja incluir — para que a cotação reflita a faixa de preço “input with video” e a fórmula de tokens (input + output) × pixels. Omita-o e a cotação retornará a linha de base sem referência.
reference_video_total_duration só é reconhecido por /video/quote. Ele não tem efeito em /video/queue e omiti-lo não causará erro de geração.
Exibindo preços estáveis
As cotações são pontuais e os preços podem mudar. Se você quiser exibir um preço fixo no seu app, chame/video/quote uma vez para cada combinação de parâmetros que você suporta e faça cache do resultado no seu próprio store — depois refaça a cotação em um schedule (ou em atualizações da lista de preços) para renovar o valor em cache. Não existe endpoint de cotação “travada” ou “estática”.
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