Como chamar happyhorse-1.1/image-to-video na API hiapi: guia com curl e Python

O que esse endpoint faz e quando usá-lo

happyhorse-1.1/image-to-video converte uma única imagem estática em um vídeo curto. Você envia uma imagem de primeiro quadro para o endpoint, e o modelo gera animação a partir desse quadro. O significado prático está na continuidade: o sujeito, a composição e a aparência da imagem inicial continuam no clipe gerado. É isso que chamamos aqui de preservação de identidade — o modelo não cria uma cena nova do zero a partir de um prompt de texto, mas continua uma cena que você já criou com uma imagem.

Portanto, esse endpoint é ideal quando a identidade visual importa mais do que a improvisação:

• Você já tem uma imagem estática de referência — um retrato, uma foto de produto, um design de personagem — e quer gerar movimento fiel a essa imagem.
• Você produz curtas em um pipeline no qual todo o restante do material é desenhado primeiro como imagem.
• Você precisa de animatic ou prévia de movimento para quadros de storyboard.

Ele é menos adequado quando você quer que o modelo reinterprete livremente a cena do zero, ou quando não há imagem estática para ancorar a saída. Nesses casos, um fluxo de trabalho com prioridade em imagem geralmente significa gerar primeiro uma imagem de ancoragem e depois entregar esse resultado a este endpoint.

A chamada em si é assíncrona: você envia uma tarefa e depois consulta até o vídeo ficar pronto. O restante deste guia percorre esse ciclo de ponta a ponta.

Antes de enviar a solicitação

Duas coisas precisam estar prontas antes da primeira chamada.

Chave de API

Todas as chamadas passam pela plataforma hiapi, e a chave de API é anexada como credencial bearer. Mantenha a chave em uma variável de ambiente, não no controle de código-fonte, para que o mesmo código funcione tanto no desenvolvimento local quanto no CI:

export HIAPI_API_KEY="your_key_here"

Em Python, leia-a em tempo de execução com os.environ["HIAPI_API_KEY"]. Nunca registre o valor bruto do header.

Imagem de primeiro quadro referenciável

O endpoint exige uma imagem inicial. Decida com antecedência como passá-la — como uma URL que a plataforma possa buscar, ou como um material enviado/codificado em base64, dependendo do que sua conta e a documentação do endpoint suportarem. O importante é que a referência seja estável e acessível no momento do envio. Se a tarefa puder ficar na fila, uma URL assinada que expira em cinco minutos é uma péssima escolha.

Também ajuda saber antes da chamada a proporção e a duração esperadas da saída, pois o primeiro quadro normalmente as restringe. Tomar essa decisão com antecedência evita reenviar depois.

Com a chave exportada e a referência de imagem definida, você já pode enviar.

Montando a entrada do primeiro quadro

O primeiro quadro é a âncora de tudo o que o modelo gera depois. Na prática, você deve tratá-lo como um contrato de identidade: qualquer coisa claramente visível nessa imagem — rosto, roupa, logotipo, esquema de cores, ângulo de câmera — é algo que o modelo deve respeitar. Se algum detalhe da imagem estática estiver borrado ou ocluído, a saída também ficará.

Independentemente dos parâmetros específicos do modelo, alguns princípios de preparação se aplicam:

• Escolha um quadro nítido e bem iluminado. Artefatos de compressão e ruído intenso reduzem o que o modelo consegue preservar. Uma imagem nítida e com iluminação uniforme é uma âncora melhor do que uma imagem dramática, mas borrada.
• Posicione o sujeito onde você quer que o movimento comece. Recortar e compor na imagem estática custa menos do que esperar que o modelo reenquadre.
• Mantenha a proporção esperada da saída. Se o vídeo final é horizontal, prepare uma imagem de ancoragem horizontal; preencher depois não recupera a composição perdida.
• Evite pistas contraditórias. Uma imagem estática que lê como uma coisa, mas implica em ação fora do quadro, dá ao modelo um ponto de partida instável.

Não presuma parâmetros específicos do modelo além da documentação do endpoint. A abordagem mais segura é deixar a própria imagem carregar a intenção e depois usar os campos da solicitação apenas para o que eles cobrem explicitamente.

Fazendo uma solicitação funcional com curl

Enviar uma tarefa requer apenas um POST. A estrutura é: enviar uma solicitação autenticada ao endpoint, com o corpo JSON carregando o identificador do modelo e a entrada de imagem.

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image": "https://your-bucket.example.com/first-frame.jpg"
    }
  }'

Passo a passo:

1. O endpoint. O destino do POST é a rota de geração de vídeo na API hiapi. Se você for escrever scripts para vários ambientes, coloque-a em uma variável.
2. O header de autenticação. Authorization: Bearer $HIAPI_API_KEY — o shell expande a variável de ambiente que você exportou anteriormente.
3. O tipo de conteúdo. application/json, porque o corpo é JSON.
4. O corpo. model seleciona happyhorse-1.1/image-to-video; input.image é sua referência de primeiro quadro. Consulte a documentação de referência do endpoint para saber o nome exato do campo de imagem e a estrutura aceitos na sua conta.

A resposta bem-sucedida não é o vídeo em si — é um handle de tarefa. Espere receber um identificador e um campo de status, normalmente algo como queued ou processing. Anote o ID; você o usará para consultar nas etapas seguintes. Execute o comando uma vez e imprima a resposta, para ver sua estrutura antes de começar a escrever scripts.

Enviando a mesma solicitação com Python

A versão em Python é um porte direto, não uma nova integração. Mesma rota, mesmos headers, mesmo corpo JSON.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/video/generations"

payload = {
    "model": "happyhorse-1.1/image-to-video",
    "input": {
        "image": "https://your-bucket.example.com/first-frame.jpg"
    },
}

resp = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)

Notas de mapeamento:

• requests com json=payload serializa o dicionário como a string -d do curl — se você usar json=, não defina Content-Type manualmente; a biblioteca cuida disso. O header explícito acima é inofensivo, mas redundante.
• raise_for_status() transforma falhas na camada HTTP em exceções logo no início, antes que você comece a consultar uma tarefa que não existe.
• O timeout é apenas uma proteção do cliente na chamada de envio. A geração roda no servidor e não é limitada por ele.

Mantenha o payload em uma variável e reutilize-o. Quando mudar o modelo ou a imagem mais tarde, você deve editar apenas um dicionário, não duas implementações paralelas.

Lidando com tarefas assíncronas e polling

A geração de imagem para vídeo leva mais tempo do que um ciclo de requisição/resposta. Por isso a API retorna imediatamente uma referência de tarefa e espera que você consulte depois. O ciclo de vida é: enviar, receber o ID, consultar o status, obter o resultado.

Extraia o ID da tarefa da resposta de envio — o nome do campo depende do schema de resposta documentado desse endpoint, então leia-o uma vez e fixe a busca pela chave no código, não o valor:

job_id = job["id"]  # check the endpoint docs for the exact field

Depois consulte em intervalos:

import time

poll_url = f"https://api.hiapi.ai/v1/video/generations/{job_id}"

while True:
    status = requests.get(
        poll_url,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    ).json()

    if status["status"] == "succeeded":
        break
    if status["status"] == "failed":
        raise RuntimeError(status)
    time.sleep(5)

Regras para manter o polling razoável:

• Consulte em intervalos fixos, não em loop apertado. Para tarefas desse porte, alguns segundos entre verificações bastam; martelar o endpoint aumenta a carga sem fazer o resultado surgir mais cedo.
• Limite o tempo total de espera. Um while True sem limite é um travamento que vai acontecer mais cedo ou mais tarde. Acompanhe o tempo decorrido e falhe explicitamente após um orçamento razoável.
• Trate os dois estados terminais. Sucesso e falha são ambas respostas. Trate strings de status desconhecidas como não terminais, mas registre-as para perceber mudanças de padrão.
• Não consulte uma tarefa a partir de vários workers paralelos. Um consultor por tarefa, ou coordene via fila.

Assim que o status for terminal, siga para o download do resultado.

Baixando e armazenando a saída

O vídeo concluído é exposto na resposta da tarefa concluída como um material — normalmente uma URL, às vezes com tempo de expiração. O primeiro passo após um polling bem-sucedido é buscar essa referência e copiar os bytes para um armazenamento sob seu controle.

video_url = status["output"]["video_url"]  # inspect the real response shape

with requests.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"out/{job_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 20):
            f.write(chunk)

Orientações de armazenamento válidas para qualquer pipeline:

• Copie os artefatos persistentes; não os referencie. URLs assinadas ou com tempo limitado são meio de transporte, não armazenamento. Persista o arquivo e depois guarde sua própria chave de objeto no banco de dados junto com o ID da tarefa.
• Faça streaming de arquivos grandes. iter_content mantém a memória estável; carregar o vídeo inteiro em uma variável vincula o limite de memória ao tamanho do material.
• Registre a proveniência. Salve o job_id, a referência da imagem de entrada e o identificador do modelo junto com o material. Quando precisar reproduzir o clipe, esse registro é a receita.
• Verifique o status HTTP antes de escrever. Uma escrita parcial causada por uma resposta de erro é pior do que uma falha limpa, porque parece um arquivo válido.

Depois que o arquivo chega ao disco ou ao armazenamento de objetos, o pipeline fecha o ciclo e você pode seguir para o próximo quadro.

Erros e armadilhas a observar

A maioria das falhas desse endpoint é previsível. Uma lista curta:

• Entrada de primeiro quadro malformada ou inacessível. A causa mais comum de envio rejeitado. Verifique se a URL da imagem resolve publicamente, se o formato é aceito pelo endpoint e se o payload aninha corretamente o campo de imagem. Reproduza com uma chamada curl para distinguir problemas de autenticação de problemas de payload.
• Consultar antes de a tarefa existir. Ler o ID do campo errado, ou consultar uma rota que não corresponde à resposta de envio, produz um 404 que parece falha de tarefa. Imprima a resposta de envio uma vez e fixe a busca pela chave com base nela.
• Espera sem limite. Sem timeout, uma tarefa travada suspende o worker indefinidamente. Defina um orçamento, falhe e alerte.
• Perder o link do material. A geração dá certo, mas a URL é consumida uma vez e nunca copiada. Salve os bytes no momento da busca e mantenha sua própria chave; não dependa do link retornado como armazenamento de longo prazo.
• Vazamento de credenciais. Colar a chave em um notebook e commitar por acidente é um problema recorrente. Carregue a partir do ambiente e, em caso de dúvida, faça rotação.
• Presumir parâmetros não documentados do endpoint. Se você precisa de um parâmetro não listado, ele não existe. Expresse a intenção apenas pela imagem de primeiro quadro e pelos campos documentados.

Lidando com isso, o fluxo assíncrono se torna corriqueiro — que é exatamente o que você quer em um pipeline de produção. Para nomes de campos e valores aceitos específicos do endpoint, mantenha a documentação de referência do endpoint aberta enquanto constrói.