Gere vídeos curtos em lote no hiapi com hailuo-2.3-fast/image-to-video

O sucesso de um vídeo curto depende da velocidade de iteração. Se seu fluxo de trabalho é um pipeline voltado para TikTok ou Reels, você não precisa de saída 4K de nível cinematográfico — você precisa de um modelo que transforme uma imagem estática de produto em um clipe utilizável em menos de um minuto, e com custo baixo o suficiente para que você possa rodar dezenas de variantes antes de escolher a melhor versão. Esse é exatamente o posicionamento do hailuo-2.3-fast/image-to-video: o irmão de camada Fast do hailuo-2.3, com preço e ajuste dedicados a fluxos de trabalho de múltiplas tentativas descartáveis e alto volume.

Este guia mostra como usá-lo como um motor de vídeos curtos em lote: como escolher a imagem estática de origem, como acioná-lo pela API de tarefas assíncronas, como validar aqueles detalhes de schema que, se ignorados, causarão erros 400, e como pensar na economia de executá-lo em escala TikTok/Reels.

O que o modelo oferece

O hailuo-2.3-fast/image-to-video recebe uma imagem estática e um prompt e a anima em um clipe de vídeo curto. Ele fica na página do modelo hailuo-2.3-fast/image-to-video e — como todos os modelos no hiapi — é chamado por meio do endpoint assíncrono unificado /v1/tasks: você faz POST de uma tarefa, consulta (ou registra um callback) até a conclusão, e então baixa o vídeo a partir de uma URL de saída de validade curta.

Verificado contra a API ao vivo no momento da redação:

• Entrada: uma imagem (image_url) + prompt de texto descrevendo o movimento desejado
• Saída: MP4, duração fixa de 6s ou 10s (comprimentos arbitrários não são suportados)
• Preço: preço fixo por vídeo, não cobrança por segundo — $0.27 por clipe de 6 segundos, $0.46 por clipe de 10 segundos
• Tempo de resposta: nosso clipe de teste concluiu de ponta a ponta (envio → sucesso) em cerca de 80 segundos

O preço fixo por vídeo é o detalhe crucial para trabalhos em lote: uma tentativa de 6 segundos custa o mesmo, seja seu prompt acertando o movimento de primeira, seja já sendo a quarta tentativa. Pelo preço da camada Fast, rodar 5-6 variantes da mesma imagem principal para encontrar a de movimento mais suave ainda custa menos do que uma única tentativa na maioria dos modelos de vídeo de alto padrão. Antes de orçar um lote, confirme os números atuais na página de preços — os preços mudam.

Se você precisa da referência completa de parâmetros, opções de duração mais longas, ou uma comparação lado a lado com a camada hailuo-2.3 não-Fast, consulte nosso tutorial de integração da API hailuo-2.3-fast/image-to-video — este guia foca no ângulo de lote/fluxo de trabalho, não na referência bruta da API.

Fluxo de trabalho: imagem estática → clipe curto

A receita para vídeos curtos é simples: parta de uma imagem estática que você já tem (fotografia de produto, hero shot gerado, material de marca) e deixe o modelo adicionar movimento — push-in lento, rotação sutil, atmosfera flutuante — em vez de gerar vídeo do zero. Isso trava sua identidade visual (mesmo produto, mesma iluminação, mesma composição) enquanto produz conteúdo que não é um post estático.

Este é um caso real de execução: uma imagem estática vertical (9:16) de um tênis de corrida sobre uma base iluminada, acionada por um prompt de movimento descrevendo um push-in lento e uma rotação suave.

A imagem estática de origem e a requisição completa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Slow smooth push-in on a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating above a wet concrete pedestal, subtle rotation revealing the side panel, mist drifting through teal-to-amber rim light, dust particles catching the light, stable cinematic camera movement, premium commercial product-video finish",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Resposta:

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

Consulte até a resolução ser concluída:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X \
  -H "Authorization: Bearer $HIAPI_API_KEY"

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

Esse output[0].url é temporário — baixe imediatamente e transfira para seu próprio armazenamento. Não faça hotlink dele, nem o armazene em um campo de banco de dados esperando que seja uma URL estável.

Schema de entrada (verificado contra a API ao vivo)

O schema deste modelo é bem mais restrito do que você esperaria de outros modelos de vídeo da plataforma — sem controle de proporção, sem níveis de resolução, sem seed.

Campo	Tipo	Restrição	Obrigatório
prompt	string	Descreve movimento/cena	Sim
image_url	string	Singular — uma URL pública, não um array	Sim
duration	string	Enum "6" ou "10" — como string, não número	Sim
prompt_optimizer	boolean	Permite que a plataforma reescreva/melhore seu prompt	Não

Se você trouxer suposições de outros modelos, duas armadilhas causarão erro 400:

1. image_url é singular, não image_urls. Vários outros modelos i2v no hiapi recebem um array de imagens de referência; este modelo recebe apenas uma. Enviar um array resultará em erro de campo ausente, não em uma conversão de tipo útil.
2. duration deve ser a string "6" ou "10", não o número 6. Enviar o número 6 retorna duration: got number, want string. E qualquer valor fora desse enum de dois valores não é aceito — esta camada não tem controle de duração arbitrária.

Enviar aspect_ratio, resolution, seed ou watermark — campos comuns em modelos irmãos — será rejeitado diretamente com additional properties ... not allowed. O modelo herda a proporção da imagem de entrada, então se você precisa de saída 9:16 para Reels/TikTok, corte ou gere a imagem estática de origem em 9:16 antes de enviar (foi exatamente o que fizemos com a imagem do tênis acima).

Python de ponta a ponta

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

Para uma execução realmente em lote — por exemplo, testar 6 variantes de prompt na mesma imagem estática de origem para escolher o movimento mais suave — envolva essa função em um loop sobre a lista de prompts e verifique cada task_id de forma independente, em vez de bloquear sequencialmente; considerando cerca de 80 segundos por clipe, rodar vários em paralelo é o que faz a camada Fast realmente parecer rápida.

Perguntas frequentes

Posso controlar a proporção da saída? Não — este modelo não tem campo aspect_ratio, e enviá-lo retorna 400. A saída segue a proporção da imagem de entrada, então prepare a imagem estática de origem na proporção desejada antes de enviar (9:16 para Reels/TikTok, 1:1 para posts de feed).

Por que minha requisição falha com "got number, want string"? Você enviou duration como um número JSON. Ele deve ser a string "6" ou "10" — esses são os únicos dois valores válidos.

É o mesmo modelo que hailuo-2.3/image-to-video (não-Fast)? Não — a camada Fast é um modelo separado e com preço próprio no hiapi, com seu próprio schema, ajustado para velocidade e custo em vez da camada padrão. Se você precisa da referência não relacionada a lote, consulte o tutorial completo de integração.

Posso alimentá-lo com imagens geradas em vez de fotos reais? Sim — a imagem estática de origem pode vir de qualquer modelo de imagem no hiapi (ou em outro lugar), desde que seja uma URL publicamente acessível. Usar as imagens estáticas que você já produziu para outros formatos (hero shots de produto, pôsteres) costuma ser a forma mais rápida de obter vídeos curtos, sem precisar de um fluxo criativo separado.

O preço varia com a resolução? Este modelo não tem parâmetro de resolução, então o preço é fixo por duração, independentemente da resolução da imagem de entrada — no momento da redação, $0.27 para 6s e $0.46 para 10s. Confirme na página de preços.

Pontos principais

• hailuo-2.3-fast/image-to-video transforma uma imagem estática em um MP4 de 6s ou 10s, com preço fixo por vídeo ($0.27 / $0.46) em vez de cobrança por segundo — barato o suficiente para rodar várias variantes de prompt em cada imagem de origem.
• O schema é intencionalmente restrito: prompt, image_url (singular), duration (enum de string "6"/"10"), e o opcional prompt_optimizer — sem controle de proporção, resolução ou seed.
• A saída herda a proporção da imagem de entrada, então prepare a imagem estática de origem em 9:16 (ou qualquer proporção que sua plataforma exija) antes de enviar.
• Os dois erros de integração mais comuns são enviar image_url como array e enviar duration como número em vez de string.
• Para fluxos de trabalho de vídeos curtos em lote, o preço fixo por vídeo e o tempo de resposta de cerca de 80 segundos tornam viável gerar várias tentativas e escolher o melhor movimento, em vez de submeter apenas uma geração por material.

Pronto para experimentar nas imagens dos seus próprios produtos? Vá para a página do modelo hailuo-2.3-fast/image-to-video para testar uma requisição diretamente, ou, se quiser primeiro comparar a camada Fast com outras opções de imagem para vídeo, consulte o catálogo completo de modelos.