Gerar vídeos curtos a partir de imagens estáticas de produtos: grok-imagine/image-to-video na API hiapi

O conteúdo de vídeo curto para produtos tem um problema de oferta. Um clipe pronto para veicular costumava significar uma produção: tempo de estúdio, design de movimento, editor. Mas se você já opera um catálogo de e-commerce, você tem a matéria-prima pronta — milhares de imagens estáticas de produtos. grok-imagine/image-to-video (o endpoint de imagem para vídeo Grok Imagine da xAI) transforma essas imagens estáticas em clipes cinematográficos de 6 a 30 segundos com uma única chamada assíncrona de API, e seu condicionamento por imagem de referência mantém seu produto com a aparência do seu produto.

Este guia é um fluxo de trabalho de ponta a ponta na API hiapi: animar uma única imagem estática de catálogo, travar a consistência do sujeito com múltiplas imagens de referência, escolher as faixas de duração e resolução para a economia do feed, e processar em lote o catálogo inteiro em uma fila de clipes verticais. Cada clipe incorporado abaixo é uma saída real, sem edição, de primeira geração, vinda da API em produção — gerada para este artigo a partir de imagens estáticas da nossa biblioteca de mídia, com o prompt e as configurações exatos ao lado.

Modelo, limites e preço

grok-imagine/image-to-video roda na interface de tarefas assíncronas da hiapi (POST /v1/tasks). O schema de entrada que verificamos empiricamente para este artigo:

• image_urls (array, obrigatório) — uma ou mais URLs de imagem de referência publicamente acessíveis. URLs privadas ou não capturáveis falham na etapa de normalização, e não com um erro de schema, então hospede as referências em um local público primeiro.
• prompt (string, opcional) — instruções de movimento, câmera e atmosfera. Sem um prompt, o modelo improvisa; para conteúdo de produto você sempre deve fornecer um.
• duration (inteiro, 6–30 segundos)
• resolution (480p ou 720p)
• aspect_ratio (1:1, 2:3, 3:2, 16:9, 9:16)

Não há campos motion_mode, seed ou prompt negativo — campos desconhecidos são rejeitados com 400. Todo o controle de movimento vem da redação do prompt.

Um comportamento que encontramos ao gerar os clipes deste artigo: quando aspect_ratio não corresponde à proporção da própria imagem de referência, a imagem de referência tende a vencer. Nas três execuções abaixo solicitamos 9:16; duas imagens estáticas de origem quadradas retornaram clipes quadrados (960×960 e 544×544), enquanto a execução cuja primeira referência era paisagem entregou um retrato verdadeiro de 720×1280. Se seu feed precisa garantir 9:16, recorte a imagem estática de referência para 9:16 antes de enviar, em vez de confiar no parâmetro.

O preço é cobrado por segundo de saída, conforme a página de preços da hiapi no momento da escrita:

Faixa	Preço por segundo	Clipe de 6 s	Clipe de 15 s	Clipe de 30 s
480p	$0.0114	$0.068	$0.171	$0.342
720p	$0.0214	$0.128	$0.321	$0.642

Esse preço molda todo o fluxo de trabalho: um clipe principal de 6 segundos em 720p custa cerca de 13 centavos, enquanto um rascunho em 480p custa cerca da metade. Você pode se dar ao luxo de iterar.

Enviar → consultar → baixar

O ciclo de vida da tarefa é enviar, consultar, baixar. Envie com curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-video",
    "input": {
      "prompt": "Slow cinematic orbit around the bag, studio lighting glinting off the brass zippers, background stays clean, product unchanged.",
      "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

Você recebe imediatamente um ID de tarefa:

{"code": 200, "data": {"taskId": "tk-hiapi-01KX2H8WMWQG99A2F97BREDPS6"}, "message": "success"}

Depois consulte GET /v1/tasks/{taskId} até que status seja success, e baixe output[0].url. Abaixo está um script auxiliar completo em Python — o padrão exato usado para gerar cada clipe deste artigo:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "grok-imagine/image-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    data = json.loads(out)
    if not (data.get("data") or {}).get("taskId"):
        raise RuntimeError(f"submit failed: {out[:300]}")
    return data["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 1200) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=180)

Dois detalhes operacionais a observar em produção:

1. output[0].url é um link assinado com validade temporária (com tempo de expiração). Baixe os bytes e migre para seu próprio armazenamento assim que a tarefa for concluída — nunca guarde permanentemente a URL bruta da tarefa.
2. A cobrança ocorre quando a tarefa é aceita, então valide antes de enviar em grandes lotes. Um truque útil: envie um valor fora do intervalo, como "duration": 99 — você recebe o erro completo de validação de schema, sem criar uma tarefa cobrável.

Uma imagem estática → um clipe principal

A operação mais comum: pegar uma foto de produto do catálogo e dar a ela um movimento de câmera contínuo. A fotografia de produto é essencialmente estática, então o papel do prompt é adicionar apenas um movimento verossímil e fixar explicitamente todo o resto:

Slow cinematic orbit around the burnt-orange canvas weekender bag, camera
circling smoothly from front to three-quarter view, studio lighting glinting
off the brass zippers, seamless white background stays clean and shadowless,
product perfectly sharp and unchanged, subtle premium e-commerce energy.

Saída real — grok-imagine/image-to-video, 6 s @ 720p, imagem de referência única. Primeira geração, sem edição. Entregue na prática em 960×960: a imagem estática de origem quadrada sobrepôs nossa solicitação 9:16 (veja a nota sobre proporção acima). A imagem estática de origem está abaixo.

Padrões de prompt que mantêm os clipes de produto fiéis:

• Um verbo de câmera (“orbitar”, “aproximar”, “deslocar”). Dois movimentos em um prompt resultam em uma imagem enjoada.
• Diga explicitamente “produto inalterado / perfeitamente nítido”. Modelos de imagem para vídeo derivam; dizer ao modelo que o sujeito é imutável reduz significativamente a deformação de logos, costuras e ferragens.
• Nomeie o momento de material (“brilhando nos zíperes de latão”) — o reflexo de luz deslizando sobre metal e couro é justamente o que faz a imagem estática parecer uma filmagem, e não uma distorção.
• Fixe o fundo (“mantenha limpo e sem sombras”). Caso contrário, o modelo inventará um cenário.

Múltiplas imagens de referência: travar o sujeito

image_urls aceita mais de uma imagem de referência, e é aí que o grok-imagine se distingue dos animadores de quadro único em trabalhos de produto. Dê a ele a imagem de lifestyle que você quer como cena, mais a imagem limpa do produto como seguro de identidade, e o modelo concilia as duas — a cena vem da primeira imagem, os detalhes exatos de acabamento, alças e zíperes do produto são ancorados pela segunda:

The same burnt-orange weekender bag rests on a weathered wooden bench in a
sunlit loft; a gentle push-in as dust motes drift through warm window light,
soft shadows slide slowly across the bench, the bag and its dark leather trim
stay exactly consistent with the reference images, calm lifestyle-catalog mood.

Saída real — grok-imagine/image-to-video, 6 s @ 720p, 9:16, duas imagens de referência (imagem de lifestyle no banco + imagem do produto em fundo branco). Primeira geração, sem edição.

Observe a frase “consistente com as imagens de referência” no prompt — com múltiplas referências, dizê-lo explicitamente ajuda o modelo a tratar as imagens extras como restrições de identidade, e não como uma segunda cena a ser misturada. Esse é o padrão para contas de marca que publicam diariamente: fotografe (ou gere) uma imagem de produto por SKU e depois reutilize-a como âncora de consistência em cada clipe de lifestyle que você animar.

Economia de duração e da faixa de rascunho

A duração vai de 6 a 30 segundos, e a resolução é onde está a alavanca de orçamento: o preço por segundo em 480p é cerca da metade do de 720p. Como os feeds comprimem agressivamente de qualquer forma, o pipeline sensato é rascunhar em 480p e refazer os vencedores em 720p. Durações mais longas também dão ao modelo espaço para uma construção lenta — abaixo está um clipe de 12 segundos na faixa de rascunho em 480p, com um movimento atmosférico contínuo sobre uma imagem estática de uma lata de chá:

Moody slow dolly-in on the matte-black tea tin standing on slate, steam curls
up lazily behind it, a soft beam of morning light sweeps across the embossed
label, tiny tea leaves tumble gently onto the slate in the final seconds, dark
premium atmosphere, label text unchanged and legible.

Saída real — grok-imagine/image-to-video, 12 s @ 480p, imagem de referência única. Primeira geração, sem edição (entregue em formato quadrado, consistente com a imagem estática de origem quadrada). Custo: $0.137.

Renderizar em 480p custa $0.0114/segundo — o clipe inteiro de 12 segundos custou apenas 13,7 centavos. Barato o suficiente para testar três variantes de prompt por produto e pagar a tarifa de 720p apenas pelo que você realmente vai publicar. Observe o “texto do rótulo inalterado e legível” no prompt: o texto de embalagem é a primeira coisa a ficar borrada em imagem para vídeo, e apontá-lo é sua proteção mais barata.

Processar o catálogo em lote

Tudo o que foi dito acima escala linearmente porque as tarefas são assíncronas: envie o lote inteiro primeiro, depois consulte. Um executor de lote mínimo para uma lista de produtos:

products = [
    {"sku": "weekender-orange", "refs": ["https://cdn.example.com/weekender.jpg"],
     "prompt": "Slow cinematic orbit around the bag, studio light on the brass zippers, background clean, product unchanged."},
    {"sku": "tea-tin-black", "refs": ["https://cdn.example.com/tea-tin.jpg"],
     "prompt": "Moody slow dolly-in, steam drifting, light sweeping the embossed label, label text unchanged."},
    # ... restante do catálogo
]

jobs = []
for p in products:
    tid = submit({
        "prompt": p["prompt"],
        "image_urls": p["refs"],
        "duration": 6,
        "resolution": "480p",     # faixa de rascunho
        "aspect_ratio": "9:16",
    })
    jobs.append((p["sku"], tid))

for sku, tid in jobs:
    task = wait(tid)
    url = task["output"][0]["url"]
    subprocess.run(["curl", "-s", "-o", f"{sku}.mp4", url], timeout=180)
    print(f"{sku}: done")

Dicas práticas de lote para rodar esse pipeline:

• Envie primeiro, consulte depois. Cada renderização leva alguns minutos e roda em paralelo no servidor; serializar “enviar-esperar-enviar” desperdiça esse paralelismo.
• Mantenha um modelo de prompt plano por tipo de conteúdo (órbita para imagens de produto, aproximação para imagens de lifestyle), interpolando o substantivo do produto. A consistência de todo o feed importa mais do que a esperteza de cada clipe.
• Verificação de orçamento: um catálogo de 50 SKUs rascunhado em 6 s/480p custa 50 × $0.068 ≈ $3.42. Promover os dez melhores para 720p adiciona dez × $0.128 ≈ $1.28. Um mês inteiro de clipes diários de produto custa menos que uma hora de estúdio.

Notas de publicação para vídeos curtos

• Vertical exige referência vertical. Como observado acima, a proporção da imagem de referência tende a sobrepor aspect_ratio — se o clipe vai para o feed, recorte a imagem estática para 9:16 antes de enviar. Recortar uma renderização quadrada já pronta para vertical descarta a maior parte dos pixels.
• O primeiro segundo é o gancho — prompts que fazem o movimento começar imediatamente (“câmera orbitando”, “aproximação”) superam o fade-in lento em taxa de conclusão.
• Os clipes vêm com uma trilha ambiente gerada pelo modelo. Cada saída que geramos carrega um stream AAC — alguns clipes têm uma atmosfera sutil de estúdio, outros são quase silenciosos. Não há campo de entrada para controlá-la, então planeje substituí-la por sua própria música ou narração na publicação, em vez de tratá-la como trilha finalizada.
• Amigável a loop: órbitas e varreduras de luz loopam muito melhor do que clipes que terminam em uma revelação. Para feeds de reprodução automática (Shorts, Reels), o padrão de órbita acima reinicia sem emendas.

Perguntas frequentes

Quanto tempo leva a renderização? Os clipes de 6 segundos deste artigo renderizaram em alguns minutos cada; o clipe de 12 segundos levou um pouco mais. Trate como uma fila assíncrona, não como uma chamada interativa — envie em lote e consulte.

Posso usar imagens geradas como imagens de referência? Sim. As URLs de referência só precisam ser publicamente acessíveis. As três imagens estáticas de origem deste artigo são elas mesmas imagens de produto geradas pela API (a partir de execuções do seedream-5.0-lite), retiradas da nossa biblioteca de mídia — um pipeline de imagem estática para vídeo totalmente sintético.

E 1080p ou mais de 30 segundos? Este endpoint é limitado a 720p e 30 segundos. Para feeds de vídeo curto, essa é justamente a faixa ideal; se você precisa de resolução maior, faça upscale na pós-produção ou consulte o catálogo de modelos para ver as opções atuais.

Qual é a diferença em relação ao grok-imagine-1.5/image-to-video? O endpoint de preview 1.5 troca alcance por qualidade de movimento: durações de 1–15 segundos, movimento aprimorado, mesmo preço por segundo. Este endpoint 1.0 oferece 6–30 segundos. Cobrimos os fundamentos do 1.5 em outro artigo detalhado.

Existe uma versão de texto para vídeo? Sim — grok-imagine/text-to-video, mesma interface de tarefas, entrada apenas de prompt. Quando a consistência de marca/produto importa, imagem para vídeo é a escolha certa; quando você precisa gerar material do zero, use texto para vídeo.

---

Se você tem imagens estáticas de produtos e uma chave de API, você está a um POST /v1/tasks de distância do seu primeiro clipe para feed: obtenha sua chave no painel, comece pela página do modelo grok-imagine/image-to-video e anime uma imagem de produto com o prompt de órbita acima — a 13 centavos por rascunho, a maneira mais rápida de aprender este modelo é executá-lo.