Resumo
A API de texto para vídeo Grok gera vídeo a partir de um prompt de texto. Você chama `POST /v1/videos/generations`, recebe um `request_id` de volta imediatamente e, em seguida, consulta `GET /v1/videos/{request_id}` até que o status seja `"done"`. O modelo é `grok-imagine-video`, com preços a partir de US$0,05 por segundo em 480p. O SDK Python da xAI lida com a consulta (polling) automaticamente.
Introdução
A xAI gerou 1,2 bilhão de vídeos somente em janeiro de 2026. Esse foi o primeiro mês após o lançamento da API de texto para vídeo Grok em 28 de janeiro de 2026. O modelo também ficou em primeiro lugar na classificação de texto para vídeo da Artificial Analysis no mesmo mês. Esses números importam porque mostram que a infraestrutura é comprovada em escala.
Este guia o conduzirá por cada etapa: fazendo sua primeira requisição, consultando o resultado, ajustando parâmetros e escrevendo prompts melhores. Você também aprenderá a usar imagens de referência, estender ou editar vídeos existentes e entender quando o texto para vídeo é a escolha certa.
O que é a API de texto para vídeo Grok?
A API de texto para vídeo Grok faz parte do conjunto de geração de mídia da xAI em `https://api.x.ai`. Você envia um prompt de texto e o modelo `grok-imagine-video` gera um pequeno clipe de vídeo do zero. Nenhuma imagem de origem é necessária.
A API está ao lado de um endpoint síncrono de geração de imagens (`POST /v1/images/generations`, modelo `grok-imagine-image`, US$0,02 por imagem). Ela também inclui endpoints para estender ou editar vídeos.
O endpoint de texto para vídeo difere do endpoint de imagem para vídeo de uma forma fundamental: você fornece apenas palavras. O modelo cria a cena, o movimento e o estilo visual inteiramente a partir da sua descrição. Consulte o guia da API de imagem para vídeo Grok se você tiver uma imagem de origem e quiser que o modelo a anime em vez disso.
Como funciona a geração de texto para vídeo (o padrão assíncrono explicado de forma simples)
A maioria das chamadas de API são síncronas. Você envia uma requisição, espera um momento, recebe sua resposta. A geração de vídeo leva de segundos a minutos, então a API usa um padrão assíncrono.
Aqui está o fluxo:
- Você envia uma requisição POST com seu prompt.
- A API retorna um `request_id` imediatamente (em menos de um segundo).
- O vídeo está sendo gerado nos servidores da xAI.
- Você consulta um endpoint GET com esse `request_id` repetidamente.
- Quando o status muda de `"processing"` para `"done"`, a resposta inclui uma URL de vídeo.
Esse padrão é comum em APIs de mídia de IA. Ele mantém suas conexões HTTP curtas e permite que você verifique o progresso no seu próprio ritmo. A parte complicada é que seu frontend precisa lidar com o estado intermediário, mostrando um indicador de carregamento até que a URL do vídeo chegue.
Pré-requisitos
Antes de escrever qualquer código, você precisa de duas coisas:
Uma conta xAI. Crie uma em console.x.ai. Você também adicionará informações de cobrança lá antes que sua chave de API tenha acesso à geração.
Uma chave de API. No console da xAI, navegue até 'API Keys' e crie uma nova chave. Copie-a para um local seguro. Você a passará como um token Bearer em cada cabeçalho de requisição.
Defina-a como uma variável de ambiente para não codificá-la diretamente:
export XAI_API_KEY="your_api_key_here"
Opcionalmente, instale o SDK Python da xAI para a integração mais simples:
pip install xai-sdk
Sua primeira requisição de texto para vídeo
O endpoint é `POST https://api.x.ai/v1/videos/generations`. Os únicos campos obrigatórios são `model` e `prompt`.
Usando curl
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": "Um golden retriever correndo entre folhas de outono em câmera lenta, iluminação cinematográfica"
}'
A resposta retorna imediatamente:
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Esse UUID é seu bilhete para recuperar o vídeo quando estiver pronto.
Usando Python com a biblioteca requests
import requests
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-video",
"prompt": "Um golden retriever correndo entre folhas de outono em câmera lenta, iluminação cinematográfica"
}
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers=headers,
json=payload
)
data = response.json()
request_id = data["request_id"]
print(f"Geração iniciada. ID da Requisição: {request_id}")
Consultando o resultado do vídeo
Assim que tiver um `request_id`, consulte `GET /v1/videos/{request_id}` até que o campo de status seja igual a `"done"`.
O campo de status tem três valores possíveis: - `"processing"`: ainda gerando - `"done"`: completo, URL do vídeo disponível - `"failed"`: algo deu errado
Aqui está um loop de consulta Python completo:
import requests
import time
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
"""Consulta até que a geração do vídeo esteja completa."""
url = f"{BASE_URL}/v1/videos/{request_id}"
for attempt in range(max_attempts):
response = requests.get(url, headers=headers)
data = response.json()
status = data.get("status")
progress = data.get("progress", 0)
print(f"Tentativa {attempt + 1}: status={status}, progresso={progress}%")
if status == "done":
return data
elif status == "failed":
raise RuntimeError(f"Falha na geração do vídeo: {data}")
time.sleep(interval)
raise TimeoutError(f"Vídeo não pronto após {max_attempts} tentativas")
# Fluxo completo: gerar e depois consultar
def generate_video(prompt: str) -> str:
"""Gera um vídeo e retorna sua URL."""
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers={**headers, "Content-Type": "application/json"},
json={"model": "grok-imagine-video", "prompt": prompt}
)
request_id = response.json()["request_id"]
print(f"ID da Requisição: {request_id}")
result = poll_video(request_id)
video_url = result["video"]["url"]
print(f"Vídeo pronto: {video_url}")
return video_url
video_url = generate_video(
"Um timelapse de um horizonte urbano ao pôr do sol fazendo a transição para a noite, vista aérea"
)
Quando concluído, a resposta completa da consulta se parece com isto:
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/....mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 500000000
}
}
Usando o SDK Python da xAI
Se você prefere pular a consulta manual, o SDK da xAI cuida disso para você. O método `client.video.generate()` bloqueia até que o vídeo esteja pronto.
from xai_sdk import Client
import os
client = Client(api_key=os.environ["XAI_API_KEY"])
result = client.video.generate(
model="grok-imagine-video",
prompt="Um golden retriever correndo entre folhas de outono em câmera lenta",
duration=8,
resolution="720p",
aspect_ratio="16:9"
)
print(f"URL do Vídeo: {result.video.url}")
print(f"Duração: {result.video.duration}s")
O SDK é o caminho mais rápido para um código funcional. Use a abordagem de requisições diretas quando precisar de mais controle sobre a lógica de retentativa, atualizações de progresso ou intervalos de consulta personalizados.
Escrevendo prompts eficazes para geração de vídeo
Seu prompt é a entrada mais importante. Um prompt detalhado e estruturado produz resultados muito melhores do que um vago.
Descrição da cena
Descreva o assunto e o cenário juntos. Seja específico sobre o que é visível. "Uma caneca de café de cerâmica branca em uma mesa de madeira ao lado de uma janela molhada pela chuva" gera uma cena mais realista do que "uma caneca de café."
Movimento
Diga ao modelo o que se move e como. "A câmera orbita lentamente a caneca enquanto o vapor sobe em espiral" adiciona movimento com direção clara. Sem dicas explícitas de movimento, o modelo pode gerar um movimento mínimo ou abrupto.
Estilo de câmera
Use terminologia de câmera que você daria a um cinegrafista: "close-up", "plano de acompanhamento", "vista aérea de drone", "câmera na mão", "dolly zoom". Essas dicas se traduzem de forma confiável para a filmagem gerada.
Iluminação e humor
"Golden hour" (hora dourada), "overcast" (nublado), "neon-lit" (iluminado por néon) e "studio three-point lighting" (iluminação de três pontos de estúdio) produzem diferentes aparências. Combine iluminação com humor: "manhã enevoada, atmosfera melancólica" dá ao modelo uma orientação tonal além da temperatura da cor.
Referências de estilo
Nomeie um estilo visual se tiver um em mente: "cinemático", "documentário", "anime", "stop-motion", "hyperlapse". Combinar dois estilos frequentemente produz resultados interessantes.
Estrutura de prompt que funciona
Comece com o assunto, adicione movimento, descreva a câmera, finalize com estilo e humor. Assim:
Um astronauta solitário flutua pela Estação Espacial Internacional,
com o cabo flutuando atrás dele. A câmera acompanha lentamente
ao lado, mostrando a Terra abaixo. Cinemático, qualidade IMAX,
luz quente do nascer do sol refletindo no visor.
Controlando resolução, duração e proporção de tela
O endpoint de geração aceita vários parâmetros opcionais que permitem controlar as dimensões de saída, o comprimento e a qualidade.
Duração
"duration": 10
Intervalo: 1 a 15 segundos. O padrão é 6 segundos. Vídeos mais longos custam mais. Um clipe de 10 segundos em 480p custa US$0,50.
Resolução
"resolution": "720p"
Duas opções: `"480p"` (padrão) e `"720p"`. Use 480p para prototipagem e testes. Use 720p para produção onde a qualidade é importante.
Proporção de tela
"aspect_ratio": "9:16"
Proporções disponíveis:
| Proporção | Melhor para |
|---|---|
16:9 |
Desktop, YouTube, apresentações (padrão) |
9:16 |
TikTok, Instagram Reels, mobile |
1:1 |
Feed do Instagram, cartões sociais |
4:3 |
Vídeo clássico, apresentações |
3:4 |
Conteúdo móvel em retrato |
3:2 |
Proporção de foto padrão |
2:3 |
Fotografia em retrato |
Exemplo completo com todos os parâmetros
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": "Uma cidade costeira ao amanhecer, ondas quebrando suavemente em uma costa rochosa",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Usando imagens de referência para guiar o estilo do vídeo
O parâmetro `reference_images` aceita um array de até 7 URLs de imagem. Essas imagens guiam o estilo visual e o conteúdo do vídeo gerado sem se tornarem o assunto dele.
{
"model": "grok-imagine-video",
"prompt": "Uma cidade costeira ao amanhecer, ondas quebrando suavemente em uma costa rochosa",
"reference_images": [
{"url": "https://example.com/my-style-reference.jpg"},
{"url": "https://example.com/color-palette-reference.jpg"}
]
}
Imagens de referência funcionam melhor quando compartilham uma estética consistente. Se você fornecer três imagens de diferentes estilos visuais, o modelo tenta conciliá-los e o resultado pode parecer inconsistente. Use um conjunto coeso de imagens com um visual unificado para a orientação mais forte.
Imagens de referência são diferentes do endpoint de imagem para vídeo. Com imagens de referência, seu prompt ainda impulsiona a cena. As imagens influenciam a gradação de cores, o estilo de composição e a textura visual. Com imagem para vídeo, a imagem de origem se torna o primeiro quadro.
Estendendo e editando vídeos gerados
A xAI oferece dois endpoints adicionais para trabalhar com vídeos que você já gerou.
Estender um vídeo
`POST /v1/videos/extensions` adiciona mais filmagem a um vídeo gerado existente. Você passa o `request_id` do vídeo original e um novo prompt para a extensão. Isso é útil para criar sequências mais longas sem atingir o limite de 15 segundos em uma única chamada.
Editar um vídeo
`POST /v1/videos/edits` modifica um vídeo existente com base em uma instrução de texto. Você pode mudar o estilo, alterar a cena ou aplicar efeitos a um clipe que você já gerou.
Ambos os endpoints seguem o mesmo padrão assíncrono que o endpoint de geração principal. Eles retornam um `request_id` e você consulta `GET /v1/videos/{request_id}` para obter o resultado.
Lendo o custo da resposta da API
A resposta da consulta concluída inclui um objeto `usage`:
"usage": {
"cost_in_usd_ticks": 500000000
}
A unidade é USD ticks. Divida por 10.000.000 para converter para dólares.
cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Custo: ${cost_in_usd:.4f}")
# Saída: Custo: $0.0500
Referência de Preços
| Resolução | Preço por segundo | Clipe de 10 segundos |
|---|---|---|
| 480p | $0.05 | $0.50 |
| 720p | $0.07 | $0.70 |
Um valor de `500000000` ticks equivale a US$0,50. Isso é um clipe de 10 segundos em 480p.
Acompanhe seus custos registrando `cost_in_usd_ticks` de cada resposta concluída. Isso permite que você construa painéis de uso sem chamar a API de faturamento da xAI separadamente.
Como testar sua API de vídeo Grok com Apidog
O padrão de consulta assíncrona cria um desafio de teste específico. Seu código frontend precisa lidar com três estados: carregamento (durante a consulta), sucesso (URL do vídeo recebida) e erro. Você não pode testar todos os três estados fazendo chamadas reais de API, porque cada chamada leva tempo e custa dinheiro. É aqui que o recurso Smart Mock da Apidog resolve o problema diretamente.
Caso de uso 1: Smart Mock para desenvolvimento frontend
Com o Smart Mock da Apidog, você define o esquema para ambos os endpoints e o Apidog retorna respostas falsas realistas instantaneamente.
Simule o endpoint de geração:
No Apidog, crie o endpoint `POST /v1/videos/generations` em seu projeto. Defina o esquema de resposta com um único campo de string `request_id`. O Smart Mock retornará um UUID falso automaticamente com base no padrão do nome do campo.
Sua resposta simulada:
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Simule o endpoint de consulta:
Crie `GET /v1/videos/{request_id}` no Apidog. Defina o esquema de resposta completo, incluindo `status`, `video.url`, `video.duration`, `progress` e `usage.cost_in_usd_ticks`. Defina uma resposta Custom Mock que retorne `"status": "done"` com uma URL MP4 de placeholder.
Sua resposta de consulta simulada:
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/mock-video-12345.mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 400000000
}
}
Os desenvolvedores frontend agora podem construir e testar toda a interface do reprodutor de vídeo contra este servidor de mock. Eles veem o estado de carregamento, o estado de concluído e podem acionar o estado de erro modificando o mock para retornar `"status": "failed"`. Nenhum crédito real da API é gasto durante o desenvolvimento.
Caso de uso 2: Cenários de Teste para o loop de consulta
Uma vez que sua integração esteja construída, use os Cenários de Teste da Apidog para validar o fluxo completo de geração e consulta automaticamente.
Passo 1: Adicione a requisição de geração. Adicione `POST /v1/videos/generations` como o primeiro passo em seu cenário de teste. No pós-processador, adicione uma Extração de Variável para capturar o `request_id` do corpo da resposta usando a expressão JSONPath `$.request_id`. Armazene-o em uma variável chamada `videoRequestId`.
Passo 2: Adicione um loop de consulta. Adicione `GET /v1/videos/{{videoRequestId}}` como o segundo passo. Envolva-o em um loop For com uma condição de interrupção: `response.body.status == "done"`. Adicione um processador de Espera de 5 segundos entre as iterações para evitar exceder o limite de taxa.
Passo 3: Afirme o resultado. Após a saída do loop, adicione um processador de Assertiva à requisição GET final. Afirme que `$.video.url` não está vazio. Isso confirma que o ciclo completo foi concluído com sucesso.
Este cenário de teste oferece cobertura repetível e automatizada do fluxo assíncrono. Execute-o na CI para detectar quaisquer regressões quando sua lógica de consulta mudar.
Texto para vídeo vs imagem para vídeo: quando usar cada um
Ambos os modos usam o mesmo modelo `grok-imagine-video`, mas servem a propósitos diferentes.
Escolha texto para vídeo quando:- Você estiver gerando conteúdo original a partir de um conceito ou roteiro - Você quiser que o modelo tenha controle criativo total sobre a composição - Você estiver construindo uma ferramenta de geração de conteúdo onde os usuários digitam prompts - Você não tiver uma imagem de origem para começar
Escolha imagem para vídeo quando:- Você tiver uma foto de produto, ilustração ou ativo de marca para animar - Você precisar manter detalhes visuais específicos de uma imagem existente - Você estiver criando animações consistentes a partir de uma série de imagens relacionadas - Você quiser animar sua própria arte ou fotografia
A distinção principal: texto para vídeo cria uma cena do zero. Imagem para vídeo faz uma imagem existente se mover. Para uma visão completa da abordagem de imagem para vídeo, consulte o guia da API de imagem para vídeo Grok.
Para equipes que constroem produtos que oferecem ambos os modos, você pode detectar o tipo de entrada em tempo de execução. Se o usuário fizer upload de uma imagem, direcione para `POST /v1/images/generations` (imagem para vídeo). Se eles digitarem apenas um prompt, direcione para `POST /v1/videos/generations`.
Erros comuns e como corrigi-los
401 Não AutorizadoSua chave de API está faltando, expirada ou formatada incorretamente. Verifique se o cabeçalho Authorization é exatamente `Bearer YOUR_XAI_API_KEY` sem espaços extras. Confirme se a chave está ativa no console da xAI.
429 Muitas RequisiçõesVocê atingiu um limite de taxa. A API permite 60 requisições por minuto e 1 requisição por segundo. Adicione um atraso entre as requisições. Se você estiver consultando, espace suas chamadas em pelo menos 5 segundos.
status: "failed" na resposta da consultaA geração falhou. Isso geralmente significa que o prompt foi rejeitado pela moderação de conteúdo. O campo `respect_moderation` na resposta será `true` se a moderação foi aplicada. Revise seu prompt para ser menos ambíguo ou remova linguagem potencialmente sensível.
URL do vídeo retorna 404URLs de vídeo geradas expiram após um período de tempo. Baixe o vídeo para seu próprio armazenamento imediatamente após recuperar a URL. Não armazene a URL e espere que ela esteja disponível dias depois.
Vídeo vazio ou congeladoPrompts vagos ou prompts sem dicas de movimento às vezes produzem vídeos com movimento mínimo. Adicione linguagem de movimento explícita ao seu prompt: descreva o que se move, em que direção e em que velocidade.
Tempos de consulta lentosVídeos em 720p levam mais tempo para serem gerados do que em 480p. Durações mais longas também levam mais tempo. Para desenvolvimento e prototipagem, use `"resolution": "480p"` e durações curtas para acelerar o ciclo de iteração.
Conclusão
A API de texto para vídeo Grok oferece um caminho direto do texto para o vídeo. Você envia um prompt, obtém um `request_id`, consulta até que esteja pronto e recupera seu MP4. O padrão assíncrono é o conceito chave a ser compreendido. Uma vez que o loop de consulta esteja funcionando, o restante dos parâmetros (duração, resolução, proporção de tela, imagens de referência) são simples de ajustar.
Para compilações de produção, adicione o rastreamento de custos lendo `cost_in_usd_ticks` de cada resposta concluída. Simule ambos os endpoints no Apidog durante o desenvolvimento para que sua equipe de frontend não seja bloqueada esperando por gerações reais. Use Cenários de Teste para manter sua lógica de consulta confiável à medida que sua integração evolui.
Baixe o Apidog gratuitamente para configurar seu servidor de mock e cenários de teste para a API de vídeo Grok.
FAQ
Qual nome de modelo devo usar para a geração de texto para vídeo?Use `grok-imagine-video`. Este é o campo `model` obrigatório em sua requisição POST para `/v1/videos/generations`.
Quanto tempo leva a geração de vídeo?Varia de acordo com a duração e a resolução. Clipes curtos em 480p podem ser concluídos em menos de 30 segundos. Clipes mais longos em 720p podem levar alguns minutos. Consulte a cada 5-10 segundos, em vez de bombardear o endpoint continuamente.
Posso gerar um vídeo com mais de 15 segundos?Não em uma única requisição. A `duration` máxima é de 15 segundos. Para criar vídeos mais longos, gere um clipe e use `POST /v1/videos/extensions` para anexar mais filmagens.
Como faço para baixar o vídeo gerado?Use a URL de `result.video.url` na resposta da consulta concluída. Baixe o MP4 para seu armazenamento imediatamente. A URL é temporária e irá expirar.
O que acontece se meu prompt violar a moderação de conteúdo?A tarefa será concluída, mas o `status` será `"failed"`. O campo `respect_moderation` na resposta da consulta indica que a moderação foi aplicada. Revise seu prompt e tente novamente.
Existe um nível gratuito para a API de vídeo?A xAI cobra por segundo de saída gerada. Não há um nível gratuito específico para a geração de vídeo. Verifique console.x.ai para ofertas de crédito atuais para novas contas.
Como `reference_images` diferem de começar com uma imagem de origem?Imagens de referência guiam o estilo visual de uma geração de texto para vídeo. Elas influenciam a aparência sem se tornarem o assunto. Uma imagem de origem para imagem para vídeo se torna o primeiro quadro real do vídeo.
Qual é a melhor forma de testar o loop de consulta sem gastar créditos?Use o Smart Mock da Apidog para simular tanto os endpoints de geração quanto os de consulta. Defina os esquemas, configure respostas de mock para os estados `"processing"` e `"done"`, e seu código de consulta funcionará sem tocar na API real.