Ray 3.2 图生视频：converta imagens estáticas em clipes curtos verticais

TL;DR

• O que é: um fluxo de trabalho repetível que usa ray-3.2/image-to-video na API de tarefas assíncronas da hiapi para transformar imagens estáticas que você já tem (por exemplo, fotos de produto ou retratos) em clipes curtos verticais.
• O fato decisivo: ray-3.2 i2v não tem aspect_ratio nem o campo duration. O formato do clipe vem da imagem de entrada, e a duração é sempre de cerca de 5 segundos. Para obter um vertical 9:16, envie uma imagem estática 9:16. Todo o truque está aqui.
• O que mudou em relação ao nosso tutorial anterior: o schema agora aceita o campo opcional end_image_url (último frame). Se você usar a mesma imagem como primeiro e último frame, obtém um clipe que termina onde começou, exatamente o que um loop sem emendas precisa.
• Validação: cada clipe abaixo foi gerado para este artigo em um único lote fan-out. Três clipes em 540p, $0,2145 cada (total de $0,6435), com 41–58 segundos de processamento no servidor cada. Os três retornaram MP4 540×960, 24fps, 5,04s, sem áudio.

A maioria das equipes de vídeo curto não tem falta de ideias. Elas têm um monte de fotos de produto, imagens estáticas de anúncios e retratos de criadores, mas nunca as colocam em movimento. O image-to-video resolve isso: sua imagem permanece como âncora e o modelo adiciona o movimento. Este guia cobre esse trabalho de ponta a ponta com o Ray 3.2: preparar a imagem estática, escrever prompts de movimento, processar em lote, o truque do loop e o que corrigir na edição.

Image-to-video ou text-to-video: qual você precisa?

O Ray 3.2 tem dois endpoints separados na hiapi, adequados a tarefas diferentes de vídeo curto:

• Image-to-video (esta página): você já tem a imagem. O modelo precisa preservar seu produto, seu modelo e sua iluminação, apenas adicionando animação. Serve para vitrines de produto, catálogo para Reels, imagens estáticas de criadores e qualquer clipe em que a fidelidade à marca importe mais que a novidade.
• Text-to-video: você tem a ideia, mas não o material. O modelo compõe o plano inteiro. Se for o seu caso, nosso fluxo de trabalho de vídeo curto com Ray 3.2 text-to-video cobre como gerar conceitos em lote apenas a partir de prompts.

Os dois fluxos são realmente diferentes. No text-to-video, você escolhe o enquadramento vertical passando aspect_ratio: "9:16". No image-to-video, esse campo não existe, então a composição é decidida antes da chamada à API, na preparação da imagem estática.

A requisição: três campos obrigatórios ou usuais e um novo campo opcional

Conferimos o schema campo por campo contra a API em tempo real em 2026-11-01. Ele é fechado, então chaves desconhecidas retornam 400:

Campo	Obrigatório	Valores	Observação
prompt	Sim	Texto	Descreva o movimento, não a cena. A cena já está na sua imagem
image_url	Sim	URL pública	Primeiro frame. Define a proporção da saída
resolution	Não	540p, 720p, 1080p	A única coisa pela qual você paga (veja abaixo)
end_image_url	Não	URL pública	Último frame opcional. Novo desde que nosso guia de uso foi escrito

duration e aspect_ratio continuam sendo rejeitados diretamente (additional properties 'duration' not allowed). Outros nomes de último frame que você possa imaginar, como last_frame_url, tail_image_url ou end_frame_url, também são rejeitados da mesma forma. O campo é end_image_url, e nada mais.

Um único clipe vertical:

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "Slow cinematic push-in toward the serum bottle, a single water droplet slides down the amber glass...",
      "image_url": "https://your-cdn.example.com/serum-9x16.jpg",
      "resolution": "540p"
    }
  }'

Você recebe data.taskId. Faça polling em GET /v1/tasks/{taskId} até que data.status seja success (ou fail), então baixe imediatamente output[0].url, porque é um link temporário com expireAt. O guia de uso tem o script completo de envio/polling/download em Python e os payloads de erro, e o início rápido cobre chaves e fundamentos da API de tarefas.

Preço: a resolução é a única alavanca

Preços em tempo real de ray-3.2/image-to-video (do preço da hiapi no momento da escrita; confira sempre de novo lá):

Resolução	Preço por clipe
540p	$0,2145
720p	$0,429
1080p	$1,7145

A duração do clipe é fixa e a proporção vem da sua imagem, então você nunca paga a mais pelo vertical, e não há opção de “clipe mais longo” para você se auto-promover. Um clipe em 1080p custa o mesmo que oito clipes em 540p. Por isso o padrão para vídeo curto é o mesmo de qualquer modelo de vídeo cobrado por clipe: teste o movimento em 540p e depois re-renderize em 720p ou 1080p apenas os prompts + imagens estáticas vencedores, para a versão que você vai publicar. Para o panorama completo de custos do Ray 3.2 nos dois endpoints, veja detalhamento de preços da API Ray 3.2.

Etapa 1: prepare uma imagem estática 9:16 (é daqui que vem o vertical)

O modelo não consegue reenquadrar seu plano, então a imagem estática precisa estar correta antes do envio:

• Faça em 9:16. Usamos imagens estáticas de 720×1280. Em 540p elas retornaram como 540×960, vertical nativo, sem necessidade de corte depois. Uma foto de produto horizontal gera um clipe horizontal, então corte ou expanda para 9:16 antes.
• Deixe margem para o movimento. O movimento de câmera avança no quadro. Nossa imagem estática do sérum tinha bastante fundo vazio acima do frasco, e o push-in usou esse espaço sem cortar a tampa.
• Coloque o gancho na própria imagem. O primeiro frame do clipe é a sua imagem, então qualquer coisa que impeça o usuário de deslizar (produto, rosto, luz) precisa já estar na estática.

As duas imagens estáticas deste artigo foram geradas com gpt-image-2 como imagens nativas 9:16. No uso real, você colocaria suas próprias fotos de produto ou retratos:

Etapa 2: descreva o movimento, não a cena

A imagem já mostra o que está no plano. O prompt só precisa dizer como isso se move. Três coisas que funcionaram neste lote:

1. Especifique um movimento de câmera (push-in, deriva suave, câmera fixa) e diga o que deve permanecer imóvel.
2. Dê ao sujeito uma ou duas batidas físicas, como uma gota escorrendo, a luz varrendo a cena ou o cabelo sendo levantado pelo vento. É isso que faz um clipe de 5 segundos parecer vivo, em vez de um pan estilo Ken Burns.
3. Escolha um movimento adequado ao tipo de material. Produtos precisam de mudanças de luz e sombra lentas e controladas. Pessoas toleram movimentos maiores e mais calorosos.

Clipe de produto (o clipe de capa acima). Prompt:

Slow cinematic push-in toward the serum bottle, a single water droplet slides
down the amber glass, a band of warm light sweeps across the bottle from left
to right and makes the gold cap glint, the background stays dark and still,
premium skincare commercial

O push-in e a varredura de luz funcionaram bem, e o formato do frasco e a tampa dourada se mantiveram. Um alerta honesto: quando a luz varreu, a borracha preta do conta-gotas ficou mais clara e mais metálica. Para um SKU real, esse é o tipo de deriva de detalhe que a equipe de marca apontaria. Confira os detalhes do produto frame a frame antes de publicar; se alguma peça continuar derivando, tente uma instrução de varredura de luz mais fraca ou mantenha o movimento no fundo.

Imagem estática de retrato / criador. Prompt:

The wind lifts her curls, she turns her head slightly toward the camera and
her half-smile widens into a warm smile, the golden-hour backlight flickers
through her hair, the camera holds steady with a very gentle drift, natural
lifestyle feel

O rosto, o suéter e a luz da hora dourada se mantiveram consistentes, e a virada de cabeça e o sorriso saíram como esperado. No entanto, o movimento de câmera do Ray 3.2 foi maior do que “uma deriva muito suave” sugeria: no último frame, ela já havia se deslocado para o outro lado do quadro, e o horizonte atrás dela também se moveu. Para planos com pessoas, espere que o modelo interprete seu prompt de movimento com folga. Se precisar de enquadramento fixo, diga isso explicitamente, como fizemos no prompt de loop abaixo.

Etapa 3: o truque do loop com end_image_url

Loops funcionam bem em feeds de vídeo curto. Um clipe que recomeça sem emendas é reproduzido repetidamente, e também pode servir de fundo para legendas ou marcações de produto. O end_image_url opcional do Ray 3.2 torna isso fácil: use a mesma imagem estática como primeiro e último frame, e o modelo precisa voltar ao ponto de partida.

{
  "model": "ray-3.2/image-to-video",
  "input": {
    "prompt": "Seamless loop: the warm light slowly brightens and dims across the serum bottle, water droplets glisten, a faint wisp of mist drifts past the stone and fades out, the camera stays locked off, the bottle does not move",
    "image_url": "https://your-cdn.example.com/serum-9x16.jpg",
    "end_image_url": "https://your-cdn.example.com/serum-9x16.jpg",
    "resolution": "540p"
  }
}

Medimos em vez de avaliar a olho. Extraímos o primeiro e o último frame de cada clipe e comparamos com SSIM (1,0 significa idêntico):

Clipe	end_image_url	SSIM primeiro frame vs. último frame
Loop (mesma imagem estática como último frame)	Sim	0,958
Push-in de produto	Não	0,654
Retrato	Não	0,410

Com o último frame fixado, o clipe termina praticamente onde começou, perto o bastante para que uma repetição simples no editor ou no replay automático da plataforma não mostre salto perceptível. Sem a fixação, o clipe termina em uma nova posição, o que é bom para corte, mas não para loop. Duas coisas para lembrar:

• Mantenha o movimento do loop periódico. Luz que clareia e escurece, névoa que entra e sai, câmera fixa: tudo isso funciona. Um push-in não consegue “voltar” de forma convincente em cinco segundos.
• Só testamos loop com a mesma imagem. Passar um último frame diferente (por exemplo, primeiro frame com a caixa fechada e último com a caixa aberta) é exatamente para o que o campo foi projetado, mas não validamos esses resultados aqui, então teste antes de construir uma campanha com base nisso.

Etapa 4: processamento em lote: primeiro fan out, depois colete

A API de tarefas é assíncrona, então não renderize um clipe por vez. Envie todos os pares imagem estática + prompt primeiro, salve no disco no instante em que receber cada taskId, e depois faça o polling:

for each (still, prompt) pair:
    taskId = POST /v1/tasks  (model=ray-3.2/image-to-video, input={...})
    persist taskId immediately        # the task is billed at submit

for each saved taskId:
    poll GET /v1/tasks/{taskId} until status in ("success", "fail")
    on success: download output[0].url now (it expires)

Nosso lote de três clipes foi enviado em sequência, e o tempo no servidor foi de 44 segundos (produto), 41 segundos (loop) e 58 segundos (retrato). Como rodaram em paralelo, o lote inteiro levou aproximadamente o mesmo tempo do clipe mais lento, pouco mais de um minuto no total, incluindo o intervalo de polling de 8 segundos. Se o polling falhar por oscilação de rede, repita com o mesmo id. Reenviar cria e cobra um segundo clipe.

Etapa 5: finalize no editor

A API entrega material bruto, não um post pronto:

• Sem áudio. Os três clipes têm apenas um fluxo de vídeo H.264, sem trilha de áudio. Adicione som em alta, narração ou legendas no editor.
• 5 segundos é uma batida. Empilhe três ou quatro clipes (por exemplo, push-in de produto → loop como fundo de legenda → reação do criador), monte uma versão de 15–20 segundos e faça cortes secos nas batidas.
• Só amplie os vencedores. Rode de novo a imagem estática + prompt escolhidos em 720p ou 1080p para a exportação final, em vez de renderizar o lote inteiro em alta resolução.

FAQ

Como obter um clipe vertical 9:16 com ray-3.2 image-to-video? Forneça uma imagem de entrada 9:16. Não há parâmetro aspect_ratio, e a saída acompanha o formato da entrada. Uma imagem estática de 720×1280 retorna como clipe de 540×960 em 540p.

Consigo fazer um clipe com mais de 5 segundos? Neste endpoint, não. Não há campo duration, e enviá-lo retorna 400. Todo clipe que geramos tem 5,04 segundos (121 frames a 24fps). Empilhe clipes na edição para obter versões mais longas.

O Ray 3.2 i2v suporta último frame? Sim. O campo opcional end_image_url define o frame final. Passar a mesma imagem também como image_url gera um clipe reproduzível em loop (em nossos testes, SSIM entre primeiro e último frame de 0,958).

Ele gera áudio? Não; o MP4 de saída é mudo.

Ele mantém meu produto exatamente igual? Em nossos testes, formato, cor e composição geral se mantiveram bem, mas peças pequenas podem derivar sob movimento forte de luz (a cor da bola do nosso conta-gotas mudou). Confira os detalhes do produto antes de publicar.

Quanto custa um lote? A cobrança é apenas por resolução e quantidade de clipes: $0,2145 em 540p, $0,429 em 720p, $1,7145 em 1080p. Nosso lote de teste com três clipes custou $0,6435.

Comece a colocar suas imagens estáticas em movimento

O Ray 3.2 image-to-video já está disponível na API de tarefas assíncronas. Abra a página do modelo ray-3.2/image-to-video para ver parâmetros e preços atuais, depois pegue três imagens estáticas 9:16 existentes e rode em 540p. Você terá um lote de teste por bem menos de um dólar. Comparando modelos para a mesma tarefa? Veja como o Kling 3.0 lida com vídeo curto image-to-video.