DEV Community

Cover image for Como Usar a API Grok Text to Video: Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a API Grok Text to Video: Guia Completo

Resumo

A API de texto para vídeo Grok transforma prompts de texto em vídeos. Para utilizá-la, envie uma requisição POST /v1/videos/generations, receba um request_id imediatamente e consulte GET /v1/videos/{request_id} até que o status seja "done". O modelo utilizado é o grok-imagine-video, com preços a partir de US$0,05 por segundo em 480p. O SDK Python da xAI gerencia o polling automaticamente.

Experimente o Apidog hoje mesmo

Introdução

Em janeiro de 2026, a xAI gerou 1,2 bilhão de vídeos apenas no primeiro mês após o lançamento da API de texto para vídeo Grok (28/01/2026). O modelo liderou o ranking da Artificial Analysis nesse período, comprovando sua robustez em escala.

Este guia mostra como fazer sua primeira requisição, consultar o resultado, ajustar parâmetros, criar prompts melhores, usar imagens de referência, estender/editar vídeos e decidir quando usar texto para vídeo.

💡 Dica importante: A API é assíncrona. Seu frontend precisa lidar com polling para saber quando o vídeo está pronto. O Smart Mock da Apidog permite simular os endpoints de geração e consulta, acelerando o desenvolvimento do frontend antes do backend real.

O que é a API de texto para vídeo Grok?

A API de texto para vídeo Grok integra o conjunto de geração de mídia da xAI (https://api.x.ai). Basta enviar um prompt textual para o modelo grok-imagine-video — ele cria um clipe do zero, sem exigir imagem de origem.

Além disso, há um endpoint síncrono para geração de imagens (POST /v1/images/generations, modelo grok-imagine-image, US$0,02 por imagem), além de operações para estender ou editar vídeos.

No endpoint de texto para vídeo, só o texto importa: a cena, o movimento e o visual são definidos pelo prompt. Se você quiser animar uma imagem específica, consulte o guia da API de imagem para vídeo Grok.

Como funciona a geração de texto para vídeo (padrão assíncrono na prática)

A geração de vídeo é assíncrona devido ao tempo de processamento (segundos a minutos). O fluxo padrão:

  1. Envie um POST com seu prompt.
  2. Receba um request_id imediatamente.
  3. A geração ocorre nos servidores da xAI.
  4. Consulte GET /v1/videos/{request_id} periodicamente.
  5. Quando o status for "done", a resposta traz a URL do vídeo.

Seu frontend precisa exibir um estado de carregamento até receber a URL final.

Pré-requisitos

Antes de codificar:

1. Conta na xAI: Cadastre-se em console.x.ai.

2. Chave de API: No console, crie sua chave em "API Keys" e salve-a com segurança. Ela será usada como Bearer Token em todas as requisições.

export XAI_API_KEY="sua_api_key_aqui"
Enter fullscreen mode Exit fullscreen mode

(Opcional) Instale o SDK Python da xAI:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Sua primeira requisição de texto para vídeo

Endpoint: POST https://api.x.ai/v1/videos/generations. Campos obrigatórios: 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Resposta imediata:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

Usando Python (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}")
Enter fullscreen mode Exit fullscreen mode

Consultando o resultado do vídeo

Após obter o request_id, faça polling em GET /v1/videos/{request_id} até status ser "done".

  • "processing": em geração
  • "done": vídeo pronto (URL disponível)
  • "failed": erro na geração

Exemplo de loop de polling em Python:

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:
    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")

def generate_video(prompt: str) -> str:
    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"
)
Enter fullscreen mode Exit fullscreen mode

Exemplo de resposta quando o vídeo está pronto:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}
Enter fullscreen mode Exit fullscreen mode

Usando o SDK Python da xAI

O SDK simplifica o processo — client.video.generate() já faz o polling e bloqueia até a conclusão.

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")
Enter fullscreen mode Exit fullscreen mode

Use o SDK para integração rápida. Para maior controle (intervalo de polling, lógica de retentativa), prefira requests diretas.

Escrevendo prompts eficazes para vídeo

Prompts detalhados geram melhores resultados.

Descrição da cena

Seja específico. Exemplo:

"Uma caneca de café de cerâmica branca em uma mesa de madeira ao lado de uma janela molhada pela chuva"

Movimento

Explique o que se move e como:

"A câmera orbita lentamente a caneca enquanto o vapor sobe em espiral"

Estilo de câmera

Comandos como "close-up", "plano de acompanhamento", "vista aérea de drone", "câmera na mão", "dolly zoom" funcionam bem.

Iluminação e humor

Combine clima e iluminação:

"manhã enevoada, atmosfera melancólica"

Referências de estilo

Cite estilos: "cinemático", "anime", "stop-motion", "documentário", etc.

Estrutura de prompt eficiente

Exemplo completo:

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.
Enter fullscreen mode Exit fullscreen mode

Controlando resolução, duração e proporção

Personalize os parâmetros de saída:

Duração 

"duration": 10
Enter fullscreen mode Exit fullscreen mode

1 a 15 segundos (padrão: 6s). Quanto maior, maior o custo.

Resolução 

"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

Opções: "480p" (padrão) e "720p". Use 480p para testes.

Proporção de tela 

"aspect_ratio": "9:16"
Enter fullscreen mode Exit fullscreen mode
Proporção Melhor uso
16:9 Desktop, YouTube, apresentações
9:16 TikTok, Reels, mobile
1:1 Instagram Feed, cartões sociais
4:3 Vídeo clássico, apresentações
3:4 Conteúdo mobile vertical
3:2 Foto padrão
2:3 Fotografia em retrato

Exemplo completo 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Usando imagens de referência para guiar o estilo

O parâmetro reference_images recebe até 7 URLs de imagem. Elas influenciam a estética do vídeo.

{
  "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"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Para melhores resultados, use imagens com estética visual coesa.

Diferencie:

  • Imagens de referência: influenciam estilo (cor, textura).
  • Imagem para vídeo: anima uma imagem de origem, que vira o primeiro frame.

Estendendo e editando vídeos gerados

Dois endpoints extras:

Estender um vídeo

POST /v1/videos/extensions — passar o request_id do vídeo original + novo prompt para gerar sequência adicional.

Editar um vídeo

POST /v1/videos/edits — modificar um vídeo existente via prompt textual (alterar estilo, efeitos, etc).

Ambos seguem o mesmo padrão assíncrono: retornam request_id e polling para resultado.

Lendo o custo da resposta da API

No resultado da consulta:

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

Converta para dólares dividindo por 10.000.000:

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Custo: ${cost_in_usd:.4f}")
# Saída: Custo: $0.0500
Enter fullscreen mode Exit fullscreen mode

Referência de Preços

Resolução Preço por segundo Clipe de 10s
480p $0.05 $0.50
720p $0.07 $0.70

Monitore cost_in_usd_ticks para construir dashboards de uso sem precisar das APIs de faturamento.

Como testar sua API de vídeo Grok com Apidog

O padrão assíncrono exige que o frontend trate três estados: carregando, sucesso e erro. Testar tudo isso com a API real é demorado e caro. O recurso Smart Mock do Apidog resolve esse problema.

Apidog Mock Example

Caso de uso 1: Smart Mock para frontend

  1. Simule o endpoint de geração: Crie POST /v1/videos/generations e defina o schema na Apidog, com campo request_id. O Smart Mock retorna um UUID fake automaticamente.

Exemplo de resposta:

   {
     "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
   }
Enter fullscreen mode Exit fullscreen mode
  1. Simule o endpoint de consulta: Crie GET /v1/videos/{request_id} com todos os campos (status, video.url, etc). Configure mocks customizados para "status": "done" e uma URL de vídeo fake.

Exemplo de resposta:

   {
     "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
     }
   }
Enter fullscreen mode Exit fullscreen mode

Frontenders podem testar todos os estados sem consumir créditos reais.

Caso de uso 2: Cenários de Teste para o loop de polling

  1. Adicione requisição de geração:

    POST /v1/videos/generations, extraia request_id usando JSONPath.

  2. Adicione loop de consulta:

    GET /v1/videos/{{videoRequestId}} dentro de loop com condição: response.body.status == "done". Adicione espera de 5s entre as requisições.

  3. Afirme o resultado:

    Após o loop, afirme que $.video.url não está vazio.

Automatize esses cenários para garantir confiabilidade contínua na sua integração.

Texto para vídeo vs imagem para vídeo: quando usar cada um

Ambos usam grok-imagine-video, mas para usos distintos.

Use texto para vídeo quando:

  • Precisa de conteúdo 100% original a partir de um conceito/roteiro
  • Quer controle criativo total do modelo
  • Usuários digitarão prompts
  • Não tem imagem de origem

Use imagem para vídeo quando:

  • Quer animar uma foto, ilustração ou arte de marca
  • Precisa manter detalhes visuais exatos
  • Vai animar uma sequência de imagens relacionadas

Texto para vídeo cria do zero; imagem para vídeo parte de uma imagem. Para detalhes, veja o guia da API de imagem para vídeo Grok.

Para apps híbridos: se usuário faz upload de imagem, use POST /v1/images/generations. Se só texto, use POST /v1/videos/generations.

Erros comuns e como corrigir

401 Não Autorizado:

  • Verifique se o header Authorization está correto: Bearer SUA_CHAVE_XAI
  • Confirme se a chave está ativa

429 Muitas Requisições:

  • Respeite o limite: 60 por minuto, 1 por segundo
  • Use delays de 5s no polling

status: "failed":

  • Prompt rejeitado pela moderação. Veja se respect_moderation é true e ajuste o texto.

URL retorna 404:

  • URLs de vídeo expiram. Baixe o arquivo assim que receber a URL.

Vídeo vazio ou travado:

  • Prompts vagos geram vídeos sem movimento. Sempre inclua instruções de movimento.

Polling lento:

  • 720p e durações maiores demoram mais. Para desenvolvimento, use "resolution": "480p" e clipes curtos.

Conclusão

A API de texto para vídeo Grok permite ir do texto ao vídeo de forma simples: envie o prompt, obtenha o request_id, faça polling até concluir e recupere o MP4. O fluxo assíncrono é o ponto central do processo. Uma vez automatizado o polling, ajustar os demais parâmetros é simples.

Para produção, monitore custos via cost_in_usd_ticks em cada resposta. Simule endpoints com Apidog para acelerar o desenvolvimento frontend e use Cenários de Teste para garantir confiabilidade.

Experimente o Apidog hoje mesmo para configurar mocks e cenários de teste para a API de vídeo Grok.

FAQ

Qual nome de modelo devo usar para geração de texto para vídeo?

Use grok-imagine-video no campo model da requisição POST para /v1/videos/generations.

Quanto tempo leva para gerar um vídeo?

Depende da duração e resolução. Em 480p, clipes curtos podem ficar prontos em menos de 30s. Em 720p e clipes longos, pode levar minutos. Faça polling a cada 5-10s.

Posso gerar vídeos com mais de 15 segundos?

Não em uma única requisição (duration máxima: 15s). Para vídeos maiores, gere um clipe e use POST /v1/videos/extensions.

Como baixar o vídeo gerado?

Use a URL retornada em result.video.url e baixe o MP4 imediatamente. A URL é temporária.

O que acontece se meu prompt violar moderação?

O status será "failed". Veja o campo respect_moderation. Ajuste o prompt e tente novamente.

Existe nível gratuito?

A xAI cobra por segundo gerado. Não há nível gratuito específico para vídeo, mas consulte console.x.ai para ofertas de crédito para novas contas.

Como reference_images diferem de imagem de origem?

reference_images apenas orientam o estilo; imagem de origem é o primeiro frame do vídeo.

Como testar o loop de polling sem gastar créditos?

Use o Smart Mock da Apidog para simular endpoints de geração e consulta, com respostas para "processing" e "done". Assim, o frontend funciona sem consumir a API real.

Top comments (0)