API de vídeo com referência Seedance 2.5: reaproveite o movimento de câmera do vídeo de referência e troque o sujeito

TL;DR

• seedance-2.5/reference-to-video usa um vídeo existente como referência, preserva seu movimento de câmera, ritmo e ações, e então troca o sujeito, troca o estilo visual ou adiciona uma música de referência. Abra a página do modelo para gerar online; novos usuários ganham 200 créditos ao se cadastrar.
• A cobrança é por segundo, e a duração do vídeo de referência também é cobrada: custo = preço unitário × (duração do vídeo de referência + duração da saída). 480p custa $0.1215 por segundo, 720p $0.2715, 1080p $0.68.
• 5 segundos de referência + 5 segundos de saída: 480p $1.215, 720p $2.715. Ajustar o prompt em 480p primeiro é o mais econômico.

Primeiro veja um resultado real: troca de sujeito mantendo o movimento de câmera

O vídeo de referência é um anúncio de tênis de corrida, e a imagem de referência é um frasco de perfume. O prompt faz o modelo seguir a sequência de planos e o movimento de câmera do anúncio de tênis e substituir o tênis inteiro pelo perfume:

Use @video1 strictly as the reference for shot progression, product rotation, camera paths, pacing, macro close-ups, and lighting transitions. Replace the shoe completely with the perfume bottle from @image1. Preserve the bottle's exact silhouette, amber glass color, cap proportions, label placement, and premium material appearance in every shot. Present it as a luxury fragrance commercial on a dark obsidian pedestal, with warm amber rim light, controlled reflections, fine atmospheric mist, and precise macro detail. Follow the visual rhythm and camera choreography of @video1 while keeping one consistent perfume bottle throughout. Do not transfer shoe laces, soles, fabric textures, or shoe-shaped geometry into the bottle. Do not invent extra products, readable brand text, logos, hands, or people.

Gerar com este prompt → (envie seu vídeo de referência e a imagem do produto, 480p, 9:16)

seedance-2.5/reference-to-video, 480p, 9:16, saída de 4 segundos, áudio gerado pelo modelo.

@video1 e @image1 são os números de referência dos materiais no prompt, correspondendo ao primeiro endereço em reference_video_urls e reference_image_urls na ordem em que foram enviados. A frase final "não traga cadarços nem solas para o frasco de perfume" é tão importante quanto a descrição positiva anterior: sem deixar isso claro, o modelo traz detalhes do vídeo de referência.

curl: o primeiro vídeo

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/reference-to-video",
    "input": {
      "prompt": "沿用 @video1 的运镜和节奏，把主体换成 @image1 里的产品，光线和构图保持一致",
      "reference_video_urls": ["https://your-cdn.example.com/reference-clip.mp4"],
      "reference_image_urls": ["https://your-cdn.example.com/product.jpg"],
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "9:16"
    }
  }'

Se o vídeo de referência tiver 5 segundos, esta chamada é cobrada como 10 segundos em 480p, $1.215.

Retorna taskId, depois 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.

Python: enviar, consultar e baixar

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

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

def generate(prompt, model="seedance-2.5/reference-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    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(
    "保留 @video1 里柯基奔跑的节奏和低机位跟拍，把整个画面改成毛毡定格动画风格",
    reference_video_urls=["https://your-cdn.example.com/corgi-run.mp4"],
    duration=5, resolution="480p", aspect_ratio="16:9",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Três usos comuns

1. Trocar o sujeito mantendo o movimento de câmera (o exemplo do perfume acima): vídeo de referência + imagem de referência. No prompt, deixe claro "o que pegar de @video1", "o que pegar de @image1" e "o que não trazer".

2. Migrar apenas a ação, trocando todo o estilo visual: envie apenas o vídeo de referência. O exemplo abaixo transforma uma filmagem real de um corgi correndo em animação stop-motion de feltro, mantendo o ritmo da corrida e o movimento de câmera de acompanhamento:

Use @video1 as the sole visual reference. Preserve the corgi's recognizable markings, running cadence, stride timing, body orientation, forward momentum, and the low side-tracking camera movement. Reimagine the entire scene as a handcrafted stop-motion film made from felt, wool, miniature grass, and painted paper scenery. Keep the warm sunset backlight and continuous chase rhythm, with subtle handmade texture and natural depth of field. Maintain one coherent corgi throughout the shot, anatomically stable legs, smooth forward motion, and a continuous camera path. Do not introduce additional animals, text, logos, abrupt cuts, or unrelated objects.

Gerar com este prompt → (envie seu vídeo de referência)

seedance-2.5/reference-to-video, 480p, apenas vídeo de referência, saída de 4 segundos.

3. Usar vídeo + imagem + áudio juntos: adicione também reference_audio_urls e use @audio1 no prompt para especificar qual imagem cai em qual ponto da música; isso é muito mais preciso do que escrever apenas "trilha sonora". O áudio de referência deve ser enviado junto com o vídeo de referência.

Visão geral dos parâmetros

Parâmetro	Valores	Descrição
prompt	String, obrigatório	Use @video1 @image1 @audio1 para referenciar materiais
reference_video_urls	Obrigatório, 1–10 trechos	MP4/MOV, cada trecho de 2–30 segundos, total não superior a 30 segundos, cada trecho menor que 200 MB
reference_image_urls	Até 30 imagens	JPEG/PNG/WebP etc., cada uma menor que 30 MB
reference_audio_urls	Até 10 trechos	WAV/MP3, deve ser usado junto com o vídeo de referência
duration	Inteiro de 4–30, ou -1 para o modelo decidir, padrão 5	Unidade: segundos
resolution	480p / 720p / 1080p, padrão 480p
aspect_ratio	16:9 4:3 1:1 3:4 9:16 21:9 adaptive	Para vertical, use 9:16
generate_audio	Padrão true

Calcule o custo

Segundos cobrados = duração total do vídeo de referência + duração da saída. Imagem de referência e áudio de referência não são cobrados à parte.

Referência + saída	480p ($0.1215/segundo)	720p ($0.2715/segundo)	1080p ($0.68/segundo)
5 segundos + 4 segundos	$1.0935	$2.4435	$6.12
5 segundos + 5 segundos	$1.215	$2.715	$6.8
10 segundos + 10 segundos	$2.43	$5.43	$13.6

Dica para economizar: corte o vídeo de referência deixando apenas o trecho de ação necessário, ajuste o prompt em 480p e, após finalizar, gere em 720p ou 1080p. Para uma conta mais detalhada, veja Preços da API Seedance 2.5.

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

• Os endereços dos materiais devem ser publicamente acessíveis: o vídeo de referência deve usar um endereço HTTPS publicamente acessível.
• 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 imediatamente: output[0].url é um link temporário; assim que obtiver, armazene no seu próprio storage.
• Retentativas com chave de idempotência: adicione Idempotency-Key no cabeçalho da requisição; a mesma chave em retentativas cria a tarefa apenas uma vez.
• Reembolso automático em caso de falha: apenas vídeos gerados com sucesso são cobrados.

Perguntas frequentes

Sem vídeo de referência, dá para usar apenas uma imagem de referência?

Não, reference_video_urls é obrigatório. Se você tiver apenas imagens, use o modo de imagem de referência do Seedance 2.5 imagem para vídeo.

Por que a cobrança foi maior do que calculei?

A duração do vídeo de referência também é cobrada. 10 segundos de vídeo de referência + 5 segundos de saída são cobrados como 15 segundos.

Dá para gerar direto em vertical?

Sim, defina aspect_ratio como 9:16; o modelo gera diretamente em vertical, não é um corte posterior.

Quanto mais materiais de referência, mais caro fica?

Imagem de referência e áudio de referência não custam a mais; apenas o vídeo de referência é cobrado pela duração.

Se você não tem materiais de referência e quer gerar apenas com um texto, veja API Seedance 2.5 texto para vídeo. Para testar um primeiro vídeo, vá à página do modelo e envie seu vídeo de referência.