Como usar o happyhorse-1.1 via API hiapi: geração de vídeo a partir de texto, de imagem e de referência

Se você está procurando como usar o happy horse 1.1, aqui vai a versão curta: o happyhorse-1.1 não é um endpoint de modelo, mas três, todos servidos pela API unificada de tarefas assíncronas da hiapi:

Endpoint (ID do modelo)	Função	Entrada obrigatória
happyhorse-1.1/text-to-video	Gera vídeo a partir de um prompt de texto	prompt
happyhorse-1.1/image-to-video	Anima uma imagem estática	image_urls
happyhorse-1.1/reference-to-video	Gera vídeo guiado por imagens de referência e um prompt	prompt, reference_image

Os três endpoints compartilham o mesmo ciclo de vida: POST /v1/tasks para enviar → obter o taskId → consultar GET /v1/tasks/<id> (ou receber callback) → baixar output[0].url. Todas as tabelas de parâmetros e mensagens de erro abaixo foram verificadas contra a API em produção — nada aqui vem de suposição.

Pré-requisitos

Você só precisa de uma coisa: uma chave de API da hiapi. Obtenha-a no console da hiapi — ela tem o formato sk-... e vai no cabeçalho Authorization: Bearer. A geração de vídeo é cobrada por segundo de saída; consulte a página de preços para as tarifas atuais por segundo de cada endpoint.

export HIAPI_KEY="sk-your-key-here"

Exemplo mínimo executável (text-to-video)

Envie a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

A resposta retorna um ID de tarefa em data.taskId. Consulte-o:

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

Quando data.status passa para success, a URL do vídeo está em data.output[0].url. Baixe imediatamente — as URLs de saída carregam um timestamp expireAt e ficam em armazenamento temporário, então trate-as como uma janela de retirada, não como hospedagem permanente.

Abaixo está o script Python completo para o mesmo fluxo (apenas biblioteca padrão):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

Parâmetros de cada endpoint

O schema de entrada é estrito: campos desconhecidos são rejeitados com 400, em vez de silenciosamente ignorados. Campos como size, seed, negative_prompt e audio retornam additional properties ... not allowed. A seguir estão os parâmetros exatamente aceitos por cada endpoint.

happyhorse-1.1/text-to-video

Campo	Obrigatório	Tipo	Valores permitidos
prompt	✅	string	Descrição da sua cena
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Tutorial completo com dicas de prompt: tutorial de text-to-video do happyhorse-1.1.

happyhorse-1.1/image-to-video

Campo	Obrigatório	Tipo	Valores permitidos
image_urls	✅	array de strings	exatamente 1 URL de imagem acessível publicamente (maxItems: 1)
prompt	—	string	Orientação de movimento/cena para a animação
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Há duas armadilhas aqui. Primeiro, image_urls é um array, mas atualmente aceita apenas um elemento — passe ["https://..."], não uma string crua nem várias URLs. Segundo, este endpoint não tem aspect_ratio (a API o rejeita); o enquadramento de saída segue a sua imagem de origem.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

Leitura aprofundada: tutorial de image-to-video do happyhorse.

happyhorse-1.1/reference-to-video

Campo	Obrigatório	Tipo	Valores permitidos
prompt	✅	string	Descrição da cena
reference_image	✅	array de strings	1–9 URLs de imagem acessíveis publicamente (maxItems: 9)
aspect_ratio	—	string	As mesmas 9 proporções do text-to-video
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (segundos)

Este é o endpoint de “mantenha meu personagem/produto consistente”: as imagens de referência ancoram identidade e estilo, enquanto o prompt conduz a ação. Diferente do image-to-video, aqui você recupera o controle de aspect_ratio e pode enviar até 9 imagens de referência.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

Leitura aprofundada: tutorial de reference-to-video do happyhorse-1.1.

Qual endpoint escolher?

• Você só tem uma ideia → text-to-video. O caminho mais rápido do texto ao movimento.
• Você tem a imagem exata que quer animar (foto de produto, ilustração, fotografia) → image-to-video. A imagem de origem é como o primeiro quadro aparece.
• Você precisa manter o mesmo sujeito em vários clipes (um personagem, um mascote, múltiplos ângulos de um produto) → reference-to-video. As imagens de referência fixam a identidade; o prompt varia por clipe.

Padrões para produção

Use callbacks em vez de polling

Para qualquer uso além de um script, registre um webhook ao criar a tarefa — tarefas de vídeo demoram bastante, e fazer polling dentro de um handler de requisição web vai acabar estourando o timeout:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Apenas "when": "final" é suportado — você recebe um único POST quando a tarefa atinge o estado terminal (qualquer outro valor retorna invalid callback.when: only 'final' is supported). Projete seu receptor para ser idempotente com base no taskId: armazene o ID da tarefa no envio e trate callbacks duplicados ou já processados como no-op. Mantenha um varredor de polling de baixa frequência como fallback para callbacks perdidos por instabilidade de rede.

Tratamento de erros: três tipos de falha

1. Erros de validação (HTTP 400, INVALID_REQUEST). As mensagens são muito precisas — leia-as, elas apontam o campo exato:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. Erros de autenticação/permissão (HTTP 401, permission_denied). A chave está errada, ou a chave não tem permissão para acessar este modelo:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

Verifique a chave no console e, se contatar o suporte, inclua o request_id.

3. Falhas de geração (tarefa status: "fail"). O envio foi bem-sucedido, mas a geração falhou; ao consultar ou receber o callback, os detalhes do erro ficam no campo error do objeto da tarefa. Vale a pena tentar novamente com backoff — erros de validação e autenticação não valem.

Controle de custos

A cobrança é por segundo de vídeo gerado, então duration é sua principal alavanca de custo — um clipe de 15 segundos custa 3 vezes mais que um de 5 segundos, e resolution tem impacto menor. Itere no prompt com duration: 3 e 720p, depois renderize a versão final na duração completa. Consulte a página de preços para as tarifas atuais.

Leitura relacionada

• happyhorse-1.1 text-to-video — página do modelo e playground
• happyhorse-1.1 image-to-video — página do modelo e playground
• happyhorse-1.1 reference-to-video — página do modelo e playground
• Fluxo de trabalho para vídeos curtos com happyhorse-1.1
• Documentação da hiapi

Perguntas frequentes

Posso usar imagem e prompt de texto juntos? Sim — image-to-video aceita um prompt opcional além do image_urls obrigatório, e reference-to-video exige tanto prompt quanto reference_image. Apenas text-to-video é só prompt.

Quantas imagens posso enviar? image-to-video: exatamente uma (image_urls é limitado a 1 elemento). reference-to-video: até nove em reference_image. Ambos aceitam arrays de URLs acessíveis publicamente, não upload de arquivos ou base64.

O happyhorse-1.1 suporta os parâmetros seed, negative_prompt ou audio? Não. O schema de entrada é estrito e rejeita esses três com erro 400 additional properties not allowed. Se você precisa de reprodutibilidade, mantenha o prompt e os parâmetros exatamente iguais e faça o versionamento do seu lado.

Quais resoluções e durações estão disponíveis? Nos três endpoints: 720p ou 1080p, e de 3 a 15 segundos (inteiro). Se omitidos, valores padrão são aplicados.

Por que recebo 401 permission_denied com uma chave que parece válida? A chave existe, mas não pode usar este modelo — isso é comum em chaves com escopo restrito ou de teste. Verifique as permissões de modelo da chave no console, ou gere uma nova chave sem restrições.

Como saber quando o vídeo está pronto sem polling? Passe callback: {"url": "...", "when": "final"} no envio. Quando a tarefa atinge success ou fail, a hiapi faz um POST para sua URL. Lembre-se de que as URLs de saída expiram — baixe o arquivo no handler do callback, não faça hotlink dele.