Tutorial
Como chamar hailuo-2.3/image-to-video pela API do HiAPI: curl e Python
Nesta página
O que hailuo-2.3/image-to-video faz e quando usar
hailuo-2.3/image-to-video é um modelo de imagem para vídeo disponibilizado pela API unificada do HiAPI. Você fornece uma imagem estática como primeiro quadro e um prompt descrevendo como a cena deve se mover; o modelo gera um vídeo curto que começa nessa imagem e avança a animação a partir dela.
A palavra-chave é primeiro quadro. Na geração de texto para vídeo, o modelo imagina a cena inteira a partir do prompt; na geração de imagem para vídeo, a composição, o sujeito, a iluminação e o estilo ficam ancorados na imagem que você fornece. Por isso, é a escolha mais adequada quando você já tem um material visual específico que precisa preservar — foto de produto, imagem de referência de personagem, quadro de storyboard, render conceitual — e quer adicionar movimento sobre ele, em vez de reinterpretá-lo.
Cenários adequados para usar este endpoint:
- Você precisa manter coerência com material existente. Uma foto de produto não deve ser regenerada como um produto ligeiramente diferente, mas sim ganhar movimento.
- Você está montando storyboards ou animatics a partir de quadros estáticos e quer pré-visualizar o movimento rapidamente.
- Você precisa de composição controlada: o enquadramento e a posição do sujeito vêm da imagem, e o prompt descreve apenas o movimento.
Se você não tem imagem de referência e quer que o modelo conceba o enquadramento, ou se os detalhes visuais são mais bem expressos em texto do que fixados por um quadro, a geração de texto para vídeo é mais adequada.
Pré-requisitos e obtenção da chave de API
Antes da primeira requisição, você precisa de três coisas: uma conta no HiAPI, uma chave de API e uma URL de imagem de primeiro quadro acessível publicamente.
Conta e chave de API
Entre no HiAPI e crie uma chave de API no console. Trate a chave como segredo: guarde-a em uma variável de ambiente, em vez de colar no arquivo-fonte. Os exemplos deste guia leem de HIAPI_API_KEY.
export HIAPI_API_KEY="your-api-key-here"
URL de imagem acessível
A imagem passada como primeiro quadro precisa ser obtida pelo servidor — URL de armazenamento em nuvem assinada, link de CDN ou qualquer URL HTTPS pública serve; caminho de arquivo local não. Se o material estiver em um local que exige autenticação, gere uma URL assinada com validade limitada para a requisição.
Antes de automatizar qualquer fluxo, confirme na documentação de referência mais recente da API do HiAPI o caminho atual do endpoint, os nomes de parâmetros e os valores permitidos. As interfaces de modelos evoluem, e codificar nomes de parâmetros vistos em tutoriais antigos é uma fonte comum e evitável de erros. O preço atual e quaisquer regras de cota estão listados no painel de preços do site — confirme lá, não presuma.
Estrutura da requisição: entrada de imagem e parâmetros
Conceitualmente, uma requisição de imagem para vídeo tem três partes: o identificador do modelo, a imagem e os parâmetros de geração.
Identificador do modelo
Cada chamada aponta para hailuo-2.3/image-to-video. Mantenha-o em um único lugar no código, para que trocar de modelo depois exija apenas uma linha.
Imagem do primeiro quadro
É a URL da imagem estática inicial do vídeo. Sua proporção e resolução determinam a geometria base da saída, então escolha uma imagem que já tenha a composição desejada, em vez de recortar depois. Uma imagem limpa, bem iluminada e com sujeito claro produz movimentos muito mais previsíveis do que uma colagem confusa.
Prompt
O campo de texto que descreve o movimento — apresentado na próxima seção.
Duração e resolução
Tarefas de imagem para vídeo geralmente oferecem opções de duração do clipe e resolução de saída. Esses parâmetros são os mais propensos a mudar com a versão do modelo, então não os codifique de memória. Abra a documentação de referência mais recente da API, leia os nomes de campos aceitos e os valores permitidos, e coloque esses valores em um objeto de configuração, em vez de espalhar literais pelo código. Se um valor for rejeitado, a resposta da API normalmente indica qual campo está com problema.
O corpo da requisição é JSON; a resposta retorna um identificador de tarefa, não o vídeo concluído, o que é abordado na seção de polling abaixo.
Escrevendo prompts que produzem movimento verossímil
A imagem já descreve o que há na cena. A tarefa do prompt é descrever como ela se move. Prompts que redescrevem o sujeito desperdiçam a capacidade do modelo; prompts que especificam movimento, comportamento de câmera e física produzem clipes muito melhores.
Descreva movimento, não conteúdo
Exemplo ruim: “Uma mulher de casaco vermelho em pé sobre uma ponte.”
Exemplo melhor: “A mulher vira lentamente a cabeça em direção à câmera, o casaco balança ao vento; a câmera avança suavemente.”
Separe o movimento do sujeito do movimento de câmera
Seja explícito sobre ambos. “Avanço lento para frente”, “oscilação de câmera na mão”, “câmera fixa” e “órbita para a direita” dizem como o quadro em si muda; “cabelo ao vento”, “vapor subindo” e “páginas virando” descrevem o que acontece dentro do quadro. Combinar os dois gera um plano coerente, em vez de uma imagem à deriva.
Respeite a física
Peça movimento plausível em velocidade plausível: “o tecido ondula levemente”, “a água corre rio abaixo”, “a fumaça sobe em espiral”. Evite instruções que contradigam a cena — fazer um sujeito sentado andar, ou pedir um pan rápido em um plano fixo de produto, geralmente gera artefatos.
Seja breve e específico
Duas ou três frases concretas e físicas valem mais do que um parágrafo inteiro de adjetivos. Diga primeiro o movimento principal, depois a câmera e, por fim, detalhes secundários como variações de iluminação.
Enviando a tarefa e consultando o resultado
A geração de vídeo leva tempo, então a API é assíncrona. O ciclo de vida tem três etapas:
1. Criar a tarefa
Envie por POST a URL da imagem, o prompt e os parâmetros para o endpoint. Uma resposta bem-sucedida retorna um identificador de tarefa e um status inicial, geralmente algo como queued ou processing. Ainda não há vídeo nessa resposta.
2. Consultar a tarefa
Envie periodicamente requisições GET para esse identificador de tarefa. Cada resposta informa o status e, quando concluída, inclui o payload do resultado. Consulte em intervalos razoáveis — normalmente alguns segundos — em vez de em um loop apertado, e limite o número de tentativas para que uma tarefa travada não deixe o processo pendurado para sempre.
3. Obter o vídeo
Quando o status indica sucesso, a resposta contém a localização do vídeo (geralmente uma URL) e, muitas vezes, metadados como duração. Baixe ou armazene conforme suas próprias políticas de retenção.
Pontos de design para produção
- Persista o ID da tarefa. Se o seu worker cair no meio do polling, você quer poder retomar em vez de reenviar e pagar por uma tarefa duplicada.
- Trate falhas terminais. Tarefas podem falhar; trate a falha como um ramo separado, não como “continuar consultando”.
- Desacople envio e polling. Em um backend web, envie a partir do handler da requisição e faça o polling em um worker em segundo plano, para que timeouts HTTP nunca encerrem uma geração em andamento.
Exemplo executável com curl
O exemplo abaixo envia uma tarefa. Substitua a URL da imagem e o prompt pelos seus; a chave vem da variável de ambiente definida anteriormente.
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "O sujeito da cena vira levemente em direção à câmera e sorri; a câmera avança lentamente, luz suave percorre o rosto."
}'
A resposta contém o identificador da tarefa. Consulte-o com uma requisição GET:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Repita até que o status seja de sucesso terminal e então leia a URL do vídeo a partir do payload. O caminho exato do endpoint e os nomes de campos mostrados aqui servem apenas para ilustrar o padrão — antes de colar qualquer coisa em código de produção, confirme na documentação de referência mais recente da API, pois as interfaces de modelos realmente mudam.
Exemplo executável em Python
Este script envia a tarefa, depois consulta até a conclusão, incluindo timeout e tratamento básico de erros.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="Vapor sobe da xícara; a câmera se desloca lentamente para a direita.",
)
result = poll_task(task)
print(result)
Como as strings de status podem diferir entre versões da API, o código verifica um pequeno conjunto de valores comuns de sucesso e falha, em vez de um único literal — confirme o vocabulário exato na documentação de referência da API e ajuste o conjunto conforme necessário. Se você constrói vários pipelines de mídia, manter essa função auxiliar separada facilita a reutilização.
Padrões comuns de falha e como depurar
A maioria dos problemas deste endpoint se encaixa nas categorias abaixo.
Imagem rejeitada ou inacessível
O serviço precisa conseguir baixar sua imagem. Se aparecer um erro de obtenção ou validação, verifique se a URL é HTTPS pública, se não expirou (URLs assinadas expiram) e se o formato e o tamanho estão dentro dos limites documentados. Uma verificação rápida é abrir a URL em uma janela privada do navegador — se ela pedir login, o servidor também não conseguirá lê-la.
Parâmetros inválidos
Duração, resolução ou campos desconhecidos rejeitados normalmente retornam um erro de validação indicando o campo. Compare seu payload com a documentação de referência mais recente da API, não com um tutorial, e registre o corpo completo do erro — a mensagem é mais específica do que apenas o código de status HTTP.
Erros de autenticação
401 ou 403 quase sempre significam chave ausente, mal formatada ou sem permissão de acesso. Confirme que o cabeçalho Authorization está presente e que a variável de ambiente foi realmente exportada no shell ou processo que executa a requisição.
Timeout no polling
Se a tarefa continuar em processing após o seu timeout, primeiro verifique se você está consultando o ID de tarefa correto e depois aumente o timeout. Em produção, diferencie “ainda em execução” de “travada”: persista o estado e faça o worker retomar o polling, em vez de reenviar, pois reenviar desperdiça tarefas.
Tarefa falha após o envio
Tarefas que falham geralmente apontam para a combinação de prompt e imagem — instruções de movimento contraditórias, ou um primeiro quadro que conflita com o movimento solicitado. Simplifique o prompt, tente um primeiro quadro mais limpo e execute novamente.
A saída parece errada
Se o movimento estiver fraco ou estranho, a correção quase sempre está no prompt: declare explicitamente o movimento principal, separe o comportamento da câmera do comportamento do sujeito e mantenha o movimento fisicamente plausível. Registre o ID da requisição e o ID da tarefa nos logs, para associar clipes ruins às entradas exatas que os produziram. Antes de publicar, confirme os nomes dos parâmetros e os preços atuais na documentação de referência da API e no painel de preços.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio