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 usa o modelo grok-imagine-video para animar uma imagem estática em um clipe de vídeo. Você faz um POST da sua URL de imagem, um prompt e configurações opcionais para https://api.x.ai/v1/videos/generations. A API retorna um request_id imediatamente. Em seguida, você consulta (polling) GET /v1/videos/{request_id} até que o status se torne "done". A duração varia de 1 a 15 segundos. O preço começa em US$ 0,05 por segundo para saída em 480p.

Introdução

Em 28 de janeiro de 2026, a xAI lançou o modelo grok-imagine-video para acesso público via API. Dentro desse primeiro mês, o modelo gerou 1,2 bilhão de vídeos e ficou em primeiro lugar no ranking de texto para vídeo da Artificial Analysis. A capacidade de imagem para vídeo é uma de suas principais funcionalidades: você entrega à API uma fotografia e um prompt descritivo, e ela anima a fotografia em um clipe de vídeo curto, pronto para download como MP4.

Esse fluxo assíncrono, onde você envia uma tarefa e depois consulta a sua conclusão (polling), introduz um desafio de teste que muitos desenvolvedores ignoram. Sua integração não está finalizada quando o primeiro POST retorna 200. Ela está finalizada quando você confirma que o loop de polling lida com os estados "processing", "done" e "failed" corretamente sob condições reais de rede.

Os Cenários de Teste do Apidog resolvem isso diretamente. Você pode construir uma sequência encadeada: fazer um POST para /v1/videos/generations, extrair o request_id, fazer um loop de consulta (polling) até que status == "done", e então afirmar que a URL do vídeo está presente. Baixe o Apidog gratuitamente para seguir o passo a passo de teste mais adiante neste guia.

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

A API Grok de imagem para vídeo faz parte do produto de geração de vídeo da xAI. Ela opera sob o modelo grok-imagine-video e aceita uma imagem como o quadro inicial do vídeo de saída. O modelo estuda o conteúdo da imagem e o prompt de texto, então gera movimento natural para animar a cena.

O endpoint da API é:

POST https://api.x.ai/v1/videos/generations

A autenticação usa um token Bearer padrão:

Authorization: Bearer YOUR_XAI_API_KEY

Você obtém sua chave no console da xAI. A mesma superfície da API também suporta texto para vídeo (omitindo o parâmetro image), extensões de vídeo e edições de vídeo.

Como funciona o processo de imagem para vídeo

O parâmetro image no corpo da requisição designa o primeiro quadro do vídeo de saída. O modelo não substitui a imagem. Ele parte dela. Cada pixel no primeiro quadro vem da sua imagem original. O modelo então prevê como essa cena se moveria no tempo com base no seu prompt.

Por exemplo: você fornece uma fotografia de um lago de montanha ao nascer do sol. Seu prompt diz "ondulações suaves se espalham pela água enquanto a névoa matinal se move". O primeiro quadro do vídeo de saída é sua fotografia. Os quadros subsequentes mostram a água e a névoa animando de acordo com o prompt.

Isso é diferente do texto para vídeo, onde o modelo gera o próprio primeiro quadro. A imagem para vídeo oferece controle exato sobre a cena inicial.

Você deve escolher imagem para vídeo quando: - Tiver fotos de produtos, paisagens ou retratos existentes que deseja animar. - Seus ativos de marca precisarem de uma identidade visual consistente no primeiro quadro. - Desejar que o movimento se sinta enraizado em uma cena real ou específica.

Você deve escolher texto para vídeo quando: - Estiver explorando ideias visuais sem uma imagem de referência. - Quiser que o modelo decida completamente a composição da cena. - A velocidade de iteração for mais importante do que a precisão do primeiro quadro.

Pré-requisitos

Antes de fazer sua primeira chamada, você precisa:

1. Uma conta xAI em console.x.ai.
2. Uma chave de API do console da xAI. Mantenha-a em uma variável de ambiente, não codificada diretamente.
3. Python 3.8+ ou Node.js 18+ (os exemplos neste guia usam ambos).
4. Uma URL de imagem publicamente acessível, ou uma imagem codificada em base64 como um URI de dados.

Defina sua chave como uma variável de ambiente:

export XAI_API_KEY="your_key_here"

Instale o SDK Python da xAI se desejar o cliente de nível superior:

pip install xai-sdk

Para chamadas HTTP diretas, nenhum pacote adicional é necessário além de requests (Python) ou fetch (Node.js).

Fazendo sua 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"
  }'

A resposta retorna imediatamente com um request_id:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

O vídeo ainda não está pronto. A geração ocorre assincronamente na infraestrutura da xAI. Você precisa consultar o resultado (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}")

Usando uma imagem base64

Se sua imagem for local ou não estiver publicamente acessível, codifique-a como um URI de dados:

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}"
}

Consultando o resultado (Polling)

A geração de vídeo é assíncrona. A API retorna request_id enquanto seu vídeo é renderizado nos servidores da xAI. Você deve consultar o endpoint de status:

GET https://api.x.ai/v1/videos/{request_id}

O campo de status passa pelos seguintes valores:

Uma resposta concluída se parece com isto:

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

Loop completo 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)

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

Mantenha o intervalo de polling em 5 segundos ou mais. A API tem um limite de taxa de 60 requisições por minuto (1 por segundo). O polling intenso em múltiplos trabalhos simultaneamente pode consumir esse orçamento rapidamente.

Usando o SDK Python da xAI

A biblioteca xai-sdk encapsula o padrão assíncrono para você. client.video.generate() envia a tarefa e bloqueia até que o vídeo esteja pronto, gerenciando todo o polling internamente:

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

O SDK lida com o loop de polling, verificações de status e propagação de erros. Use esta abordagem quando desejar um código de aplicação limpo sem gerenciar o polling HTTP por conta própria.

Para controle granular sobre intervalos de polling, estratégias de repetição ou registro (logging), a abordagem de requisições diretas oferece mais flexibilidade.

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

A API de vídeo Grok oferece controle direto sobre o formato de saída.

Duração

O parâmetro duration aceita números inteiros de 1 a 15 segundos. O padrão é 6.

"duration": 10

Vídeos mais longos custam mais. Um clipe de 10 segundos custa aproximadamente 10 vezes um clipe de 1 segundo na mesma resolução.

Resolução

Duas opções estão disponíveis:

"resolution": "720p"

Proporção da tela (Aspect ratio)

O parâmetro aspect_ratio controla as dimensões do quadro de saída:

Quando você fornece uma image, a proporção da tela é padronizada para corresponder às dimensões da imagem de origem. Defina-o explicitamente para substituir ou cortar.

Usando imagens de referência para orientação de estilo

O parâmetro reference_images é distinto do parâmetro image. Entender a diferença é importante.

image: A fotografia de origem que se torna o primeiro quadro do vídeo. O modelo anima a partir deste ponto de partida.

reference_images: Um array de até 7 imagens que guiam o estilo, conteúdo ou contexto visual do vídeo gerado. Estas não são quadros na saída. Elas influenciam como o modelo renderiza o movimento e a aparência.

Use reference_images quando quiser que o vídeo de saída adote características visuais de ativos existentes, mas não como o quadro inicial:

{
  "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"
}

Neste exemplo, product-shot.jpg é o primeiro quadro. As imagens de referência guiam a iluminação e o tratamento estilístico.

Você pode fornecer imagens de referência sem uma imagem de primeiro quadro. Nesse caso, o modelo gera uma saída de texto para vídeo, enquanto extrai orientação de estilo das referências.

Estendendo e editando vídeos

A API suporta duas operações adicionais além da geração inicial.

Estendendo um vídeo

POST /v1/videos/extensions pega um vídeo existente e gera segundos adicionais a partir de onde ele parou. Isso é útil para criar clipes mais longos a partir de múltiplas passagens de geração, mantendo-se dentro do limite de 15 segundos 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": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

A resposta segue o mesmo padrão assíncrono: consulte GET /v1/videos/{request_id} para o clipe estendido.

Editando um vídeo

POST /v1/videos/edits aplica modificações guiadas por prompt a um vídeo existente. Você pode alterar aspectos específicos do conteúdo ou movimento sem regenerar do zero.

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": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

Ambas as extensões e edições são assíncronas e usam o mesmo padrão de polling.

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

A API de vídeo da xAI cobra por dois componentes: o processamento da imagem de entrada e a duração do vídeo de saída.

Exemplo: Vídeo de 10 segundos em 720p

• Imagem de entrada: US$ 0,002
• Saída: 10 segundos × US$ 0,07 = US$ 0,70
• Total: US$ 0,702

Exemplo: Vídeo de 6 segundos em 480p (configurações padrão)

• Imagem de entrada: US$ 0,002
• Saída: 6 segundos × US$ 0,05 = US$ 0,30
• Total: US$ 0,302

A cobrança pela imagem de entrada se aplica toda vez que você envia uma requisição de geração, mesmo que você reutilize a mesma URL de imagem. Planeje suas chamadas de geração de acordo se estiver iterando sobre a mesma imagem base.

Texto para vídeo (sem o parâmetro image) omite a cobrança de US$ 0,002 pela entrada, mas segue o mesmo preço por segundo.

Como testar sua integração com a API de vídeo Grok usando Apidog

O padrão assíncrono cria um desafio de teste que testes simples de requisição única não conseguem cobrir. Você precisa verificar que:

1. A requisição de geração retorna um request_id.
2. A requisição de polling lida corretamente com o status "processing" enquanto espera.
3. A resposta final tem status == "done" e uma URL de vídeo não vazia.

Os Cenários de Teste do Apidog encadeiam essas etapas em um único fluxo automatizado. Veja como construí-lo:

Passo 1: Crie um novo Cenário de Teste

No Apidog, abra o módulo Testes e clique no botão + para criar um novo cenário. Dê a ele o nome "Fluxo assíncrono de imagem para vídeo Grok".

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

Adicione uma etapa de requisição POST personalizada:

• URL: https://api.x.ai/v1/videos/generations
• Método: POST
• Cabeçalho: Authorization: Bearer {{xai_api_key}}
• Corpo (JSON):

{
  "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"
}

Passo 3: Extraia o request_id

Após a etapa POST, adicione um processador Extrair Variável. Configure-o:

• Nome da variável: video_request_id
• Origem: Corpo da resposta
• Método de extração: JSONPath
• Expressão JSONPath: $.request_id

O Apidog armazena o valor extraído em {{video_request_id}} para uso em etapas posteriores.

Passo 4: Construa o loop de polling

Adicione um processador de loop For. Dentro do loop, adicione a requisição de polling:

• URL: https://api.x.ai/v1/videos/{{video_request_id}}
• Método: GET
• Cabeçalho: Authorization: Bearer {{xai_api_key}}

Adicione um processador Extrair Variável dentro do loop para capturar o status atual:

• Nome da variável: video_status
• JSONPath: $.status

Adicione um processador Esperar (5000ms) após a extração do status para evitar atingir o limite de taxa.

Defina a condição Interromper Se do loop: {{video_status}} == "done".

Passo 5: Afirme a URL do vídeo

Após o loop For, adicione uma etapa GET final para o mesmo endpoint de polling. Adicione um processador de Asserção:

• Campo: $.video.url
• Condição: Não está vazio

Esta asserção confirma que a URL do vídeo está presente antes que seu teste seja aprovado.

Para uma análise mais aprofundada sobre como testar APIs assíncronas com Apidog, incluindo padrões de polling mais complexos e integração CI/CD, consulte o guia dedicado.

Executando o cenário

Clique em Executar na visualização do cenário de teste. O Apidog executa o POST, extrai o request_id, faz um loop de polling até que status == "done", e então avalia suas asserções. O relatório de teste mostra o status e o tempo de cada etapa.

Você pode integrar este cenário ao seu pipeline de CI/CD com o Apidog CLI:

apidog run --scenario grok-video-async-flow --env production

Erros comuns e soluções

401 Não Autorizado

Sua chave de API está faltando ou é inválida. Verifique o formato do cabeçalho Authorization: Bearer SUA_CHAVE_API_XAI. Confirme se a chave está ativa no console da xAI.

422 Entidade Não Processável

O corpo da requisição está malformado. Causas comuns: o campo model está ausente, o prompt está vazio ou a image.url não está acessível. Teste a URL da imagem em um navegador antes de usá-la.

URL da imagem não acessível

Os servidores da xAI devem ser capazes de buscar a URL da imagem no momento da geração. URLs privadas, endereços de localhost ou URLs protegidas por autenticação falharão. Use um CDN público ou um URI de dados base64.

Status permanece em "processing" indefinidamente

Uma geração pode levar de 30 segundos a vários minutos, dependendo da resolução e duração. Se o status permanecer em "processing" por mais de 10 minutos, o trabalho pode ter travado. Envie uma nova requisição. A API da xAI atualmente não expõe um sinal de timeout separadamente de "failed".

Erros de limite de taxa (429)

A API permite 60 requisições por minuto e 1 requisição por segundo. Se você estiver consultando (polling) vários trabalhos simultaneamente, escalone suas requisições. Adicione um time.sleep(1) entre as chamadas de polling, no mínimo.

Upload Base64 rejeitado

Certifique-se de que seu URI de dados inclua o prefixo correto do tipo MIME. Use data:image/jpeg;base64, para arquivos JPEG e data:image/png;base64, para arquivos PNG.

Incompatibilidade de proporção da tela

Quando você define um aspect_ratio explícito que difere significativamente das proporções da sua imagem de origem, o modelo pode cortar ou adicionar barras pretas. Corresponda a proporção da tela à sua imagem de origem para obter os melhores resultados.

Conclusão

A API Grok de imagem para vídeo oferece um caminho direto de uma fotografia estática para um clipe animado curto. Você faz um POST da imagem e do prompt, recebe um request_id, consulta (polling) até a conclusão e baixa o MP4. O modelo grok-imagine-video ficou no topo do ranking da Artificial Analysis em janeiro de 2026. Mais de um bilhão de vídeos foram gerados naquele único mês. Essa escala reflete a capacidade do modelo subjacente.

O padrão de polling assíncrono é onde a maioria das integrações falha. Um teste adequado nos Cenários de Teste do Apidog cobre a etapa de Extrair Variável, o loop de polling com condição de interrupção e uma asserção final da URL. Essa combinação detecta problemas antes que cheguem à produção.

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

FAQ (Perguntas Frequentes)

Qual nome de modelo devo usar para a API Grok de imagem para vídeo?

O nome do modelo é grok-imagine-video. Passe-o como o campo model no corpo da sua requisição POST.

Qual a diferença entre os parâmetros image e reference_images?

O parâmetro image define o primeiro quadro do vídeo de saída. O modelo anima a partir dessa imagem inicial. O array reference_images fornece orientação de estilo e conteúdo sem ser usado como quadro. Você pode combinar ambos na mesma requisição.

Quanto tempo leva a geração de vídeo?

O tempo de geração varia conforme a duração e a resolução. Um vídeo de 6 segundos em 480p geralmente leva de 1 a 3 minutos. Um vídeo de 15 segundos em 720p pode levar de 4 a 8 minutos. Faça polling a cada 5 segundos para verificar o status sem esgotar seu limite de taxa.

Posso usar um arquivo local como imagem de origem?

Sim. Codifique seu arquivo local como um URI de dados base64: data:image/jpeg;base64,{encoded_bytes}. Passe essa string como o valor url dentro do objeto image.

O que acontece se eu não especificar o aspect_ratio?

Quando você fornece um parâmetro image, a proporção da tela é padronizada para corresponder às proporções nativas da imagem de origem. Ao gerar texto para vídeo sem uma imagem, o padrão é 16:9.

Quanto custa um vídeo de 10 segundos em 720p?

A imagem de entrada custa US$ 0,002. A saída custa 10 × US$ 0,07 = US$ 0,70. Total: aproximadamente US$ 0,702 por vídeo.

Quais são os limites de taxa?

A API permite 60 requisições por minuto e 1 requisição por segundo. Isso cobre tanto as requisições POST de geração quanto as requisições GET de polling combinadas.

Posso estender um vídeo para além de 15 segundos?

Sim, usando o endpoint POST /v1/videos/extensions. Você gera um clipe inicial de até 15 segundos e depois o estende com passagens de geração adicionais. Cada extensão também segue o padrão de polling assíncrono.