Tutorial
Como chamar o seedance-2.5-flash reference-to-video via API HiAPI (curl + Python)
Requisições funcionais, um script Python executável e como tratar o polling de tarefas assíncronas
Nesta página
O que reference-to-video significa na prática
Reference-to-video é um modo de geração em que você fornece ao modelo duas coisas ao mesmo tempo: um prompt de texto que descreve movimento e cena, e um ou mais materiais de referência que ancoram o conteúdo visual. O prompt carrega a intenção ("aproximação lenta, o personagem se vira e sorri"), e os materiais de referência carregam identidade e aparência (um personagem, um produto, um estilo visual).
O endpoint de modelo para este fluxo de trabalho é seedance-2.5-flash/reference-to-video, disponibilizado pela API unificada da HiAPI. Você envia o model, o prompt e os materiais de referência juntos em um único corpo de requisição. Não há etapa separada de upload para orquestrar, nem registro por material para manter.
A consequência prática: esta é uma operação de longa duração. A renderização de um vídeo curto ainda leva muito mais tempo do que uma completion de texto, então a API trata a chamada como uma tarefa assíncrona. Sua requisição cria a tarefa; uma segunda chamada obtém o resultado. Esse formato de "enviar primeiro, consultar depois" é o ponto mais importante do seu design e é a direção que o restante deste tutorial constrói.
Tudo abaixo permanece dentro das interfaces da HiAPI: uma URL base, um cabeçalho de autenticação, uma família de endpoints.
Antes de enviar a primeira requisição
Três coisas precisam estar prontas antes da primeira chamada.
1. Chave de API
Crie a chave no console da HiAPI e mantenha-a longe do controle de versão. Os exemplos abaixo a leem de variáveis de ambiente:
export HIAPI_API_KEY="your_key_here"
Se você não tiver certeza do formato atual da chave ou da convenção de cabeçalhos, consulte a documentação da API da plataforma no console — não adivinhe e não codifique a chave diretamente em scripts que você possa compartilhar.
2. URL base e cabeçalho de autenticação
Todas as chamadas vão para a URL base da HiAPI e carregam sua chave no cabeçalho Authorization. Defina isso uma vez como variável para manter cada requisição consistente:
export HIAPI_BASE_URL="https://api.hiapi.ai"
Use a URL base exatamente como descrito na documentação da sua conta — uma barra final incompatível é uma causa comum de 404 confusos.
3. Endpoint do modelo
Seu alvo é seedance-2.5-flash/reference-to-video. Referencie-o pelo identificador no corpo da requisição, não o embuta no caminho, assim trocar de modelo depois exigirá apenas uma linha.
Você também precisa que os materiais de referência estejam acessíveis por URL (ou em qualquer formato de material que a documentação do endpoint especifique). Hospede-os e torne-os publicamente acessíveis antes de começar — uma URL de referência quebrada é a causa mais comum de uma tarefa ser enviada com sucesso, mas falhar durante a geração.
Com esses três itens configurados, você pode montar o corpo da requisição.
Montando o corpo da requisição com materiais de referência
O corpo da requisição tem três partes conceituais: qual modelo usar, o que você quer e o que referenciar.
Modelo
Defina model como seedance-2.5-flash/reference-to-video. Trate-o como um campo de string comum — sem codificação de URL, sem segmento de caminho.
Prompt
Escreva o prompt como uma descrição de cena, não como uma lista de desejos. Especifique o sujeito, a ação, o comportamento da câmera e o ritmo. "Uma pessoa de jaqueta vermelha caminhando em direção à câmera, plano médio, aproximação lenta, luz suave" dá ao modelo muito mais informação do que "um vídeo bonito de uma pessoa". Mantenha o prompt consistente com os materiais de referência que fornecer: se dois materiais de referência mostrarem personagens diferentes, indique qual é o dominante.
Materiais de referência
Os materiais de referência são exatamente o que diferencia este endpoint de uma chamada comum de text-to-video. Você passa um ou mais materiais que definem o que deve permanecer consistente entre os quadros. Regras práticas que economizam iterações:
- Use o menor número de materiais de referência que determine a identidade. Uma referência forte costuma superar quatro referências medíocres.
- Mantenha os materiais de referência consistentes entre si. Ângulos ou estilos conflitantes causam deriva na saída.
- Prefira fontes limpas e bem iluminadas. Materiais recortados, desfocados ou com filtros pesados propagam esses defeitos.
- Verifique se cada URL é resolvível antes de enviar — busque-a você mesmo uma vez primeiro.
Como os materiais de referência são de fato indexados no corpo da requisição (nome do campo de array, estrutura de objeto, tipos de material suportados) deve vir do esquema de requisição do endpoint na documentação da HiAPI. Monte o corpo da requisição conforme esse esquema, não de memória; o esquema é a fonte autoritativa dos nomes de campo, e chaves incompatíveis causam falhas silenciosas.
Valide o JSON localmente antes que a requisição chegue à rede (python -m json.tool body.json). Um corpo malformado é o erro mais fácil de capturar e o mais chato de depurar a partir de um stack trace.
Uma requisição curl funcional
O comando abaixo segue o padrão de enviar primeiro e consultar depois: ele cria a tarefa e imprime a resposta JSON, que contém o identificador de tarefa que você usará para consultar.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "Uma pessoa de jaqueta vermelha caminhando em direção à câmera, plano médio, aproximação lenta, luz suave",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Substitua as URLs de referência pelos seus próprios materiais hospedados e, antes de depender deste código em produção, confirme o caminho do endpoint e os nomes dos campos na página do modelo na documentação da HiAPI — os detalhes do esquema são autoritativos e este trecho é apenas ilustrativo.
O que observar na resposta:
- Um id (ou identificador de task/job) — capture-o; você precisará dele em cada consulta.
- Um campo status indicando que a tarefa foi aceita.
- Quaisquer avisos sobre materiais ignorados ou rejeitados.
Para facilitar a leitura, formate-o:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Manter o corpo da requisição em body.json vale esse pequeno esforço extra: ele entra no controle de versão de forma limpa, pode ser comparado de forma legível e remove erros de aspas do shell do escopo de depuração.
A mesma chamada em Python
Abaixo está a chamada equivalente em Python, escrita para ser executada diretamente após definir as variáveis de ambiente. Ela usa apenas a biblioteca padrão, então não é preciso instalar nada.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="Uma pessoa de jaqueta vermelha caminhando em direção à câmera, plano médio, aproximação lenta, luz suave",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Dois detalhes importam mais do que parecem. Primeiro, timeout=60 — a chamada de envio deve retornar rápido, mas uma conexão travada é pior do que uma falha rápida. Segundo, result.get("id") trata casos em que a estrutura da resposta é inesperada, em vez de lançar KeyError no seu caminho normal.
Se você preferir requests ou httpx, a conversão é direta: mesma URL, mesmos cabeçalhos, mesmo corpo JSON. A construção do corpo é a parte que vale copiar; o cliente HTTP é substituível.
Consultando a tarefa assíncrona até a conclusão
A geração de vídeo não é uma requisição que você pode esperar. Você envia, recebe o identificador e então verifica o status periodicamente até a tarefa atingir um estado terminal. Duas características tornam isso seguro: o polling tem baixo custo, e a chamada de envio já realizou o trabalho caro.
O loop
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
Um loop mais apertado não será mais rápido; apenas consumirá limites de taxa. Para tarefas de vídeo, um intervalo de cinco segundos é um padrão razoável.
Notas de design
- Sempre defina um prazo final. Uma tarefa que nunca termina jamais deve deixar uma thread de requisição pendurada para sempre.
- Trate estados desconhecidos como "continuar aguardando", não como sucesso. Apenas sucesso explícito é sucesso.
- Não faça polling dentro de um handler de requisição web. Envie no handler, devolva o id da tarefa ao cliente e deixe um worker em segundo plano consultar e persistir o resultado.
- Persista o id da tarefa e as transições de status, para que um processo interrompido possa retomar em vez de reenviar e pagar duas vezes pela renderização.
Essa separação entre enviar e consultar é exatamente o que permite colocar um pipeline de vídeo lento atrás de uma API rápida.
Erros comuns e como corrigi-los
Quase toda falha na primeira hora se enquadra em uma de quatro categorias. Verifique-as nesta ordem.
1. Autenticação
Sintoma: uma resposta não autorizada ou proibida antes de qualquer tarefa ser criada.
Verifique: HIAPI_API_KEY está realmente preenchida no shell ou processo que executa o script? O cabeçalho é exatamente Authorization: Bearer <key>? Você carregou a chave na importação quando o script espera usá-la mais tarde? Imprima os primeiros caracteres da chave resolvida (nunca a chave inteira) e confirme que não é uma string vazia.
2. Caminho do endpoint
Sintoma: não encontrado, geralmente imediatamente.
Verifique: exatamente uma barra entre a URL base e o caminho — é por isso que o exemplo Python chama .rstrip("/"). Confirme o caminho de geração e o caminho de consulta na página do modelo na documentação; uma URL de consulta sem o segmento de id de tarefa dará 404 sempre. Uma barra final que o servidor não espera produz o mesmo sintoma.
3. Corpo da requisição malformado
Sintoma: erro de validação, ou uma tarefa aceita que falha logo em seguida.
Verifique: execute json.dumps(body) e inspecione-o. model corresponde exatamente a seedance-2.5-flash/reference-to-video? O campo de referência é um array e cada entrada é uma URL de string resolvível no navegador? Você enviou Content-Type: application/json? Passe o corpo por python -m json.tool para descartar erros de sintaxe antes de chegar à rede.
4. Status da tarefa
Sintoma: a chamada de envio tem sucesso, mas a tarefa falha ou nunca conclui.
Verifique: leia o campo de erro na resposta de status — ele geralmente indica a causa, mais comumente um material de referência inacessível ou não suportado. Se a tarefa apenas parar, confirme que você está consultando o id correto e que a comparação de status no loop cobre os estados terminais que a API realmente retorna. Registre cada transição de status; o último estado antes da falha é sua base de diagnóstico.
Uma regra que encurta as quatro categorias de diagnóstico: registre o id da requisição e o id da tarefa para cada chamada. Quando algo falhar, um id transforma um relatório de erro vago em uma busca concreta.
Próximos passos
Você agora tem a forma completa: montar o corpo da requisição com prompt e materiais de referência, enviá-lo, consultar até o estado terminal e tratar as quatro classes comuns de falha. A partir daqui, os próximos passos naturais são de engenharia, não de API.
- Envolva o envio em retentativas com backoff para erros de rede transitórios, mas nunca retente uma tarefa que já tem id — isso é renderização duplicada.
- Mova o polling para um worker ou fila, para que a camada HTTP permaneça responsiva e as tarefas sobrevivam a reinícios de processo.
- Armazene o id da tarefa junto com os metadados da sua própria requisição (prompt, materiais de referência, usuário solicitante), para que os resultados permaneçam rastreáveis meses depois.
- Só libere materiais de referência após validação — busque cada URL quando o usuário a fornecer, antes de gastar uma tarefa.
Para o esquema de requisição autoritativo, formatos de material suportados e detalhes atuais do endpoint, consulte a página do modelo seedance-2.5-flash reference-to-video na HiAPI. Monte conforme esse esquema, mantenha a separação entre enviar e consultar, e a integração continuará sem graça — que é exatamente o que você quer de um pipeline de vídeo.
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