API de imagem para vídeo do Seedance 2.5: como enviar o primeiro frame, o primeiro e o último frame e imagens de referência

TL;DR

• seedance-2.5/image-to-video faz uma imagem se mover, e você também pode fornecer o primeiro e o último frame ao mesmo tempo para o modelo preencher o processo intermediário. Cada clipe tem de 4 a 30 segundos e já vem com áudio. Abra a página do modelo para gerar online; novos usuários ganham 200 créditos ao se cadastrar.
• Mesmo preço do texto para vídeo: 720p a $0.204 por segundo, 1080p a $0.516 por segundo. 4 segundos em 720p custa $0.816.
• Escolha um dos dois modos: primeiro frame / primeiro e último frame, ou imagem de referência + áudio de referência; não é possível misturar.

Veja primeiro um resultado real: primeiro e último frame

Use uma imagem de «vaso vazio» como primeiro frame e uma de «vaso cheio de manjericão» como último frame, e escreva no prompt apenas como a cena muda no meio:

Time-lapse growth of a basil seedling sprouting and unfurling leaves inside the terracotta pot, smooth continuous motion, soft morning light staying consistent, camera locked off, no cuts

Gerar com este prompt → (envie seu primeiro e último frame, 4 segundos, 720p)

seedance-2.5/image-to-video, primeiro frame + último frame, 720p, 4 segundos, com áudio, $0.816.

Mantenha a composição, a iluminação e a posição dos objetos iguais nas duas imagens e mude apenas o que você quer que o vídeo mostre (aqui, a planta); assim a transição intermediária fica fluida. O trecho "soft morning light staying consistent" no prompt serve para impedir que o modelo transforme também a iluminação em time-lapse.

curl: apenas o primeiro frame

O uso mais comum: uma foto de produto ou ilustração, mais uma frase dizendo «como deve se mover em seguida»:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "input": {
      "prompt": "A câmera empurra lentamente em direção a uma xícara de café fumegante, o vapor gira e sobe na luz da manhã, leve tremor de câmera na mão",
      "first_frame_url": "https://your-cdn.example.com/coffee-cup.jpg",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Retorna o taskId:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Consulte o resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando status for success, baixe o vídeo em output[0].url.

Primeiro e último frame: adicione um last_frame_url

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "Time-lapse da mesma escrivaninha do dia para a noite: a luz do dia escurece aos poucos, a luminária de mesa acende com luz quente, as luzes da cidade lá fora se acendem uma a uma, câmera fixa",
    "first_frame_url": "https://your-cdn.example.com/desk-day.jpg",
    "last_frame_url": "https://your-cdn.example.com/desk-night.jpg",
    "duration": 4,
    "resolution": "720p"
  }
}

• last_frame_url deve ser usado junto com first_frame_url.
• Se a proporção do último frame for diferente da do primeiro, o último frame será cortado ao centro; o ideal é gerar as duas imagens na mesma proporção.
• O enquadramento segue o primeiro frame; aspect_ratio tem apenas o valor adaptive e não precisa ser enviado.

Python: enviar, consultar e baixar

# pip install requests; antes faça export HIAPI_KEY=sua_Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="seedance-2.5/image-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # Ao reenviar a mesma tarefa, use o mesmo Idempotency-Key para evitar cobrança duplicada
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "Time-lapse growth of a basil seedling sprouting and unfurling leaves, camera locked off, no cuts",
    first_frame_url="https://your-cdn.example.com/seedling-start.jpg",
    last_frame_url="https://your-cdn.example.com/seedling-grown.jpg",
    duration=4, resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Outro modo: imagem de referência + áudio de referência

Se você não quer fixar uma imagem como primeiro frame, mas quer que o modelo «use como referência» a aparência de uma pessoa, o visual de um produto ou o estilo de desenho, use reference_image_urls (até 30 imagens) e também pode adicionar reference_audio_urls (até 10 trechos) para referenciar o estilo de som:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "A garota da imagem de referência, com a mesma mochila azul, atravessa uma esquina chuvosa, câmera acompanha",
    "reference_image_urls": [
      "https://your-cdn.example.com/girl.jpg",
      "https://your-cdn.example.com/backpack.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }
}

Atenção: imagens de referência e áudios de referência não podem ser enviados junto com first_frame_url / last_frame_url; escolha um dos dois.

Visão geral dos parâmetros

Parâmetro	Valores	Descrição
prompt	string, obrigatório	Descreva a ação, a câmera e o som; não é preciso descrever a imagem inteira de novo
first_frame_url	URL da imagem	Primeiro frame
last_frame_url	URL da imagem	Último frame, usado junto com o primeiro
reference_image_urls	até 30 imagens	Não pode ser usado junto com primeiro/último frame
reference_audio_urls	até 10 trechos	Não pode ser usado junto com primeiro/último frame
duration	inteiro de 4 a 30, padrão 5	Em segundos
resolution	720p / 1080p, padrão 720p
generate_audio	padrão true	Áudio e imagem gerados juntos
output_format	mp4 / mov

Calcule o custo

Duração	720p ($0.204/s)	1080p ($0.516/s)
4 segundos	$0.816	$2.064
5 segundos	$1.02	$2.58
10 segundos	$2.04	$5.16
15 segundos	$3.06	$7.74

Primeiro e último frame têm o mesmo preço de apenas primeiro frame; o custo depende apenas da resolução e dos segundos. Para mais detalhes, veja Preços da API do Seedance 2.5.

Atenção antes de ir para produção

• O endereço da imagem precisa ser acessível publicamente: pode ser um endereço HTTP(S) ou data URL; endereços de rede interna não são acessíveis pelo modelo.
• Use callback em vez de polling: adicione no nível superior da requisição "callback": {"url": "https://seu-dominio/hiapi/callback"} e deduplique por taskId.
• Salve o resultado logo: output[0].url é um link temporário; armazene-o no seu próprio storage assim que recebê-lo.
• Retentativas com chave de idempotência: adicione o cabeçalho Idempotency-Key; a mesma chave só cria a tarefa uma vez.
• Reembolso automático em caso de falha: a cobrança é feita apenas pelos vídeos gerados com sucesso.

Perguntas frequentes

O que fazer se aparecer um «crossfade» entre o primeiro e o último frame?

Quando as duas imagens são muito diferentes, é comum que um ou dois segundos no meio pareçam um crossfade entre as duas. Mantenha a composição e os objetos iguais nas duas imagens, mude apenas o sujeito e escreva "camera locked off, no cuts" no prompt.

Posso enviar apenas o último frame?

Não; o último frame precisa ser usado junto com o primeiro.

Posso especificar formato vertical?

O enquadramento segue o primeiro frame; para formato vertical, envie uma imagem de primeiro frame em formato vertical.

Qual é a diferença entre primeiro frame e imagem de referência?

O primeiro frame se torna literalmente o primeiro frame do vídeo; a imagem de referência apenas orienta o modelo quanto à aparência e ao estilo, e o enquadramento pode ser refeito.

Só tem prompt e nenhuma imagem? Veja API de texto para vídeo do Seedance 2.5. Quer mais formas de escrever o primeiro frame? Veja o Manual de uso do Seedance 2.5 ou vá direto para a página do modelo e envie uma imagem para testar.