Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Endpoint /v1/videos/generations: O Seu Primeiro Vídeo

Aula 1 de 12 Atualizada a 3 de novembro de 2026 Intermediario
Nesta página
  1. Gerar um Vídeo a Partir de Texto
  2. Estrutura do Pedido
  3. Uma Primeira Chamada de Ponta a Ponta
  4. Áudio, por Predefinição
  5. Pontos-chave

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 -lite e grok-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âmetro size apresentado 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.

1-15s
Duração por Vídeo
1080p
Resolução Máxima
desde $0.02
Por Segundo Gerado
9
Proporções Disponíveis

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ómica grok-imagine-video-1.5-lite, recomendada pela xAI para vídeos simples, ou grok-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), 720p ou 1080p — esta última renderizada nativamente pelo grok-imagine-video-1.5 em texto-para-vídeo e imagem-para-vídeo, obtida por amostragem ascendente (upsampling) de 720p na versão -lite e ausente no grok-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, com grok-imagine-video-1.5, a sua versão -lite ou grok-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_id para 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": false produz um vídeo silencioso