Criando vídeos curtos com happyhorse-1.1/reference-to-video através da API hiapi

A maioria das demonstrações de "vídeo com IA" termina com um único clipe, um único plano. Assim que você precisa que o mesmo personagem apareça no segundo ou terceiro plano — por exemplo, um mascote entrando em cena, depois correndo, depois comemorando — tanto o texto-para-vídeo quanto o imagem-para-vídeo começam a falhar: a cada nova geração, o rosto muda, a roupa muda, a iluminação muda. O happyhorse-1.1/reference-to-video na API hiapi existe justamente para resolver esse problema específico. Você fornece até 9 imagens de referência do mesmo sujeito, mais um prompt que descreve a ação entre planos, e ele retorna um único vídeo contínuo, mantendo o sujeito consistente do início ao fim — em vez de uma apresentação de slides montada no editor com animações independentes coladas umas nas outras.

Nós produzimos e entregamos de ponta a ponta um clipe real de 8 segundos em 720p para ver como isso funciona na prática: o prompt, a chamada à API, o custo e a saída. Segue o processo completo.

Por que reference-to-video é uma ferramenta diferente

O texto-para-vídeo não dá ao modelo nada em que ancorar a identidade, então ao regenerar com o mesmo prompt o rosto e a roupa do personagem podem variar. O imagem-para-vídeo ancora uma pose, o que funciona para um único momento, mas falha assim que sua história precisa de um segundo ângulo ou de uma ação que a imagem de origem nunca mostrou. O reference-to-video fica no meio-termo: múltiplas imagens de referência permitem que o modelo veja o mesmo sujeito de vários ângulos reais — frontal, pose de ação, tudo o que você fornecer — e use essas imagens juntas como âncoras de identidade, para que o vídeo percorra múltiplos momentos sem perder o fio da meada.

Isso o torna adequado a uma necessidade específica e comum de vídeos curtos: clipes de apresentação com mascote, conteúdo social com personagem recorrente, narrativas com personagem de produto — qualquer cenário em que o mesmo "quem" precise atravessar vários "o quês" em um único plano contínuo.

O caso de teste: uma raposa entregadora, três momentos

Criamos um pequeno personagem original — Bramble, uma raposa entregadora — e, antes de começar qualquer coisa relacionada a vídeo, geramos duas imagens de referência para estabelecer a identidade dele.

Prompt usado: "Um pequeno personagem raposa de desenho animado com olhos grandes chamado Bramble: pelagem laranja-avermelhada, focinho e peito cor de creme, orelhas altas e pontudas com interior creme, usando um lenço verde-azulado e carregando uma bolsa de couro marrom surrada de entregador a tiracolo, com um pequeno emblema redondo azul na alça. Estilo de animação 3D de longa-metragem, iluminação suave e quente, pose de corpo inteiro virada para a câmera, fundo neutro e liso, design de personagem consistente."

Prompt usado: "O mesmo personagem raposa Bramble — pelagem laranja-avermelhada, focinho creme, lenço verde-azulado, bolsa de couro marrom de entregador com emblema azul — congelado em corrida numa pose de ação dinâmica em três quartos, um braço balançando para frente, cauda ondulando para trás, olhos grandes e expressivos, mesmo estilo de animação 3D de longa-metragem e mesmas proporções da folha de referência, fundo neutro e liso."

Cada imagem custou $0.03 para ser gerada. Juntas, elas formam todo o passo de "escalação de elenco" — nenhuma chamada de vídeo acontece até que o personagem esteja definido.

Chamando a API

O reference-to-video, como todos os outros modelos da plataforma, é um endpoint baseado em tarefas: envie e depois consulte até a conclusão.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "Bramble the fox courier picks up a glowing gift box at a warm, lantern-lit delivery station and looks at it with delight; cut to Bramble sprinting through a bustling night market strung with red lanterns, package tucked under one arm, tail flying; cut to Bramble standing proudly on a rooftop at golden-hour sunset, package delivered, looking out over the rooftops with a satisfied smile. Consistent character design throughout, cinematic 3D animated feature style, warm lighting, smooth camera motion.",
      "reference_image": [
        "https://static.hiapi.ai/blog/happyhorse-1-1-reference-to-video-short-form-video/01-bramble-front.png",
        "https://static.hiapi.ai/blog/happyhorse-1-1-reference-to-video-short-form-video/02-bramble-action.png"
      ],
      "duration": 8,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Isso retorna um taskId. Consulte-o até que o status atinja um estado terminal:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_API_KEY"

O status passa por queued → handling → (às vezes) archiving → success ou fail. Em caso de sucesso, o clipe concluído está em uma URL temporária em output[0].url — baixe imediatamente, o link expira.

Campos que confirmamos funcionar

Campo	Tipo	Valor que usamos	Observação
prompt	string, obrigatório	Descrição de tomada em 3 momentos	Escreva como uma mini lista de storyboard, não como uma frase genérica
reference_image	array de URLs de imagem	2 imagens	A plataforma indica suporte a até 9 por clipe
duration	inteiro, segundos	8	A série happyhorse-1.1 varia de 3 a 15 segundos
resolution	string	"720p"	"1080p" também disponível, com preço maior
aspect_ratio	string	"16:9"	Enumeração padrão de proporção de tela

Resultado

Observe o personagem entre os pontos de corte: mesma cor de pelagem, mesmo lenço verde-azulado, mesma bolsa com emblema azul, desde a retirada interna até a corrida no mercado noturno e o pôr do sol no telhado. É exatamente esse o sentido de fornecer duas imagens de referência em vez de uma — diante da troca de cena, o modelo tem mais em que se ancorar do que uma única imagem estática. O clipe também inclui áudio nativo automaticamente; não há campo de áudio separado a configurar.

Exemplo reutilizável em Python

import json
import subprocess
import time

def generate_reference_video(prompt, reference_images, token,
                              duration=8, resolution="720p", aspect_ratio="16:9"):
    payload = {
        "model": "happyhorse-1.1/reference-to-video",
        "input": {
            "prompt": prompt,
            "reference_image": reference_images,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    submit = subprocess.run(
        ["curl", "-s", "-X", "POST", "https://api.hiapi.ai/v1/tasks",
         "-H", f"Authorization: Bearer {token}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, check=True,
    )
    task_id = json.loads(submit.stdout)["data"]["taskId"]

    while True:
        poll = subprocess.run(
            ["curl", "-s", f"https://api.hiapi.ai/v1/tasks/{task_id}",
             "-H", f"Authorization: Bearer {token}"],
            capture_output=True, text=True, check=True,
        )
        task = json.loads(poll.stdout)["data"]
        if task["status"] in ("success", "fail"):
            break
        time.sleep(5)

    if task["status"] != "success":
        raise RuntimeError(task.get("error"))
    return task["output"][0]["url"]

Quanto custa

Item	Custo
Imagem de referência (frontal)	$0.03
Imagem de referência (pose de ação)	$0.03
Clipe de 8 segundos @ 720p ($0.16/segundo)	$1.28
Total desta demonstração	$1.34

720p custa $0.16/segundo; 1080p custa $0.21/segundo, então o mesmo clipe de 8 segundos em 1080p custaria $1.68. As tarifas completas atuais estão sempre na página de preços — confira lá antes de aumentar a duração ou a resolução dos clipes.

Dicas de prompt para consistência entre vários planos

• Escreva o prompt como uma lista de tomadas, não como uma frase. "Momento 1 → Momento 2 → Momento 3", cada momento com uma ação clara, é o que realmente impulsiona planos distintos dentro de um clipe — uma única descrição genérica tende a se fundir em um movimento contínuo.
• Garanta você mesmo a consistência visual entre as imagens de referência. O modelo preserva o que já é consistente entre suas imagens de referência; ele não reconcilia inconsistências. Se sua imagem frontal e sua imagem de ação tiverem tons de pelagem diferentes ou um emblema faltando, essa ambiguidade se propaga para o vídeo.
• Forneça uma pose que a imagem estática nunca mostrou. O valor de múltiplas referências em relação a uma única é que o modelo consegue sintetizar ações e ângulos além do que qualquer imagem isolada mostra — uma pose frontal e uma pose de ação bastam para sustentar momentos calmos e momentos cheios de energia.
• Sinalize explicitamente as mudanças de cenário. "corte para", "então" e nomes de locais específicos no prompt correspondem diretamente aos cortes de plano que você vê na saída.

Perguntas frequentes

Quantas imagens de referência posso usar? Até 9 por clipe. Nesta demonstração usamos 2, o que bastou para manter a identidade ao longo de três momentos distintos.

Há suporte a 1080p? Sim — 1080p custa $0.21/segundo, contra $0.16/segundo do 720p.

E se eu tiver apenas uma imagem de referência? Use happyhorse-1.1/image-to-video — mesma série, imagem inicial única, sem ancoragem de identidade por múltiplas referências.

A mesma série tem opção de texto-para-vídeo puro? Sim, happyhorse-1.1/text-to-video, com a mesma tarifa por segundo, para quando você não tem nenhuma imagem estática de referência.

A saída inclui som? Inclui, o áudio nativo é gerado automaticamente junto com a imagem — não há parâmetro de áudio separado a definir.

Qual pode ser a duração do clipe? A série happyhorse-1.1 vai de 3 a 15 segundos; usamos 8 segundos para apresentar uma narrativa em três momentos.

Principais conclusões

• happyhorse-1.1/reference-to-video transforma 2 a 9 imagens estáticas em um vídeo contínuo, mantendo o mesmo personagem, figurino e estilo artístico em cada plano.
• Uma demonstração completa e funcional — 2 imagens de referência mais um clipe de 8 segundos em 720p — custa $1.34 de ponta a ponta na API hiapi.
• Além do prompt, o modelo só precisa de três campos: reference_image (array de URLs), duration (3 a 15 segundos) e resolution (720p ou 1080p).
• Escreva o prompt como uma lista de tomadas (Momento 1 → Momento 2 → Momento 3), não como uma descrição genérica — é isso que realmente impulsiona a estrutura de vários planos.
• O áudio nativo é gerado automaticamente junto com o vídeo, sem necessidade de uma etapa separada de geração de áudio.

Pronto para testar com seus próprios personagens? Comece pela página do modelo happyhorse-1.1/reference-to-video, ou veja um fluxo de trabalho semelhante para vídeos curtos no nosso tutorial prático do Seedance 2.0 Mini.