Tutorial
Como chamar happyhorse-1.1/text-to-video via API HiAPI: exemplos disponíveis em curl e Python
Estrutura de requisição, consulta assíncrona e processamento de áudio nativo para uma integração funcional
Nesta página
O que esta integração cobre
Este guia acompanha você em todo o processo de chamada de happyhorse-1.1/text-to-video por meio da API unificada do HiAPI. Ao final da leitura, você terá uma requisição funcional: enviar um prompt de texto, consultar até a conclusão e salvar o vídeo gerado com sua trilha de áudio nativa. Começamos pela estrutura da requisição, para que você entenda o payload antes de escrever qualquer código; em seguida apresentamos uma chamada curl pronta para copiar; depois explicamos o padrão de consulta assíncrona necessário para a geração de vídeo; por fim, migramos tudo para Python com tratamento básico de erros. Não é necessário ter experiência com APIs de vídeo; você só precisa de uma chave de API do HiAPI e de um terminal ou ambiente Python. O objetivo é oferecer um exemplo de integração mínimo, porém completo, que você possa adaptar ao seu próprio pipeline.
Estrutura da requisição de happyhorse-1.1/text-to-video
Antes de fazer a chamada, vale a pena entender os campos que compõem uma requisição de texto para vídeo. O endpoint aceita um payload JSON que contém, no mínimo, o identificador do modelo e seu prompt de texto. Outros campos comuns controlam o tamanho e a duração da saída, mas os nomes exatos dos parâmetros e os valores aceitos devem seguir a documentação desse modelo no HiAPI. Um payload válido normalmente se parece com isto:
{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Ao nascer do sol, a câmera se move lentamente em panorâmica sobre uma floresta coberta de névoa"
}
Mantenha o payload plano e use apenas os campos descritos na documentação do modelo. Campos não reconhecidos ou tipos malformados são as causas mais comuns de rejeição da requisição. Em caso de dúvida, comece com o payload mínimo contendo apenas model e prompt e adicione parâmetros opcionais um a um, para facilitar a identificação de problemas.
Fazendo a primeira requisição com curl
Com o payload pronto, você pode enviar a tarefa usando curl. Você enviará uma requisição POST com corpo JSON e a chave de API no cabeçalho Authorization. A resposta normalmente contém o identificador da tarefa, que você usará mais tarde para consultar o status. Veja um exemplo funcional:
curl -X POST https://api.hiapi.ai/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "happyhorse-1.1/text-to-video",
"prompt": "Ao nascer do sol, a câmera se move lentamente em panorâmica sobre uma floresta coberta de névoa"
}'
Substitua $HIAPI_API_KEY pela sua chave real ou exporte-a no shell. A resposta será um JSON contendo o campo id (ou um identificador com nome semelhante) e um status indicando que a tarefa foi aceita. Leia a resposta com atenção: se o status não for de aceitação, verifique a mensagem de erro antes de continuar. Nesse momento, não presuma que o vídeo já está pronto; a tarefa acabou de entrar na fila.
Tratando a consulta assíncrona
A geração de vídeo não é instantânea, portanto o HiAPI retorna o identificador da tarefa na resposta inicial, em vez do vídeo final. Você precisa consultar o endpoint de status até que a tarefa atinja um estado terminal. O padrão geral é: enviar a tarefa, obter o ID e então solicitar repetidamente o status da tarefa em intervalos curtos. Pare quando o status indicar sucesso ou falha. A lógica em pseudocódigo é a seguinte:
- Envie a tarefa e leia o
idda tarefa. - Aguarde alguns segundos.
- Solicite o status da tarefa usando esse
id. - Se o status for "completed" ou "succeeded", obtenha a URL de saída e saia do loop.
- Se o status for "failed", registre o erro e saia.
- Caso contrário, aguarde novamente e repita, até atingir um número máximo razoável de tentativas.
Evite consultar com frequência excessiva. Para tarefas de vídeo, um intervalo de alguns segundos entre tentativas costuma ser suficiente. Além disso, não espere que uma única resposta bloqueante contenha o vídeo final; o modelo assíncrono é intencional e consistente em todas as tarefas de geração de longa duração.
Áudio nativo na saída
Os vídeos gerados por happyhorse-1.1/text-to-video já vêm com áudio nativo na saída. Quando a tarefa é concluída, a resposta aponta para o arquivo de vídeo gerado, e esse arquivo já contém a trilha de áudio. Não é necessário gerar ou obter o áudio separadamente. Para salvar e validar o resultado, baixe o arquivo de vídeo a partir da URL fornecida e preserve o formato do contêiner. Se você processar o arquivo programaticamente, verifique se o fluxo de áudio existe, por exemplo, usando uma ferramenta de mídia para inspecionar o arquivo. A menos que o pipeline downstream exija, não remova nem recodifique o áudio, pois isso pode reduzir a qualidade ou remover completamente a trilha. Trate o arquivo retornado como um ativo audiovisual completo.
Fazendo a mesma requisição em Python
Portar a chamada curl para Python é direto: reutilize o mesmo payload JSON e adicione o loop de consulta. O exemplo a seguir usa requests, aguarda entre as tentativas e lança uma exceção em caso de falha. Substitua o caminho do endpoint e os nomes dos campos de status pelos descritos na documentação de happyhorse-1.1/text-to-video no HiAPI.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "happyhorse-1.1/text-to-video",
"prompt": "Ao nascer do sol, a câmera se move lentamente em panorâmica sobre uma floresta coberta de névoa",
}
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
for attempt in range(60):
status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
status_resp.raise_for_status()
status = status_resp.json()
state = status.get("status")
if state in ("completed", "succeeded"):
video_url = status["output"]["url"]
print("Vídeo pronto: ", video_url)
break
if state == "failed":
raise RuntimeError(status.get("error", "Falha na geração"))
time.sleep(5)
else:
raise TimeoutError("Tempo de consulta esgotado")
Isso segue a lógica de "consultar até concluir" descrita anteriormente. Use raise_for_status() para expor erros HTTP o quanto antes e mantenha um intervalo de espera razoável para evitar requisições desnecessárias.
Solução de problemas comuns
A maioria dos problemas de integração se enquadra em algumas categorias. Um payload malformado, como a falta do campo model ou o uso de tipos JSON incorretos, é rejeitado imediatamente; confira seu JSON com atenção em relação à documentação do modelo. Consultas com frequência excessiva podem causar limitação de taxa ou carga desnecessária; aumente o intervalo de espera. Confundir a resposta inicial com o vídeo final é outro erro comum; sempre consulte até o estado terminal. Erros de autenticação geralmente indicam cabeçalho Authorization ausente ou malformado, então verifique se sua chave de API foi exportada corretamente. Por fim, se a tarefa falhar após a consulta, verifique a mensagem de erro na resposta de status; ela geralmente aponta para um prompt inválido ou um parâmetro não suportado. Depois de corrigir esses problemas, tente novamente com o payload mínimo válido.
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