Seedance 2.5 이미지-투-비디오 API: 첫 프레임, 첫/마지막 프레임, 참조 이미지를 전달하는 방법

TL;DR

• seedance-2.5/image-to-video는 이미지 한 장을 움직이게 하며, 첫 프레임과 마지막 프레임을 동시에 주고 모델이 중간 과정을 채우게 할 수도 있습니다. 한 편당 4–30초, 사운드 내장. 모델 페이지 열기에서 온라인으로 생성할 수 있고, 신규 가입 시 200 크레딧을 증정합니다.
• 텍스트-투-비디오와 동일한 가격: 720p 초당 $0.204, 1080p 초당 $0.516. 4초 720p는 $0.816입니다.
• 두 가지 사용법 중 하나를 선택: 첫 프레임 / 첫·마지막 프레임, 또는 참조 이미지 + 참조 오디오. 혼용할 수 없습니다.

먼저 실제 결과 하나 보기: 첫·마지막 프레임

「빈 화분」을 첫 프레임으로, 「바질이 가득 자란 화분」을 마지막 프레임으로 주고, 프롬프트에는 중간에 어떻게 변하는지만 작성합니다:

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

이 프롬프트로 생성 →(첫 프레임과 마지막 프레임 업로드, 4초, 720p)

seedance-2.5/image-to-video, 첫 프레임 + 마지막 프레임, 720p, 4초, 사운드 포함, $0.816.

첫·마지막 두 이미지의 구도, 조명, 소품 위치를 일관되게 유지하고 영상에서 표현하고 싶은 것(여기서는 식물)만 바꿔야 중간 전환이 자연스럽습니다. 프롬프트의 "soft morning light staying consistent"는 모델이 조명까지 타임랩스로 만들지 않도록 하기 위한 것입니다.

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/image-to-video",
    "input": {
      "prompt": "镜头缓慢推向冒着热气的咖啡杯，热气在晨光中旋转上升，轻微手持晃动",
      "first_frame_url": "https://your-cdn.example.com/coffee-cup.jpg",
      "duration": 5,
      "resolution": "720p"
    }
  }'

taskId 반환:

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

결과 조회:

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

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

첫·마지막 프레임: last_frame_url 하나 더 추가

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "同一张书桌从白天到夜晚的延时：日光渐渐变暗，台灯亮起暖光，窗外的城市灯光逐一亮起，镜头固定不动",
    "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은 first_frame_url과 함께 사용해야 합니다.
• 마지막 프레임과 첫 프레임의 비율이 다르면 마지막 프레임은 중앙 크롭되므로, 두 이미지 모두 같은 비율로 생성하는 것이 좋습니다.
• 화면 비율은 첫 프레임을 따르며, aspect_ratio는 adaptive 값 하나뿐이라 전달할 필요가 없습니다.

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/image-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(
    "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)

또 다른 사용법: 참조 이미지 + 참조 오디오

특정 이미지를 첫 프레임으로 고정하지 않고 모델이 인물의 외모, 제품 외관 또는 화풍을 「참조」하길 원한다면 reference_image_urls(최대 30장)를 사용하고, reference_audio_urls(최대 10개)로 사운드 스타일을 참조할 수도 있습니다:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "参考图里的女孩背着同款蓝色书包，走过下雨的街角，镜头跟随",
    "reference_image_urls": [
      "https://your-cdn.example.com/girl.jpg",
      "https://your-cdn.example.com/backpack.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }
}

주의: 참조 이미지, 참조 오디오는 first_frame_url / last_frame_url과 동시에 전달할 수 없으며, 둘 중 하나를 선택해야 합니다.

파라미터一览

파라미터	값	설명
prompt	문자열, 필수	동작, 카메라, 사운드를 작성하며 전체 이미지를 다시 설명할 필요 없음
first_frame_url	이미지 URL	첫 프레임
last_frame_url	이미지 URL	마지막 프레임, 첫 프레임과 함께 사용
reference_image_urls	최대 30장	첫·마지막 프레임과 동시에 사용할 수 없음
reference_audio_urls	최대 10개	첫·마지막 프레임과 동시에 사용할 수 없음
duration	4–30 정수, 기본값 5	단위 초
resolution	720p / 1080p, 기본값 720p
generate_audio	기본값 true	사운드와 화면을 함께 생성
output_format	mp4 / mov

비용 계산

길이	720p($0.204/초)	1080p($0.516/초)
4초	$0.816	$2.064
5초	$1.02	$2.58
10초	$2.04	$5.16
15초	$3.06	$7.74

첫·마지막 프레임과 단일 첫 프레임은 같은 가격이며, 비용은 해상도와 초 수에만 따라 달라집니다. 더 자세한 계산은 Seedance 2.5 API 가격을 참고하세요.

출시 전 주의 사항

• 이미지 주소는 공개 접근 가능해야 함: HTTP(S) 주소 또는 data URL 모두 가능하며, 내부망 주소는 모델이 가져올 수 없습니다.
• 폴링 대신 콜백 사용: 요청 최상위에 "callback": {"url": "https://你的域名/hiapi/callback"}를 추가하고 taskId로 중복 제거하세요.
• 즉시 저장: output[0].url은 임시 링크이므로 받은 즉시 자체 스토리지에 저장하세요.
• 재시도 시 멱등 키 포함: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 재시도해도 작업이 한 번만 생성됩니다.
• 실패 시 자동 환불: 성공적으로 생성된 영상에 대해서만 과금됩니다.

자주 묻는 질문

첫·마지막 프레임 중간에 「디졸브」가 나타나면 어떻게 하나요?

두 이미지 차이가 너무 크면 중간 1~2초가 두 이미지가 겹치는 디졸브처럼 보이기 쉽습니다. 두 이미지의 구도와 소품을 일관되게 유지하고 주체만 바꾼 뒤, 프롬프트에 "camera locked off, no cuts"를 작성하세요.

마지막 프레임만 줄 수 있나요?

아니요, 마지막 프레임은 첫 프레임과 함께 사용해야 합니다.

세로 화면을 지정할 수 있나요?

화면 비율은 첫 프레임을 따르므로, 세로 화면을 원하면 세로 첫 프레임 이미지를 업로드하세요.

첫 프레임과 참조 이미지의 차이는 무엇인가요?

첫 프레임은 그대로 영상의 첫 프레임이 됩니다; 참조 이미지는 모델이 외관과 스타일을 참고하게 할 뿐이며, 화면은 다시 구도화될 수 있습니다.

프롬프트만 있고 이미지가 없나요? Seedance 2.5 텍스트-투-비디오 API를 참고하세요. 더 많은 첫 프레임 작성법을 원하면 Seedance 2.5 사용 설명서를 보거나, 바로 모델 페이지에서 이미지 한 장을 업로드해 시험해 보세요.