Tutorial
Tutorial da API seedance-2.5-flash image-to-video: curl e Python Requests
Um exercício prático de integração para desenvolvedores: estrutura da requisição, entradas de primeiro/último quadro, polling assíncrono e diagnóstico de erros
Nesta página
O que uma chamada de imagem para vídeo realmente faz
Antes de escrever a primeira linha de código, é útil entender o que a API faz do outro lado. Uma chamada a seedance-2.5-flash/image-to-video não é uma requisição síncrona que fica bloqueada até o arquivo de vídeo retornar. É um workflow assíncrono em duas etapas: você envia a tarefa e depois consulta o resultado periodicamente.
Etapa de envio
Você envia uma requisição POST com a imagem de entrada e as configurações de geração. A API valida o corpo da requisição, enfileira a tarefa e retorna imediatamente uma resposta contendo o identificador da tarefa e o estado inicial. O processo é rápido — geralmente um instante — porque nenhum pixel foi renderizado ainda. Sua tarefa é capturar esse identificador e guardá-lo com segurança.
Etapa de renderização
A geração ocorre em segundo plano. Dependendo da duração do clipe e das configurações, isso pode levar um tempo de relógio considerável. Nessa janela, não espere que a URL final do vídeo já esteja disponível. Em vez disso, consulte o estado da tarefa.
Etapa de resultado
A tarefa finalmente chega a um estado terminal: sucesso, com um artefato de vídeo baixável; ou falha, com um erro que permite o diagnóstico. Assim que o estado terminal for atingido, o polling deve parar.
Por que isso importa para o seu código
Como o modelo é assíncrono, os erros de integração mais comuns são arquiteturais, não sintáticos: supor que a primeira resposta já contém o vídeo, dormir em intervalos fixos em vez de consultar o campo de estado, e não distinguir o estado transitório processing de uma falha permanente. Todo o tutorial gira em torno de um ciclo limpo de “enviar → consultar → sair”, então mantenha essas três etapas em mente durante a leitura.
Pré-requisitos e estrutura da requisição
O que preparar antes da primeira chamada
- Credenciais de API. Sua chave de API HiAPI, enviada em cada requisição. Guarde-a em uma variável de ambiente (
HIAPI_API_KEY), e não no controle de versão — os exemplos abaixo a leem dessa forma. - Identificador do modelo. Neste tutorial a string é fixa:
seedance-2.5-flash/image-to-video. Trate-a como uma constante opaca; não a monte concatenando partes. - Imagem de origem. Uma URL pública ou uma referência de imagem inline suportada. O modelo precisa de pelo menos uma imagem de primeiro quadro.
- Cliente HTTP.
curlpara o teste rápido erequestspara qualquer coisa que você pretenda manter.
Campos lógicos do corpo da requisição
Independentemente da linguagem, o corpo de uma requisição de imagem para vídeo é composto por alguns grupos conceituais. Conhecê-los separadamente torna o JSON mais fácil de entender:
Modelo e entradas
- O identificador do modelo.
- Um objeto de entrada contendo a imagem do primeiro quadro e, opcionalmente, a imagem do último quadro. O capítulo 4 explica como elas interagem.
Configurações de saída
- Opções relacionadas a resolução e duração.
- A opção de áudio nativo, que determina se o clipe gerado terá uma faixa de áudio acompanhante. O capítulo 5 explica quando ativá-la.
O que é retornado
Um envio bem-sucedido retorna um objeto de tarefa. Os campos que você realmente precisa são o identificador da tarefa e o estado atual. Todo o resto são metadados que você pode registrar ou ignorar. No primeiro dia, não converta a resposta inteira em um modelo tipado — registre, inspecione e depois restrinja.
Uma verificação rápida de realidade antes de continuar: se o corpo da sua requisição contiver algum campo cujo nome você não consiga explicar em uma frase, remova-o e comece pelo mínimo. A página do modelo seedance-2.5-flash/image-to-video é a referência para os nomes exatos dos campos aceitos.
Enviar uma tarefa com curl
Comece com a menor requisição que possa funcionar e depois adicione um campo por vez. A seguir está o envio mínimo com curl:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
Comentário campo a campo
Authorization— sua chave de API, como bearer token. Se houver erro aqui, você receberá um erro de autenticação antes que qualquer validação seja executada, então verifique isso primeiro ao depurar.Content-Type: application/json— obrigatório; omiti-lo gera erros confusos nas etapas seguintes.model— o identificador fixo do modelo. Um erro de digitação aqui resulta em 4xx, e não em fallback silencioso.input.first_frame_image— a imagem de abertura do clipe. Use uma URL realmente acessível pela sua rede; URLs privadas ou expiradas falham na busca, não no envio.
Ler a resposta
A resposta é um JSON contendo o identificador da tarefa e o estado. Guarde o identificador imediatamente — é ele que você consultará no capítulo 7. Uma forma rápida de extraí-lo no shell:
# após o curl acima, pipe através de jq
# {"job_id": "...", "status": "queued"}
Adicionar o último quadro
Para controlar também o quadro final, adicione uma segunda imagem dentro do mesmo objeto input. O nome do campo e os formatos aceitos estão na documentação do modelo — não adivinhe grafias alternativas; a API rejeita chaves desconhecidas em vez de ignorá-las.
Assim que a requisição mínima funcionar, você terá um teste rápido que pode executar novamente quando algo der errado. Guarde-o em um arquivo; quando o serviço falhar às duas da manhã, ele vale mais do que qualquer textão.
Entradas de primeiro e último quadro
As imagens de entrada são o maior fator determinante do sucesso de uma tarefa. Elas moldam o conteúdo do clipe e também são a fonte mais comum de requisições rejeitadas.
O que o primeiro quadro controla
A imagem do primeiro quadro define o estado inicial do clipe gerado: composição, sujeito, iluminação e cor. O modelo gera movimento e continuidade a partir desse ponto de partida, então a imagem deve parecer exatamente com o quadro que você quer no instante zero. Imagens de origem desfocadas, cortadas ou muito comprimidas não melhoram magicamente nas etapas seguintes.
O que o último quadro controla
Fornecer uma imagem de último quadro fixa o estado final. Isso é útil quando o clipe precisa terminar em um plano específico — um quadro de produto bonito, uma revelação de logo, um corte combinado na edição. Quando omitido, o modelo escolhe o final por conta própria, o que é aceitável para trabalho exploratório, mas imprevisível para produção.
Como os dois interagem
Quando ambos são fornecidos, o modelo interpola entre eles. Isso tem consequências práticas:
- Continuidade vence contraste. Dois quadros da mesma cena com movimento moderado entre eles produzem um clipe mais coerente do que duas imagens sem relação. Se os quadros forem muito diferentes, espere deformações visíveis em vez de uma transição plausível.
- As proporções devem coincidir. Proporções diferentes entre primeiro e último quadro forçam o modelo a um reenquadramento estranho. Corte ambos para a mesma proporção antes de enviar.
- As resoluções devem ser comparáveis. Enviar um primeiro quadro nítido e um último quadro de baixa resolução dá sinais contraditórios ao modelo.
Checklist antes do envio
Antes de enviar, verifique: as duas URLs de imagem são acessíveis publicamente e não expiram no meio da tarefa; ambas estão em formatos suportados; ambas têm a mesma proporção; nenhuma delas é uma captura de tela com elementos de interface que você não quer que sejam renderizados. Uma requisição HEAD rápida em cada URL detecta a maioria desses problemas de forma mais barata do que uma tarefa de geração falha.
Se você realmente receber uma rejeição, a mensagem de erro normalmente aponta para o objeto de entrada. Valide as imagens localmente — dimensões, formato e acessibilidade — antes de suspeitar da API.
Configurações de resolução e áudio nativo
As configurações de saída são onde os desenvolvedores tendem a configurar demais. A boa notícia é que os padrões são razoáveis; o risco está em copiar valores da documentação de outro modelo.
Resolução
A resolução determina o tamanho do vídeo entregue e, por consequência, o tempo de geração e o volume de saída. Duas regras práticas:
- Escolha pelo destino, não pelo número. Um clipe para um feed mobile não precisa ser renderizado em tamanho grande para depois ser reduzido. Escolha a menor resolução que atenda à plataforma de destino.
- Prefira um dos presets da documentação. Passar valores arbitrários ou não suportados é uma causa comum de rejeição da requisição. Se precisar de um quadro específico, corte ou redimensione após a geração, em vez de brigar com o validador da requisição.
Áudio nativo
A opção de áudio nativo determina se o clipe gerado inclui uma faixa de áudio produzida junto com o vídeo. Considere se você precisa dela:
- Ative-a quando o clipe for a entrega final assistida com som — conteúdo social, promoções curtas, cenas de personagens em que o áudio ambiente reforça a sensação de movimento.
- Desative-a quando você for adicionar sua própria música ou narração no editor, ou quando o clipe for um ativo intermediário. Gerar áudio que você vai descartar é trabalho desperdiçado e torna o processamento posterior mais pesado.
Duração
A duração está acoplada a todo o resto: clipes mais longos levam mais tempo para gerar e estão mais sujeitos a deriva de consistência do sujeito. Para a primeira integração, comece curto. Confirme que o pipeline funciona de ponta a ponta com um clipe curto e depois alongue-o quando confiar no pipeline.
Mantenha o objeto de configurações enxuto
Se você se pegar adicionando configurações para corrigir problemas de qualidade, pare e verifique se o problema está de fato nas imagens de entrada. A maioria dos resultados decepcionantes remonta ao capítulo 4, não à falta de um botão. Configure com intenção, registre o objeto de configurações exato junto com cada identificador de tarefa e você poderá atribuir mudanças de qualidade a ajustes específicos.
Fazer a mesma requisição em Python
A requisição com curl é traduzida diretamente para Python. O objetivo aqui não é um framework — é um cliente pequeno e legível que envia a tarefa e retorna o identificador, para que a camada de polling permaneça separada.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Por que estruturar assim
- Configuração por variáveis de ambiente. A URL base e a chave ficam fora do código, então o mesmo cliente pode rodar contra ambientes diferentes.
timeout=30no envio. O envio é rápido; um envio travado indica problema de rede ou autenticação, que você quer detectar cedo em vez de bloquear o worker indefinidamente.raise_for_status()antes de analisar. Um corpo de resposta 4xx geralmente é um objeto de erro JSON, não uma tarefa. Lançar a exceção primeiro mantém o caminho normal limpo e deixa o chamador tratar a falha explicitamente.- Envio separado do polling.
submit_jobfaz uma coisa só. O ciclo de polling do próximo capítulo recebe o dicionário retornado e é responsável por esperar.
Portar para um serviço
Em um serviço real, envolva a chamada para que as falhas apareçam como uma exceção tipada carregando o código de status e o corpo da resposta — você vai querer o corpo bruto ao depurar em produção. Registre o corpo da requisição junto com o identificador de tarefa retornado; quando um colega perguntar por que um clipe saiu errado, essa linha de log será toda a investigação.
Os nomes dos campos são exatamente os mesmos do exemplo com curl. Se você entende um, entende o outro — e é exatamente por isso que vale a pena começar pelo curl por cinco minutos.
Consultar o resultado sem sobrecarregar a API
Agora a tarefa existe e tem um identificador. A abordagem ingênua — dormir sessenta segundos e torcer — falha de duas maneiras: desperdiça tempo quando a tarefa termina antes e falha completamente quando a tarefa demora mais.
Consulte o campo de estado, não o relógio
Escreva um ciclo que consulta o estado atual da tarefa e ramifica com base nele:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # backoff exponencial limitado
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
Características que importam
- Estados terminais explícitos. Apenas
succeededefailedencerram o ciclo. Qualquer outro estado é transitório. Não trate estados desconhecidos como falha — novos estados intermediários surgem com o tempo, e seu ciclo deve tolerá-los. - Backoff limitado. Comece pequeno (alguns segundos), cresça com um fator moderado e limite em torno de dez a quinze segundos. Isso mantém a agilidade para tarefas curtas sem sobrecarregar o endpoint durante renderizações longas.
- Prazo rígido. Sempre limite o tempo total de espera. Sem isso, uma tarefa travada ocupa um worker para sempre. Escolha o limite com base no seu tempo de renderização real mais longo, mais uma margem.
- Separe falha de timeout. Uma tarefa
failedé um erro de geração que vale a pena relatar ao usuário. Um timeout é uma condição de infraestrutura que merece nova tentativa ou investigação separada. Misturar os dois torna a análise pós-incidente penosa.
Em um serviço web
Não execute esse ciclo no handler de requisição em que o usuário está esperando. Envie a tarefa, armazene o identificador, retorne imediatamente e deixe um worker em segundo plano fazer o polling e entregar o resultado — via webhook, fila ou atualização de linha observada pelo frontend. O ciclo acima é uma preocupação do worker, não do HTTP.
Diagnosticar falhas comuns
A maioria das falhas se encaixa em três categorias. Primeiro determine a categoria, depois a causa específica.
Categoria 1: falha de validação de entrada
Sintoma: um 4xx imediato no envio, antes de qualquer renderização.
Diagnostique nesta ordem:
- A URL da imagem é acessível? Busque-a você mesmo a partir da mesma rede. URLs assinadas expiradas e buckets privados são as principais causas.
- O formato é suportado? Recodifique para um formato padrão em vez de discutir.
- Primeiro e último quadro são consistentes? Proporções incompatíveis ou cenas muito diferentes geralmente se manifestam como falhas de validação ou de qualidade.
- Você adicionou algum campo com nome errado? Chaves desconhecidas costumam ser rejeitadas em vez de ignoradas. Compare com a referência do modelo.
Categoria 2: incompatibilidade de parâmetros
Sintoma: a requisição é rejeitada por causa de alguma configuração, ou a saída ignora sua configuração.
- Resolução ou duração não suportada. Use apenas valores da documentação; números arbitrários são uma causa comum de rejeição.
- Erro de digitação no identificador do modelo. É uma string fixa — copie-a, não digite de novo.
- Erro de aninhamento. Configurações que pertencem ao nível superior colocadas dentro de
input, ou vice-versa, geram erros confusos. Use a estrutura de requisição do capítulo 3 como referência.
Categoria 3: timeout de polling e falha de tarefa
Sintoma: a tarefa é aceita, mas nunca chega a um estado terminal de sucesso.
- Confirme que você está consultando o identificador correto. Erros de copiar e colar entre tarefas em scripts de lote são surpreendentemente comuns.
- Verifique se o estado está realmente avançando. Registre o estado a cada polling para ver se a tarefa progride ou estagna.
- Distinga falha da API de falha de geração. Se a própria requisição de polling falhar, é um problema de transporte. Se a tarefa reportar
failed, leia o corpo do erro — ele geralmente aponta a entrada que causou o problema. - Reexecute o teste rápido mínimo com
curl. Se o teste rápido também falhar, o problema está nas credenciais ou no serviço; se ele funcionar, o problema está no seu corpo de requisição.
Postura geral de depuração
Registre três coisas para cada tarefa: o corpo exato da requisição, o identificador de tarefa retornado e o estado final com o corpo do erro. Com esses três itens, quase todo incidente vira um diagnóstico de cinco minutos em vez de uma tarde inteira. Em caso de dúvida, reduza a requisição à forma mínima do capítulo 3 e adicione campos um a um até ela quebrar — o último campo adicionado é o culpado.
Artigos relacionados
Ver todos os artigos →-
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
-
Tutorial
Cenários práticos de aplicação do gemini-4-neon: 5 usos de alto valor e pontos-chave de integração
-
Tutorial
Como chamar seedance-2.5-flash de texto para vídeo pela API HiAPI (curl e Python)
Um passo a passo funcional para desenvolvedores: endpoint, parâmetros, tratamento assíncrono de tarefas e exemplos executáveis em curl e Python