Blogue

Tutorial

Como chamar a API de imagem para vídeo do seedance-2.5: exemplos disponíveis em curl e Python

Nov 12, 2026
Arte de capa abstrata: painéis de vidro translúcidos sobrepostos projetando faixas azuis frias sobre um campo cinza-claro, plano e arquitetônico.
Nesta página

O que o endpoint de imagem para vídeo do seedance-2.5 pode oferecer

O seedance-2.5 imagem para vídeo é um endpoint de modelo assíncrono na HiAPI que converte uma ou duas imagens estáticas em um clipe curto de vídeo. Você envia uma imagem (ou um par de imagens que servem como pontos de início e fim do movimento), descreve a mudança desejada, e a plataforma retorna uma tarefa que, quando a geração termina, é resolvida em uma URL de arquivo de vídeo.

Em uma stack típica de geração de vídeo, este endpoint ocupa a camada de "dar vida a uma imagem estática". Você já tem as imagens de origem — fotos de produto, renders de personagem, quadros de storyboard — e precisa de movimento, não de uma nova imagem. Como a chamada é assíncrona, seu trabalho é enviar a tarefa, guardar o identificador da tarefa e fazer polling contínuo até o resultado estar pronto. Esse padrão de enviar e depois fazer polling é comum nos endpoints de geração de longa duração da HiAPI, então o cliente que você escrever aqui pode ser reaproveitado em outros modelos.

O endpoint também oferece opções de áudio nativo, o que é importante se o seu fluxo de processamento precisa de um clipe com som, e não de um material silencioso para receber trilha sonora depois. Se você precisa de movimento de câmera preciso ao quadro ou de animação em loop, o imagem para vídeo com primeiro e último quadros explícitos costuma ser a opção mais controlável sem montar uma cena 3D.

Pré-requisitos e autenticação

Antes da primeira chamada, prepare três coisas.

1. Uma chave de API da HiAPI

Cada requisição é autenticada com a sua chave, enviada como bearer token no cabeçalho Authorization. Não a versione no controle de código-fonte — leia-a de uma variável de ambiente, para que o mesmo script rode tanto localmente quanto em CI.

export HIAPI_API_KEY="your_key_here"

2. Imagens de origem acessíveis pela API

As entradas de imagem são URLs. Hospede as imagens em um local acessível ao serviço — armazenamento de objetos com URL assinada, CDN ou qualquer endereço HTTPS público. Se não quiser expor as imagens publicamente, gere uma URL assinada de curta duração em vez de tornar o bucket público.

Para o fluxo de primeiro/último quadro, você precisa de uma imagem (apenas o primeiro quadro) ou de duas imagens (primeiro e último quadros).

3. Um cliente HTTP

Qualquer ferramenta que envie JSON serve: curl para testes rápidos de fumaça, requests ou httpx em Python, fetch em Node. Não é necessário SDK especial.

A URL base, o caminho e os nomes de campo específicos do modelo ficam na página do modelo no console da HiAPI; use esses valores literalmente nos exemplos abaixo. Com a chave e a URL da imagem em mãos, você já pode enviar.

Entrada de primeiro quadro e entrada de último quadro

As duas entradas de imagem controlam extremidades diferentes do clipe, e a escolha entre elas muda seu grau de controle sobre o movimento.

Apenas primeiro quadro. Você fornece uma imagem e o modelo gera a partir dela para frente. É a escolha certa quando você quer que o modelo invente o movimento: um retrato virando lentamente, um produto girando, uma paisagem com nuvens passando. Você abre mão da certeza sobre onde o clipe termina, mas ganha mais espaço criativo e precisa de apenas um material.

Primeiro e último quadros. Você fornece duas imagens e o modelo gera o caminho entre elas. É a escolha certa quando o ponto final importa: um logo que se junta ao logotipo final, um personagem que passa da pose A para a pose B, um objeto que desliza da esquerda para a direita do quadro. Fornecer o último quadro restringe o movimento, o que costuma significar menos surpresas e melhor capacidade de loop se você planeja repetir o clipe.

Uma regra prática: se você consegue descrever o clipe como "esta imagem sofre alguma mudança", use apenas o primeiro quadro. Se consegue descrevê-lo como "esta imagem se transforma naquela imagem", forneça as duas. Ao fornecer as duas, mantenha-as consistentes em composição, proporção e iluminação — pares de imagens incompatíveis forçam o modelo a lidar com um salto que parece falha.

Seu prompt deve complementar as imagens, não conflitar com elas. Descreva o movimento, não o conteúdo estático que o modelo já consegue ver.

Envie a primeira requisição com curl

A requisição a seguir envia uma tarefa de imagem para vídeo. Substitua o caminho do endpoint, o identificador do modelo e os nomes de campo pelos valores exibidos na página do modelo seedance-2.5 imagem para vídeo no console da HiAPI, e troque pelas suas próprias URLs de imagem.

curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "prompt": "A câmera avança lentamente enquanto o sujeito se vira em direção à luz",
    "first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
    "last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
  }'

Alguns pontos sobre a estrutura da requisição:

  • prompt descreve o movimento. Mantenha-o curto e específico; listas longas de adjetivos tendem a diluir a instrução.
  • first_frame_image é obrigatório para imagem para vídeo. last_frame_image é opcional — remova o campo por completo na geração com apenas o primeiro quadro.
  • Se precisar de opções de áudio, são campos extras no mesmo corpo JSON (abordados adiante).

A resposta é um objeto de tarefa com um identificador e um status. Guarde o identificador; você precisará dele em cada polling. Se a chamada retornar erro de autenticação ou validação, verifique primeiro os cabeçalhos e a URL da imagem antes de tentar novamente.

A mesma requisição em Python

Abaixo está o código equivalente de envio em Python, reorganizado para facilitar a captura do identificador da tarefa.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_video(first_frame, last_frame=None, prompt="", audio=False):
    payload = {
        "model": "seedance-2.5/image-to-video",
        "prompt": prompt,
        "first_frame_image": first_frame,
    }
    if last_frame:
        payload["last_frame_image"] = last_frame
    if audio:
        payload["audio"] = True

    resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return data["task_id"], data

task_id, raw = submit_video(
    first_frame="https://your-cdn.example.com/frame-01.jpg",
    last_frame="https://your-cdn.example.com/frame-02.jpg",
    prompt="A câmera avança lentamente enquanto o sujeito se vira em direção à luz",
)
print(task_id)

Dois hábitos que vale a pena adquirir desde cedo. Primeiro, defina um timeout explícito na chamada de envio — requisições penduradas devem falhar rápido, não bloquear seu worker. Segundo, guarde a resposta bruta durante o desenvolvimento. O campo que armazena o identificador da tarefa pode diferir de task_id conforme a versão do endpoint, e imprimir o JSON bruto uma vez economiza uma rodada de depuração.

Faça polling da tarefa assíncrona até o vídeo ficar pronto

A geração de imagem para vídeo leva mais tempo do que uma requisição HTTP deve permanecer aberta, então a plataforma adota o ciclo de enviar e depois fazer polling. O envio retorna o identificador da tarefa; em seguida, você consulta periodicamente o endpoint de tarefa até o status atingir um estado terminal.

import time
import requests

def wait_for_video(task_id, interval=5, max_wait=600):
    url = f"{BASE_URL}/<task-path>/{task_id}"
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(url, headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()
        status = task.get("status")
        if status == "succeeded":
            return task["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")

Projete o polling em torno de quatro regras:

  • Faça polling em intervalos moderados. Cinco segundos é um padrão razoável. Martelar o endpoint não faz o vídeo renderizar mais rápido.
  • Sempre defina um prazo limite. Tarefas podem falhar ou ficar na fila mais do que o esperado; um loop sem limite transforma um problema temporário em um worker travado.
  • Trate failed e cancelled como estados terminais. Exponha o campo de erro em vez de repetir a mesma tarefa para sempre.
  • Use backoff no polling contínuo. Se estiver fazendo polling de muitas tarefas ao mesmo tempo, aumente gradualmente o intervalo para evitar picos de tráfego.

Em produção, faça o polling a partir de um worker em segundo plano ou de uma fila, não dentro de um handler de requisição web. O resultado é uma URL de vídeo; baixe-a logo e copie para o seu próprio armazenamento, pois as URLs de recursos gerados geralmente não são permanentes.

Lide com o flag de áudio nativo

O seedance-2.5 pode gerar clipes com áudio nativo, e esse controle é um campo da requisição ao lado das entradas de imagem e do prompt — não um endpoint separado. O nome exato do campo e os valores aceitos estão listados na página do modelo; a função auxiliar em Python acima ilustra o uso passando um booleano audio.

Ativá-lo ou não depende de como o clipe será consumido.

Solicite áudio quando: a saída for diretamente para o público — post em rede social, prévia, demonstração — e você quiser que o clipe pareça completo sem uma segunda edição. O áudio nativo também ajuda os revisores a avaliar o ritmo, pois o som torna a cadência do movimento mais legível.

Pule o áudio quando: o seu fluxo de processamento sobrepuser a própria trilha sonora, o clipe for entrar em ferramentas de composição ou edição, ou você planejar gerar muitas variantes e só trilhar a versão final escolhida. A geração silenciosa mantém o material neutro e evita problemas de sincronização posteriores.

Uma observação prática para delimitar o escopo: trate o áudio como uma decisão por requisição, não como configuração global. Como mostrado acima, uma única função auxiliar que aceita o flag audio permite que o mesmo caminho de código atenda tanto lotes silenciosos em segundo plano quanto a renderização final refinada.

Se o flag estiver presente mas o resultado sair sem som, confirme primeiro se o valor foi serializado como esperado — a string "true" versus o booleano true é um descompasso comum — antes de assumir que o modelo o ignorou.

Pontos de falha comuns e próximos passos

A maioria dos problemas de primeira integração se enquadra em quatro categorias.

Entradas que o serviço não consegue buscar

Uma URL que funciona no seu navegador pode falhar no servidor: bucket privado, link expirado ou host que bloqueia user agents que não são de navegador. Use uma URL assinada com validade suficiente para cobrir toda a geração e confirme que a imagem carrega a partir de uma máquina fora da sua rede.

Quadros incompatíveis

Quando o primeiro e o último quadros diferem em proporção, recorte ou temperatura de cor, o modelo precisa reconciliar esse salto. Antes de enviar, pré-processe o par de imagens para o mesmo tamanho e uma coloração semelhante.

Nomes de campo ou identificador de modelo errados

Os exemplos aqui usam a estrutura de requisição da página do modelo; copie literalmente do console os nomes de campo e a string do modelo, em vez de confiar na memória ou em trechos antigos. Erros de digitação em nomes de campo costumam ser silenciosamente ignorados em vez de rejeitados.

Polling que nunca termina

Se o seu loop der timeout repetidamente, registre cada valor de status que observar. Ver uma string de status inesperada geralmente explica a estagnação — sua verificação de estado terminal pode simplesmente não corresponder ao que a API retorna.

Depois de rodar um único clipe de ponta a ponta, os próximos passos naturais são processar várias imagens em lote com a mesma função auxiliar de enviar e fazer polling, adicionar retentativas com backoff ao redor do envio e gravar os resultados em armazenamento persistente. Você pode encontrar os detalhes do endpoint, os campos da requisição e a referência de parâmetros na página do modelo seedance-2.5 imagem para vídeo e, com base neles, adaptar o código acima às suas próprias imagens.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API