DEV Community

Cover image for Como Usar a API de Imagem para Vídeo da Grok: Guia Passo a Passo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a API de Imagem para Vídeo da Grok: Guia Passo a Passo

Em Resumo

A API Grok de imagem para vídeo utiliza o modelo grok-imagine-video para animar uma imagem estática em um clipe de vídeo. Basta enviar um POST com a URL da sua imagem, um prompt e configurações para https://api.x.ai/v1/videos/generations. O retorno inclui um request_id para você consultar (polling) via GET /v1/videos/{request_id} até que o status seja "done". A geração leva de 1 a 15 segundos de vídeo, com preço a partir de US$ 0,05/seg para 480p.

Experimente o Apidog hoje

Introdução

Em 28 de janeiro de 2026, a xAI lançou o modelo grok-imagine-video para acesso público via API. No primeiro mês, o modelo gerou 1,2 bilhão de vídeos, liderando o ranking de texto para vídeo da Artificial Analysis. Com a funcionalidade de imagem para vídeo, você envia uma foto e um prompt descritivo via API, e recebe um vídeo animado pronto para download em MP4.

O fluxo assíncrono, onde você envia a tarefa e faz polling até a conclusão, exige testes reais. A integração só está finalizada quando o seu loop de polling trata corretamente os estados "processing", "done" e "failed".

Os Cenários de Teste do Apidog resolvem esse fluxo: encadeie o POST para /v1/videos/generations, extraia o request_id, faça polling até status == "done", e afirme que a URL do vídeo foi retornada. Siga o passo a passo de teste mais abaixo neste guia.

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

A API Grok de imagem para vídeo é parte do produto de geração de vídeo da xAI, operando com o modelo grok-imagine-video. Ela recebe uma imagem que se torna o quadro inicial do vídeo. O modelo analisa a imagem e o prompt de texto, gerando movimento natural na cena.

Endpoint:

POST https://api.x.ai/v1/videos/generations
Enter fullscreen mode Exit fullscreen mode

Autenticação:

Authorization: Bearer SUA_CHAVE_API_XAI
Enter fullscreen mode Exit fullscreen mode

Sua chave está disponível no console da xAI. O mesmo endpoint suporta texto para vídeo (sem o parâmetro image), extensão e edição de vídeo.

Como funciona o processo de imagem para vídeo

O parâmetro image define o primeiro quadro do vídeo. O modelo parte dessa imagem (não a substitui) e prevê como ela se moveria conforme o prompt.

Exemplo:

Imagem: lago ao nascer do sol

Prompt: "ondulações suaves se espalham pela água enquanto a névoa matinal se move"

O primeiro quadro será a foto enviada; os quadros seguintes trazem a animação conforme o prompt.

Use imagem para vídeo quando:

  • Precisa animar fotos reais de produtos, paisagens ou retratos.
  • Quer manter identidade visual no quadro inicial.
  • Deseja movimento realista a partir de uma cena específica.

Prefira texto para vídeo quando:

  • Não tem imagem de referência.
  • Quer liberdade total na composição.
  • Precisa de iteração rápida.

Pré-requisitos

Antes de começar:

  1. Conta xAI no console.x.ai
  2. Chave de API do console xAI (mantenha em variável de ambiente)
  3. Python 3.8+ ou Node.js 18+ (exemplos para ambos)
  4. Imagem publicamente acessível (URL) ou codificada em base64 (data URI)

Pré-requisitos

Defina a variável de ambiente:

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

Instale o SDK Python:

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Para HTTP direto, use apenas requests (Python) ou fetch (Node.js).

Fazendo a primeira requisição de imagem para vídeo

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": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
Enter fullscreen mode Exit fullscreen mode

Resposta esperada:

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

A geração é assíncrona. Use o request_id para polling.

Usando Python (requisições diretas) 

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")
Enter fullscreen mode Exit fullscreen mode

Usando uma imagem base64

Se a imagem não estiver pública:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}
Enter fullscreen mode Exit fullscreen mode

Consultando o resultado (Polling)

A geração é assíncrona. Faça polling do status:

GET https://api.x.ai/v1/videos/{request_id}
Enter fullscreen mode Exit fullscreen mode

Status possíveis:

Status Significado
"processing" Vídeo sendo gerado
"done" Vídeo pronto, URL disponível
"failed" Erro na geração

Exemplo de resposta:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}
Enter fullscreen mode Exit fullscreen mode

Loop de polling em Python 

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# Uso
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")
Enter fullscreen mode Exit fullscreen mode

Dica: Use intervalo de polling ≥5s. A API limita a 60 requisições/minuto.

Usando o SDK Python da xAI

O xai-sdk faz o polling automaticamente:

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")
Enter fullscreen mode Exit fullscreen mode

Prefira SDK para código limpo. Use HTTP direto para controle total de polling.

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

Duração 

"duration": 10
Enter fullscreen mode Exit fullscreen mode

Aceita 1 a 15 segundos. Quanto maior, maior o custo.

Resolução

Valor Descrição
"480p" Padrão. Mais barato, mais rápido
"720p" Alta qualidade. US$ 0,07/seg 
"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

Proporção da tela (aspect_ratio)

Valor Uso
"16:9" Padrão, paisagens
"9:16" Stories, vertical
"1:1" Instagram, miniatura
"4:3" Fotografia, apresentação
"3:4" Retrato
"3:2" Fotografia padrão
"2:3" Retrato alto

Se enviar uma imagem, o padrão é a proporção da imagem. Defina explicitamente para cortar/padronizar.

Usando imagens de referência para estilo

O parâmetro reference_images é um array de até 7 imagens para guiar estilo, conteúdo ou contexto. Não são quadros do vídeo, apenas referência visual.

Exemplo de uso:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}
Enter fullscreen mode Exit fullscreen mode

Você pode omitir image e usar apenas reference_images para guiar um texto para vídeo.

Estendendo e editando vídeos

Estender um vídeo

Use:

POST /v1/videos/extensions
Enter fullscreen mode Exit fullscreen mode

Adicione segundos a um vídeo existente (máx. 15s por chamada):

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "seu_request_id_original",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'
Enter fullscreen mode Exit fullscreen mode

Faça polling do novo request_id normalmente.

Editar um vídeo

Use:

POST /v1/videos/edits
Enter fullscreen mode Exit fullscreen mode

Altere conteúdo ou animação guiado por prompt:

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "seu_request_id_original",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'
Enter fullscreen mode Exit fullscreen mode

Extensões e edições seguem o mesmo padrão assíncrono de polling.

Detalhes de preços: quanto custa um vídeo de 10 segundos

Componente Custo
Imagem de entrada US$ 0,002 por imagem
Saída 480p US$ 0,05/seg
Saída 720p US$ 0,07/seg

Exemplo:

  • 10s em 720p: Imagem = US$ 0,002; Saída = 10×US$ 0,07 = US$ 0,70.

    Total: US$ 0,702

  • 6s em 480p: Imagem = US$ 0,002; Saída = 6×US$ 0,05 = US$ 0,30.

    Total: US$ 0,302

A cobrança da imagem se aplica em toda geração, mesmo para a mesma imagem.

Como testar sua integração com a API Grok usando Apidog

O padrão assíncrono exige testar:

  1. Requisição POST retorna request_id
  2. Polling trata status "processing"
  3. Resposta final tem status == "done" e URL de vídeo válida

Cenários de Teste do Apidog permitem automatizar esse fluxo:

Passo 1: Crie novo cenário de teste

No Apidog, acesse Testes > Novo cenário: "Fluxo assíncrono de imagem para vídeo Grok".

Passo 2: Adicione a requisição de geração

  • URL: https://api.x.ai/v1/videos/generations
  • Método: POST
  • Header: Authorization: Bearer {{xai_api_key}}
  • Corpo: 
  {
    "model": "grok-imagine-video",
    "prompt": "Gentle mist rises from the water as light filters through the trees",
    "image": {
      "url": "https://example.com/your-test-image.jpg"
    },
    "duration": 6,
    "resolution": "480p"
  }
Enter fullscreen mode Exit fullscreen mode

Passo 3: Extraia o request_id

  • Processador: Extrair Variável
  • Nome: video_request_id
  • Origem: Corpo da resposta
  • JSONPath: $.request_id

Passo 4: Loop de polling

  • Processador: Loop For
  • Dentro do loop:
    • GET https://api.x.ai/v1/videos/{{video_request_id}}
    • Extrair variável: video_status ($.status)
    • Esperar: 5000ms
    • Condição de parada: {{video_status}} == "done"

Passo 5: Afirmação da URL

  • GET final
  • Asserção: $.video.url não está vazio

Rodando o cenário

Clique em Executar para rodar o fluxo. O Apidog executa POST, extrai ID, faz polling e verifica a URL do vídeo. O relatório mostra status e tempo de cada etapa.

Integre ao CI/CD:

apidog run --scenario grok-video-async-flow --env production
Enter fullscreen mode Exit fullscreen mode

Erros comuns e soluções

  • 401 Não Autorizado: Cheque o header Authorization e a chave no console xAI.
  • 422 Entidade Não Processável: Verifique se o corpo está correto, prompt não vazio, e imagem acessível.
  • Imagem não acessível: Use uma URL pública ou base64; evite localhost e URLs privadas.
  • Status travado em "processing": Pode levar até alguns minutos. Se passar de 10 minutos, tente novamente.
  • Limite de taxa 429: Respeite 60 req/minuto, 1 req/segundo. Use sleep(1) no polling paralelo.
  • Upload base64 rejeitado: Confirme prefixo do data URI (ex: data:image/jpeg;base64,).
  • Aspect ratio incompatível: Se diferente da imagem, pode haver corte/barras pretas. Ajuste para corresponder.

Conclusão

A API Grok de imagem para vídeo permite transformar fotos em clipes animados via POST + polling, baixando o MP4 ao final. O modelo grok-imagine-video liderou em janeiro de 2026, com mais de 1 bilhão de vídeos gerados. O polling assíncrono é o maior desafio; use Cenários de Teste do Apidog para garantir robustez na integração (extração de variável, loop, asserção de URL).

Comece a construir sua integração com Apidog gratuitamente. Não é necessário cartão de crédito.

FAQ (Perguntas Frequentes)

Qual modelo utilizar?

grok-imagine-video no campo model.

Diferença entre image e reference_images?

image: define o primeiro quadro.

reference_images: guia estilo/tema, não é quadro do vídeo.

Tempo de geração?

6s em 480p: 1~3 min.

15s em 720p: 4~8 min.

Poll a cada 5s.

Posso usar imagem local?

Sim, codifique como base64: data:image/jpeg;base64,{bytes}.

O que acontece sem aspect_ratio?

Com imagem, usa proporção da imagem. Sem imagem, padrão é 16:9.

Preço de 10s em 720p?

Imagem: US$ 0,002; Saída: 10×US$ 0,07 = US$ 0,70.

Total: US$ 0,702.

Limites de taxa?

60 requisições/minuto, 1 por segundo (POST e GET combinados).

Posso estender vídeos além de 15s?

Sim, usando POST /v1/videos/extensions e múltiplas chamadas, sempre via polling.

Links para Apidog mantidos conforme solicitado.

Top comments (0)