API Grok Imagine Video: texto para vídeo com Python

A API do Grok Imagine Video é assíncrona: você envia um prompt para criar uma tarefa, consulta o ID da tarefa até ela terminar e baixa o MP4. O modelo atual é grok-imagine-video-1.5. Em 24 de outubro de 2026, nosso clipe de 6 segundos em 720p ficou pronto 46 segundos depois do envio, e veio com faixa de áudio.

Abaixo estão o script que roda como está, os parâmetros que decidem o resultado, o custo e o tempo de um clipe e os erros com que você vai esbarrar.

Resposta curta

• Modelo: grok-imagine-video-1.5. A xAI diz que o 1.5 saiu da prévia e entrou em disponibilidade geral em 16 de junho de 2026 (xAI).
• Ajustes: duration de 4 a 15 segundos, resolution "720p" e um ratio como "16:9".
• Custo: US$ 0,14 por segundo em 720p na tabela da xAI, ou seja, US$ 0,84 por um clipe de 6 segundos (página de modelos da xAI, consultada em 24 de outubro de 2026).
• Tempo: nossa tarefa de 6 segundos em 720p levou 46 segundos. Consulte o mesmo ID de tarefa e baixe o arquivo dentro de uma hora.

Como a API do Grok Imagine Video funciona?

São três etapas: criar, consultar e baixar (guia de geração de vídeo da xAI, consultado em 24 de outubro de 2026).

Na API própria da xAI, você envia um POST para https://api.x.ai/v1/videos/generations com o ID do modelo e o prompt e recebe um request_id. Depois consulta https://api.x.ai/v1/videos/{request_id} com GET até a tarefa ficar done e lê video.url (o mesmo guia).

A xAI recomenda o grok-imagine-video-1.5-lite para vídeos simples e o grok-imagine-video-1.5 quando você precisa de referências, vozes, quadros fixos ou 1080p nativo (visão geral de vídeo, consultada em 24 de outubro de 2026). Para imagens paradas, o guia da API de imagens do Grok Imagine cobre os três modelos de imagem da xAI; para comparar o Grok com outras APIs de vídeo, leia nossa comparação de modelos de vídeo.

A OmniaKey vende acesso de API ao Grok Imagine Video 1.5, então rodamos o exemplo por ela. As chamadas são POST https://api.omniakey.com/v1/media/tasks com um cabeçalho Idempotency-Key, que responde 202 com um id, e GET /v1/media/tasks/{id} para o status (visão geral de mídia da OmniaKey, consultada em 24 de outubro de 2026). A mesma sequência de criar, consultar e baixar vale para os outros modelos de vídeo da documentação da API de vídeo: Kling 3.0, Seedance, Wan 3.0, MiniMax H3 e HappyHorse. Todos os preços abaixo são os da própria xAI.

Os nomes de campo da xAI vêm da referência da API de vídeos e os da OmniaKey da documentação da API de vídeo, ambos consultados em 24 de outubro de 2026.

Quais parâmetros você pode definir?

O prompt e três ajustes decidem o que você recebe.

• duration é obrigatório na OmniaKey e define o preço (documentação de vídeo da OmniaKey). O mínimo da OmniaKey para este modelo é 4 segundos e o máximo da xAI é 15 (guia de geração de vídeo), então fique entre 4 e 15.
• resolution: envie "720p" em minúsculas. A OmniaKey entrega o vídeo do Grok até 720p (visão geral de mídia da OmniaKey). A API própria da xAI inclui 480p, o padrão dela, e 1080p nativo (guia de geração).
• ratio aceita nove valores: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 e 5:2, com 16:9 como padrão (guia de geração de vídeo). Usamos 16:9.
• n precisa ser 1 (documentação de vídeo da OmniaKey).
• O prompt: descreva o plano, a luz e o movimento de câmera e acrescente uma linha Sound:. Tudo que você citar ali pode aparecer na imagem: nossa linha de som falava de uma colher, e uma colher e uma mão apareceram no quadro.

Como transformar um prompt de texto em vídeo com Python?

Instale o requests, coloque a chave em OMNIAKEY_API_KEY e rode o script.

pip install requests
export OMNIAKEY_API_KEY="your-key"

Este é o script que rodamos, sem alterações:

import os
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

PROMPT = (
    "Close-up of a white ceramic coffee cup on a wooden café table by a window, "
    "morning sunlight, steam curling up from the coffee, the camera slowly pushes in, "
    "shallow depth of field. Sound: quiet café chatter and a spoon clinking on a saucer."
)

# 1. Crie a tarefa. Reuse a mesma Idempotency-Key só ao repetir esta requisição exata.
job = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "grok-imagine-video-1.5",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": PROMPT},
        "parameters": {"duration": 6, "resolution": "720p", "ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
task = job.json()
print("task:", task["id"], task["status"])

# 2. Consulte a tarefa até ela terminar. Tarefa lenta não falhou: siga perguntando pelo mesmo id.
while True:
    task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] not in ("queued", "processing"):
        break
    time.sleep(5)

if task["status"] != "succeeded":
    raise SystemExit(f"job ended {task['status']}: {task.get('error')}")

# 3. Baixe agora: a URL assinada expira em cerca de uma hora.
asset = task["assets"][0]
with open("coffee.mp4", "wb") as f:
    f.write(requests.get(asset["url"], timeout=120).content)
print("saved coffee.mp4", asset["mime_type"], asset["byte_size"], "bytes")

A última linha que ele imprimiu em 24 de outubro de 2026:

saved coffee.mp4 video/mp4 2659230 bytes

A primeira linha do script mostra o ID da tarefa e o status. Guarde esse ID: é por ele que você reencontra a tarefa se o script parar.

Uma tarefa de 6 segundos em 720p voltou assim:

O clipe segue o prompt: xícara de cerâmica branca com café preto sobre um pires branco, numa mesa de madeira perto da janela, com vapor subindo e o café desfocado ao fundo. A câmera avança em ritmo constante e a xícara passa de cerca de um terço da largura do quadro para cerca de metade. Aos 4,5 segundos uma colher entra pela direita. O áudio é uma faixa calma, com um pico nítido aos 4,8 segundos, exatamente quando a colher toca o pires.

Quanto custa um clipe e quanto tempo ele leva?

A xAI cobra o vídeo por segundo, e a tarifa depende do modelo e da resolução. A página de modelos (consultada em 24 de outubro de 2026) detalha o preço por resolução, e os US$ 0,080 por segundo fixos da página de preços são a tarifa de 480p.

Nesses preços de tabela:

• 6 segundos no 1.5 em 720p: 6 × 0,14 = US$ 0,84.
• 8 segundos, a duração padrão, no 1.5 em 480p: 8 × 0,08 = US$ 0,64.
• 15 segundos no 1.5 em 1080p: 15 × 0,25 = US$ 3,75.
• 6 segundos no 1.5 Lite em 720p: 6 × 0,03 = US$ 0,18.

A xAI publica só tarifas de vídeo por segundo (página de preços, consultada em 24 de outubro de 2026).

Na OmniaKey, a cobrança é a duração pedida vezes a tarifa por segundo, debitada do saldo na criação da tarefa e devolvida automaticamente se a tarefa falhar (documentação de vídeo da OmniaKey, consultada em 24 de outubro de 2026). Pedimos 6 segundos, recebemos um arquivo de 6,04 segundos e a cobrança foi de 6 segundos. As tarifas atuais estão na página do Grok Imagine Video 1.5.

Nossa tarefa levou 46 segundos entre a requisição e o succeeded. A xAI diz que a geração "costuma levar até alguns minutos" e o SDK dela espera até 10 minutos (guia de geração). Consulte a cada poucos segundos. Se você puser um limite de tempo no laço, dê folga, e quando estourar, busque a tarefa de novo pelo ID em vez de mandar outra requisição.

O link assinado dura cerca de uma hora, e o nosso expirou exatamente uma hora depois do fim da tarefa. O registro da tarefa fica guardado por 24 horas, então você pode consultar de novo para obter um link novo (visão geral de mídia da OmniaKey, consultada em 24 de outubro de 2026).

Com quais erros você vai esbarrar?

A maioria dos erros volta na hora, antes de a tarefa existir, então não custa nada. Uma tarefa que falha depois termina como failed e o valor é devolvido. A documentação de mídia da OmniaKey (consultada em 24 de outubro de 2026) lista, entre outros:

Provocamos os dois primeiros de propósito em 24 de outubro de 2026. Sem o cabeçalho, a resposta é HTTP 400:

{"error":{"code":"missing_idempotency_key","message":"Idempotency-Key is required and must be at most 255 characters"}}

Reaproveitando a chave da tarefa com um prompt diferente, a resposta é HTTP 409:

{"error":{"code":"idempotency_key_reused","message":"Idempotency-Key was already used with a different request"}}

• Trate uma tarefa lenta como ainda em andamento. Continue consultando o mesmo ID de tarefa; reenviar a requisição com uma Idempotency-Key nova começa uma segunda tarefa e cobra por ela.
• Uma requisição repetida responde 200 com a tarefa original e sem lista assets, e é por isso que o script busca a tarefa antes de ler assets.

Perguntas frequentes

A API do Grok Imagine Video é gratuita?

Não. A xAI publica só tarifas por segundo, e a mais barata é o 1.5 Lite a US$ 0,02 por segundo em 480p (página de modelos, consultada em 24 de outubro de 2026).

Qual é a duração máxima de um vídeo do Grok Imagine?

De 1 a 15 segundos na API da xAI, com 8 segundos por padrão (guia de geração de vídeo). Pela OmniaKey, use de 4 a 15 segundos: o mínimo da OmniaKey para este modelo é 4 (documentação de vídeo da OmniaKey, consultada em 24 de outubro de 2026) e o máximo da xAI é 15.

O Grok Imagine Video gera som?

Sim, uma faixa de áudio por padrão, com efeitos, ambiente e diálogo gerados junto com a imagem (guia de geração de vídeo; anúncio da xAI). A nossa tinha uma faixa AAC estéreo. A API da xAI aceita generate_audio: false para um clipe sem som; para tirar a faixa de um arquivo baixado, rode:

ffmpeg -i coffee.mp4 -an -c:v copy coffee-silent.mp4

O Grok Imagine transforma imagem em vídeo?

Sim, na API da xAI: passe a imagem como image (uma URL pública, um data URI em base64 ou um file_id da Files API; JPEG, PNG ou WebP), ela vira o primeiro quadro, o prompt é opcional e o clipe mantém a proporção da imagem (guia de imagem para vídeo; referência da API de vídeos). Vamos acrescentar aqui um exemplo de imagem para vídeo pela OmniaKey quando tivermos verificado de ponta a ponta.

Qual é a diferença entre o Grok Imagine Video 1.5 e o 1.5 Lite?

O Lite é o mais barato por segundo, faz texto para vídeo e imagem para vídeo com fala sincronizada com os lábios, chega a 1080p ampliando o 720p e não tem imagens de referência, referências de voz nem quadros-chave (visão geral de vídeo; página do modelo Lite). Os exemplos aqui usam o 1.5, que você chama na OmniaKey como Grok Imagine Video 1.5.

grok-imagine-video-1.5-preview ainda é um ID de modelo válido?

A xAI ainda lista como alias, mas o 1.5 saiu da prévia e entrou em disponibilidade geral em 16 de junho de 2026 (página do modelo; anúncio da xAI). Use grok-imagine-video-1.5.