Seedance 2.5 레퍼런스 투 비디오 API: 참고 영상의 카메라 무빙을 그대로 살리고 피사체만 교체하기

TL;DR

• seedance-2.5/reference-to-video는 기존 영상 하나를 참고 소재로 삼아 카메라 무빙, 리듬, 동작을 유지한 채 피사체를 바꾸거나 화풍을 바꾸거나 참고 음악을 입힙니다. 모델 페이지 열기에서 바로 온라인 생성할 수 있고, 신규 가입 시 200 크레딧을 드립니다.
• 초 단위로 과금되며 참고 영상의 길이도 비용에 포함됩니다: 비용 = 단가 × (참고 영상 길이 + 출력 길이). 480p는 초당 $0.1215, 720p는 $0.2715, 1080p는 $0.68입니다.
• 5초 참고 + 5초 출력: 480p $1.215, 720p $2.715. 프롬프트는 480p로 먼저 조정하는 게 가장 저렴합니다.

먼저 실제 결과 하나: 피사체 교체, 카메라 무빙 유지

참고 영상은 러닝화 광고, 참고 이미지는 향수 한 병입니다. 프롬프트로 모델이 러닝화 광고의 샷 순서와 카메라 무빙을 그대로 따르면서 신발을 통째로 향수로 바꾸게 합니다:

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.

이 프롬프트로 생성하기 →(참고 영상과 제품 이미지를 업로드, 480p, 9:16)

seedance-2.5/reference-to-video, 480p, 9:16, 4초 출력, 사운드는 모델이 생성.

@video1, @image1은 프롬프트 안의 소재 번호로, 전달 순서에 따라 reference_video_urls, reference_image_urls의 첫 번째 주소에 대응합니다. 마지막 문장 「신발 끈, 신발 밑창을 향수병에 가져오지 말 것」은 앞의 긍정적 묘지만큼 중요합니다. 명시하지 않으면 모델이 참고 영상의 디테일을 끌어옵니다.

curl: 첫 영상

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"
    }
  }'

참고 영상이 5초라면 이 요청은 480p 기준 10초로 과금되어 $1.215입니다.

taskId가 반환되면 결과를 조회합니다:

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

status가 success가 되면 output[0].url에서 영상을 다운로드합니다.

Python: 제출, 폴링, 다운로드

# 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)

세 가지 대표 사용법

1. 피사체 교체, 카메라 무빙 유지(위의 향수 예시): 참고 영상 + 참고 이미지. 프롬프트에 「@video1에서 무엇을 가져올지」「@image1에서 무엇을 가져올지」「무엇을 가져오지 말지」를 분명히 적습니다.

2. 동작만 이전, 화풍은 전면 교체: 참고 영상만 전달합니다. 아래 예시는 코기가 달리는 실사 영상을 펠트 스톱모션 애니메이션으로 바꾸면서 달리는 리듬과 트래킹 카메라 무빙은 유지합니다:

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.

이 프롬프트로 생성하기 →(참고 영상을 업로드)

seedance-2.5/reference-to-video, 480p, 참고 영상만 사용, 4초 출력.

3. 영상 + 이미지 + 오디오 함께 사용: reference_audio_urls를 더하고, 프롬프트에서 @audio1로 어느 장면이 음악의 어느 지점에 맞춰지는지 지정하면 「배경 음악」이라고만 쓰는 것보다 훨씬 정확합니다. 참고 오디오는 반드시 참고 영상과 함께 전달해야 합니다.

파라미터 한눈에 보기

파라미터	값	설명
prompt	문자열, 필수	@video1 @image1 @audio1로 소재 참조
reference_video_urls	필수, 1–10개	MP4/MOV, 각 2–30초, 합계 30초 이하, 각 200 MB 미만
reference_image_urls	최대 30장	JPEG/PNG/WebP 등, 장당 30 MB 미만
reference_audio_urls	최대 10개	WAV/MP3, 참고 영상과 함께 사용해야 함
duration	4–30의 정수, 또는 -1이면 모델이 결정, 기본값 5	단위 초
resolution	480p / 720p / 1080p, 기본값 480p
aspect_ratio	16:9 4:3 1:1 3:4 9:16 21:9 adaptive	세로 화면은 그대로 9:16으로 지정
generate_audio	기본값 true

비용 계산하기

과금 초수 = 참고 영상 총 길이 + 출력 길이. 참고 이미지와 참고 오디오는 추가 요금이 없습니다.

참고 + 출력	480p($0.1215/초)	720p($0.2715/초)	1080p($0.68/초)
5초 + 4초	$1.0935	$2.4435	$6.12
5초 + 5초	$1.215	$2.715	$6.8
10초 + 10초	$2.43	$5.43	$13.6

비용을 아끼는 방법: 참고 영상을 필요한 동작 구간만 남기고 잘라낸 뒤, 480p로 프롬프트를 조정하고 확정된 후 720p 또는 1080p로 출력하세요. 더 자세한 계산은 Seedance 2.5 API 가격을 참고하세요.

출시 전 유의사항

• 소재 주소는 공개 접근 가능해야 함: 참고 영상은 공개 접근 가능한 HTTPS 주소를 사용해야 합니다.
• 폴링 대신 콜백 사용: 요청 최상위에 "callback": {"url": "https://당신의 도메인/hiapi/callback"}를 추가하고, taskId로 중복을 제거하세요.
• 즉시 이전 저장: output[0].url은 임시 링크이므로 받은 즉시 자신의 스토리지에 저장하세요.
• 재시도에는 멱등 키를: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 재시도해도 작업이 한 번만 생성됩니다.
• 실패 시 자동 환불: 성공적으로 생성된 영상에만 과금됩니다.

자주 묻는 질문

참고 영상 없이 참고 이미지만으로 사용할 수 있나요?

아니요, reference_video_urls는 필수입니다. 이미지만 있다면 Seedance 2.5 이미지 투 비디오의 참고 이미지 모드를 사용하세요.

왜 계산한 것보다 과금이 더 많이 나오나요?

참고 영상의 길이도 과금됩니다. 10초 참고 영상 + 5초 출력이라면 15초로 계산됩니다.

바로 세로 화면으로 출력할 수 있나요?

가능합니다. aspect_ratio에 9:16을 지정하면 모델이 세로 화면으로 직접 생성하며, 사후 크롭이 아닙니다.

참고 소재가 많을수록 더 비싼가요?

참고 이미지와 참고 오디오는 추가 요금이 없고, 참고 영상만 길이에 따라 과금됩니다.

참고 소재 없이 텍스트만으로 영상을 만들려면 Seedance 2.5 텍스트 투 비디오 API를 참고하세요. 먼저 하나 시험해 보려면 모델 페이지에서 참고 영상 업로드하기.