Pular para o conteúdo principal
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.

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.