Skip to main content
A geração de vídeo é assíncrona. Envie um job, salve o 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:
Resposta (200):
Para modelos Grok Imagine Private, a resposta de fila inclui um campo extra download_url:
O 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-private
  • grok-imagine-image-to-video-private
  • grok-imagine-reference-to-video-private
  • grok-imagine-video-to-video-private
Ao contrário das variantes públicas 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. 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á.
Privacidade: revogue o link com 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.
Fluxo: faça polling em /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:
A resposta depende do status: Resposta de processamento (200, application/json):
Os tempos estão em milissegundos. Use 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:
Ou chame /video/complete após salvar:
Resposta (200):

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 via image_url. O prompt descreve o movimento desejado, não o conteúdo da imagem.
Ou com base64:

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:
Resposta:
A cotação está em USD.
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), passe reference_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

  1. Faça polling de /video/retrieve em um intervalo (por exemplo, a cada 5 segundos)
  2. Se Content-Type for application/json e status for "PROCESSING", aguarde e faça polling novamente. Use average_execution_time e execution_duration (milissegundos) para estimar o tempo restante
  3. Se Content-Type for video/mp4, salve o corpo da resposta como seu arquivo de saída
  4. Se Content-Type for application/json e status for "COMPLETED", faça GET no download_url da resposta de fila para buscar o vídeo (veja Links de download privados)
  5. Se você usou download_url, considere DELETE nessa URL quando terminar para reduzir por quanto tempo a URL pré-assinada existe; depois opcionalmente defina delete_media_on_completion: true no retrieve ou chame /video/complete para limpeza baseada em fila
  6. Trate 404 como mídia inválida, expirada ou excluída; trate 500/503 com retries/backoff

Modelos disponíveis

Veja Modelos de vídeo para a lista de modelos atual e preços.