Como usar a API de imagem para vídeo do LTX 2.5 Fast? Dê vida a imagens estáticas

TL;DR

• LTX 2.5 Fast Image to Video (ltx-2.5-fast/image-to-video) dá vida a imagens estáticas: envie 1 imagem de primeiro frame (opcionalmente mais 1 de frame final), gere vídeos de 2–20 segundos em 720p / 1080p com áudio nativo. Abra a página do modelo, envie uma imagem e teste; novos usuários ganham 200 créditos ao se registrar.
• Preço com a mesma regra do texto para vídeo: 720p a $0.043 por segundo, 1080p a $0.086 por segundo, cobrado conforme os segundos de duration; a chave de áudio não afeta o preço.
• A chamada usa a interface /v1/tasks da HiAPI: image_urls recebe 1–2 imagens (primeiro frame / primeiro frame + frame final); após sucesso, pegue o vídeo em output.

O que ele faz

• Primeiro frame em movimento: uma foto estática + uma descrição de movimento, o sujeito da imagem permanece igual, com adição de movimento, câmera e som.
• Primeiro frame + frame final: envie duas imagens, o modelo completa a transição do primeiro frame ao frame final (por exemplo, de uma cabana de dia para uma cabana em noite estrelada).
• Proporção vertical acompanhada: o formato de saída é decidido por aspect_ratio (16:9 / 9:16); recomenda-se que seja igual ao primeiro frame para evitar cortes ou bordas.
• Texto para vídeo da mesma família: para gerar do zero, veja o guia de integração de texto para vídeo; as regras de preço das duas interfaces são idênticas.

Abaixo está um resultado real (foto estática de farol → clipe de 6 segundos com som):

Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls

(Em português: as ondas quebram nas rochas abaixo do farol, as gaivotas deslizam pelo céu dourado, a câmera avança lentamente, som do mar e das gaivotas. O primeiro frame usa a foto do farol do material; parâmetros: 720p, 6 segundos, 16:9.)

→

ltx-2.5-fast/image-to-video, 720p, 6 segundos, 16:9, 1280×720, com som, $0.258.Ver o clipe completo →

Gerar com este prompt →

Como enviar primeiro frame / primeiro frame + frame final

Entrada	image_urls	Efeito
1 imagem	["imagem do primeiro frame"]	Começa a se mover a partir desta imagem, sujeito inalterado
2 imagens	["imagem do primeiro frame", "imagem do frame final"]	Transição do primeiro frame ao frame final, o modelo completa o processo intermediário

As imagens aceitam endereços públicos JPG / PNG / WebP; recomenda-se que as duas imagens tenham o mesmo formato, e aspect_ratio deve ser definido igual ao do primeiro frame.

Duas rotas para começar

Navegador em 3 passos: abra a página do modelo → envie a imagem do primeiro frame, escreva a descrição de movimento → clique em gerar e pré-visualize o resultado.

API em 3 passos: POST /v1/tasks para enviar → obtenha o taskId → GET /v1/tasks/<taskId> até ver success e baixe.

curl: o primeiro (frame único)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
    "image_urls": ["https://static.hiapi.ai/gallery/2026/10/0ca26560398eae72.jpg"],
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9"
  }
}'

Primeiro frame + frame final (cabana de dia → cabana em noite estrelada): altere apenas image_urls:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ltx-2.5-fast/image-to-video",
  "input": {
    "prompt": "Time passes from bright winter day to starry night, the sky darkens, the cabin windows light up warmly and smoke rises from the chimney, an aurora appears, fixed camera",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/7756ea1a228b0b88.jpg",
      "https://static.hiapi.ai/gallery/2026/10/16e267619aa1b003.jpg"
    ],
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }
}'

Python: enviar, consultar, baixar

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "ltx-2.5-fast/image-to-video",
    "input": {
        "prompt": "Waves crash against the rocks below the lighthouse, seagulls glide across the golden sky, the camera slowly pushes in, sound of surf and gulls",
        "image_urls": ["https://example.com/your-first-frame.jpg"],
        "resolution": "720p",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video = next(o for o in task["output"] if o.get("type") == "video")
    mp4 = requests.get(video["url"], timeout=120)   # endereço temporário, salve o quanto antes
    with open("output.mp4", "wb") as f:
        f.write(mp4.content)
    print("saved output.mp4")

Tabela de parâmetros

Campo	Obrigatório	Valores	Descrição
image_urls	Sim	1–2 endereços públicos	A 1ª é o primeiro frame; a 2ª é o frame final (JPG/PNG/WebP)
prompt	Sim	1–5000 caracteres	Descreva movimento, câmera e som; não repita o que já está na imagem
resolution	Não	720p / 1080p, padrão 720p	O preço por segundo em 1080p é cerca de 2 vezes o de 720p
duration	Não	2/3/4/5/6/8/10/12/14/16/18/20, padrão 6	Valores enumerados
aspect_ratio	Não	16:9 / 9:16, padrão 16:9	Recomenda-se igual ao primeiro frame para evitar cortes ou bordas
generate_audio	Não	padrão true	Áudio nativo; desligue se for adicionar música na pós-produção

Campos fora da tabela no corpo da requisição retornam 400 diretamente.

Erros que você vai encontrar

Código de status	Significado	Como tratar
400 INVALID_REQUEST	Corpo da requisição inválido (falta image_urls ou prompt, enviou 3 imagens, duration fora dos valores enumerados)	Ajuste o corpo conforme a tabela de parâmetros
402 INSUFFICIENT_QUOTA	Saldo insuficiente (sem cobrança)	Recarregue e tente novamente
429 RATE_LIMITED	Limite de requisições atingido	Reduza a frequência de envio
409 / 422 IDEMPOTENCY_KEY_*	Envio repetido com a mesma chave de idempotência	Use um novo Idempotency-Key

Falhas no estado final da tarefa incluem CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT etc.; falhas não são cobradas.

Atenção antes de ir para produção

• Callback: tarefas de vídeo demoram, envie "callback": {"url": "https://..."} no nível superior do corpo para evitar polling.
• Salve logo: o endereço do vídeo em output é temporário, baixe assim que receber.
• Formato consistente entre primeiro e último frame: se a proporção das duas imagens for muito diferente, a transição tende a distorcer; defina aspect_ratio igual ao do primeiro frame.
• Para adicionar música na pós-produção: envie generate_audio como false para obter imagem limpa, o preço não muda.
• A qualidade do primeiro frame define a qualidade do vídeo: um primeiro frame desfocado ou de baixa resolução não ficará nítido ao se mover; use primeiro uma imagem grande e nítida e depois deixe o modelo adicionar movimento.

Perguntas frequentes

• Sim, no máximo 2 imagens: 1 de primeiro frame ou primeiro frame + frame final; a 3ª retorna 400.
• Sim, o formato não segue a imagem: é decidido por aspect_ratio, por isso recomenda-se definir manualmente igual ao do primeiro frame.
• Sim, o preço é igual ao de texto para vídeo: 720p a $0.043 por segundo, 6 segundos custam $0.258.
• Sim, a transição de frame final é ideal para "passagem do tempo": de dia para noite, de cena vazia para cena cheia de produtos, duas imagens e um prompt bastam.
• Sim, dar vida a imagens de produto é o ponto forte: use a imagem principal do produto como primeiro frame, escreva no prompt o movimento de câmera (orbit, push in) e elementos de destaque, e um vídeo de demonstração sai pronto.
• Sim, fotos verticais com 9:16: saída em 720×1280, direto para plataformas de vídeo curto; fotos horizontais mantêm 16:9.

Próximo passo: pegue uma imagem do seu produto e dê vida a ela na página do modelo; para quatro cenários de imagem para vídeo, veja o guia completo de prompts.