Endpoint /v1/videos/generations: O Seu Primeiro Vídeo
Nesta página
Atualizado a 3 de novembro de 2026 com base na documentação de vídeo da xAI: estão disponíveis três modelos de vídeo (
grok-imagine-video-1.5, a sua versão-liteegrok-imagine-video), a resolução vai até 1080p nos modelos 1.5, os vídeos incluem uma faixa de áudio por predefinição (generate_audio), os limites de taxa contam em pedidos por segundo e o parâmetrosizeapresentado na versão antiga não consta na referência da API. Fontes: Geração de Vídeo · Preços.
Gerar um Vídeo a Partir de Texto
A API da xAI disponibiliza um endpoint dedicado para vídeo, POST /v1/videos/generations, que transforma uma descrição escrita numa sequência animada utilizando um dos três modelos Grok Imagine Video. Encare-o como um estúdio sob demanda: descreve uma cena, o modelo dá-lhe movimento e obtém um ficheiro MP4 pronto para edição. Clipes promocionais, visualizações de conceitos, animações ilustrativas — todos estes casos de uso passam por este mesmo endpoint, pelo que vamos dissecá-lo primeiro.
O exemplo acima dá-lhe uma ideia do resultado esperado. Antes de escrever o seu primeiro pedido, tenha em mente os quatro limites que enquadram tudo o que produz com estes modelos.
Estrutura do Pedido
O corpo do pedido é um objeto JSON de uma simplicidade reconfortante. Declara o modelo, escreve o seu prompt e enquadra o resultado com três parâmetros de formatação.
{
"model": "grok-imagine-video",
"prompt": "A dolphin jumping in a sunset",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Eis o significado exato de cada campo:
- model:
grok-imagine-video-1.5, o mais recente, a sua versão económicagrok-imagine-video-1.5-lite, recomendada pela xAI para vídeos simples, ougrok-imagine-video, a geração anterior, ainda utilizada nos exemplos deste curso - prompt: a sua descrição textual da cena desejada
- duration: duração em segundos, entre 1 e 15 (8 por predefinição)
- aspect_ratio: proporção da imagem (16:9 por predefinição, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
- resolution:
480p(predefinição),720pou1080p— esta última renderizada nativamente pelogrok-imagine-video-1.5em texto-para-vídeo e imagem-para-vídeo, obtida por amostragem ascendente (upsampling) de 720p na versão-litee ausente nogrok-imagine-video, que para nos 720p
Dois pontos merecem ênfase imediata. O modelo grok-imagine-video custa $0.050 por segundo de vídeo gerado ($0.08 para grok-imagine-video-1.5, $0.02 para a sua versão -lite, valores de 3 de novembro de 2026): uma sequência de cinco segundos custa-lhe, portanto, $0.25 com o primeiro, independentemente de quantas tentativas foram necessárias para lá chegar. E o limite de taxa conta em pedidos por segundo, dependendo do nível da sua equipa: 10 no nível de entrada para modelos de vídeo, uma margem confortável para uso normal, que se torna uma restrição quando lança lotes massivos.
Mais importante ainda, a geração é assíncrona. A sua chamada POST não devolve um vídeo: devolve um request_id, cabendo-lhe depois sondar o estado até que o ficheiro esteja pronto. Este mecanismo de sondagem é objeto de uma lição completa mais adiante no curso; por agora, lembre-se apenas de que a resposta imediata é um acusar de receção, não um resultado.
Uma Primeira Chamada de Ponta a Ponta
Passemos à prática com curl. O seguinte pedido encomenda uma sequência de cinco segundos em 720p, formato paisagem.
curl -X POST "https://api.x.ai/v1/videos/generations" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video",
"prompt": "A cat playing with a ball of yarn in a bright living room",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'
A resposta cabe numa única linha:
{
"request_id": "vid_abc123def456"
}
Guarde este identificador com cuidado. É a sua única forma de recuperar o vídeo assim que a geração estiver concluída, e uma aplicação que o perca pagou por uma geração que nunca recuperará. Num serviço real, regista-o antes mesmo de iniciar a sondagem.
Áudio, por Predefinição
Um vídeo gerado inclui uma faixa de áudio por predefinição — com, no grok-imagine-video-1.5 e na sua versão -lite, fala sincronizada com o movimento dos lábios. Para um vídeo silencioso, destinado por exemplo a um fundo de site ou para edição onde adicionará a sua própria música, adicione "generate_audio": false ao pedido.
Para enquadrar o resultado, no entanto, a API apenas conhece a proporção (aspect_ratio) e a definição (resolution): a referência da API não fornece nenhum parâmetro de tamanho em píxeis. Em imagem-para-vídeo, a proporção de saída segue sempre a da imagem de origem.
Pontos-chave
- O endpoint é
POST /v1/videos/generations, comgrok-imagine-video-1.5, a sua versão-liteougrok-imagine-video - A duração varia entre 1 e 15 segundos (8 por predefinição), a resolução de 480p a 1080p (máximo 720p com
grok-imagine-video) - O preço conta por segundo gerado: $0.020 (
-lite), $0.050 (grok-imagine-video) ou $0.080 (grok-imagine-video-1.5) - A geração é assíncrona: recebe um
request_idpara sondar posteriormente - Estão disponíveis nove proporções para se adaptar a todos os formatos
- Uma faixa de áudio é gerada por predefinição;
"generate_audio": falseproduz um vídeo silencioso