ByteDance

Seedance 2.5

seedance-2.5/reference-to-video

바이트 Seed의 오디오-비디오 통합 생성 모델로, 최대 30초, 최고 4K의 연속 클립을 지원하며 멀티모달 레퍼런스와 타임스탬프 수준 편집을 기반으로 화면을 정밀하게 제어할 수 있습니다

seedance-2.5/image-to-video seedance-2.5/reference-to-video seedance-2.5/text-to-video

seedance-2.5/reference-to-video 사용해 보기

입력

작품 갤러리

모든 작품 보기

출력

video

파라미터를 입력하고 생성하면 결과가 여기에 표시됩니다.

가격

seedance-2.5/reference-to-video per second

사양	단가
480P	$0.1215
720P	$0.2715
1080P	$0.680

포지셔닝 소개

Seedance 2.5의 참조 기반 비디오 생성 라인으로, 소재를 통해 화면 일관성을 제약해야 하는 비디오 생성 작업을 위한 것입니다. 개발자는 프롬프트와 최소 한 개의 참조 비디오를 제출하고, 이미지와 오디오 참조를 동시에 추가할 수 있으며, 모델이 @image1, @video1, @audio1 순서로 소재를 참조해 4~30초, 480p~1080p의 완성 영상을 생성합니다. 광고, 숏드라마, 브랜드 콘텐츠 팀이 시리즈 창작에서 캐릭터, 제품, 장면 외형을 고정하는 데 적합하며, 음향 효과와 대사를 동기화해야 하는 내러티브 클립 제작에도 적합합니다.

핵심 하이라이트

멀티모달 소재가 함께 화면을 제약——최대 30장의 이미지, 10개의 비디오, 10개의 오디오를 동시에 참조로 지원하여 제품, 캐릭터, 장면 외형을 고정합니다.
프롬프트에서 소재를 순서대로 참조——prompt에서 @image1, @video1, @audio1 순서로 참조 항목을 지칭하여 소재와 화면 목표를 명확히 대응시킵니다.
길이와 화면비 제어 가능——출력 길이는 4~30초 중 선택하거나 모델이 자동으로 결정하게 할 수 있으며, 화면비는 16:9, 9:16부터 21:9 및 소재를 따르는 자동 적응을 지원합니다.
영상과 음향 동시 생성——기본적으로 화면과 동기화된 대사, 음향 효과, 배경 오디오를 생성하며, 끄면 순수 화면 출력을 얻을 수 있습니다.

기능 설명

참조 비디오 기반 생성: 최소 한 개의 참조 비디오를 입력하면 모델이 이를 바탕으로 새 클립을 생성하며, 원본을 연장하거나 편집하지 않습니다. 기존 촬영 기법과 화면 질감을 재사용해야 하는 제작에 적합합니다.

이미지와 비디오 혼합 참조: 이미지 최대 30장, 비디오 최대 10개를 조합해 제출할 수 있으며, 캐릭터, 제품, 장면을 각각 제약해 시리즈 콘텐츠의 외형 변동을 줄입니다.

오디오 참조 및 오디오 생성: 최대 10개의 wav 또는 mp3 오디오 참조를 추가할 수 있으며(최소 한 개의 참조 비디오와 함께 제출해야 함), 동기화된 대사, 음향 효과, 배경음 생성 여부를 선택할 수 있습니다.

해상도 및 출력 형식 옵션: 출력은 480p, 720p, 1080p 세 단계를 지원하며, 형식은 mp4 또는 전문 후반 작업용 mov를 선택할 수 있고, 출력 초 단위로 과금됩니다.

웹 검색으로 정보 보충: web_search를 켜면 모델이 생성 전에 프롬프트에 포함된 시의성 정보를 검색하게 할 수 있으며, 현재 사실을 인용해야 하는 콘텐츠에 적합합니다.

적용 시나리오

광고 및 브랜드 팀의 제품 단편 제작——제품 이미지와 실사 참조 비디오로 외형을 제약해 4~30초의 광고 클립을 생성하고, 광고 소재와 소셜 미디어 배포에 활용합니다.
숏드라마 팀의 캐릭터 일관성 유지——캐릭터 이미지와 기존 클립을 참조로 삼아 같은 캐릭터의 연속 장면을 대량 생성하고, 콘티 조립 후 편집에 사용합니다.
후반 팀의 촬영안 사전 시뮬레이션——장면 참조 비디오와 구도 이미지를 제출해 완성 영상에 가까운 질감의 프리뷰 클립을 빠르게 얻고, 고객 확인과 촬영 전 커뮤니케이션에 활용합니다.
콘텐츠 팀의 영상·음향 동기화 클립 제작——더빙이나 음악 참조를 제공하고 오디오 생성을 켜서 동기화된 대사와 음향 효과가 포함된 완성 영상을 제작하고, 완성본이나 추가 믹싱에 바로 사용합니다.

제한 사항 및 선택 가이드

한 번에 생성하는 클립은 최대 30초이며, 더 긴 내러티브는 여러 클립으로 나누어 생성한 뒤 이어 붙여야 합니다. 참조 소재에는 명확한 제약이 있습니다. 비디오는 2~30초이고 총 길이가 30초를 넘지 않아야 하며, 오디오 총 길이도 30초를 넘지 않아야 하고, 단일 파일 크기와 픽셀 수에도 하한과 상한이 있어 소재가 규정에 맞지 않으면 바로 실패합니다. 이 라인은 참조로 유도하는 생성에 사용되며 비디오 편집이나 원본 연장은 지원하지 않습니다. 다중 소재 참조는 프롬프트 작성과 파라미터 조정 비용이 더 높다는 의미이기도 합니다. 가볍고 단일 장면이며 일관성 요구가 없는 니즈에는 같은 시리즈의 텍스트-투-비디오 라인을 고려할 수 있습니다.

자주 묻는 질문

모든 질문 보기 →

Seedance 2.5 이미지-투-비디오는 첫 프레임과 마지막 프레임을 모두 업로드해야 하나요?

아니요. 첫 프레임/첫-마지막 프레임 모드에서 first_frame_url만 업로드하면 모델이 첫 프레임부터 이후 화면을 자연스럽게 확장합니다. 샷의 종료 상태를 제어해야 할 때만 last_frame_url을 함께 제공하면 됩니다. 마지막 프레임은 단독으로 사용할 수 없습니다. 또는 엔드포인트 프레임을 전달하지 않고 reference_image_urls 또는 reference_audio_urls를 참조 모드로 사용할 수도 있습니다.
첫 프레임, 첫/마지막 프레임과 다중 참조 소재를 한 번의 요청에 함께 넣을 수 있나요?

현재 HiAPI Playground는 이를 두 가지 입력 방식으로 처리합니다: 첫 프레임/첫·마지막 프레임 모드, 또는 reference_image_urls, reference_audio_urls 참조 모드입니다. 제어 신호가 서로 충돌하지 않도록 매번 한 가지 방식만 유지하세요. 참조 영상으로 동작이나 카메라 무빙을 안내해야 할 때는 별도의 seedance-2.5/reference-to-video를 사용하세요.
Seedance 2.5 이미지→비디오는 어떤 길이와 해상도를 지원하나요?

현재 요청 계약은 4–30초의 정수 길이와 720p, 1080p를 지원합니다. 출력 aspect_ratio는 adaptive로 고정되며, 첫 프레임의 화면 비율을 따릅니다. 페이지의 네 가지 사례는 모두 720p이며, 그중 세 개는 4초, 하나는 5초입니다. 30초는 API 지원 범위에 속하지만 페이지에는 해당 사례가 아직 없습니다.
Seedance 2.5 이미지 투 비디오는 어떻게 과금되나요?

출력 길이와 해상도에 따라 과금되며, 720p와 1080p는 서로 다른 초당 요금 구간을 사용합니다. 구체적인 금액은 모델 페이지의 실시간 가격과 작업 기록을 기준으로 합니다.

생성 작업 제출

POST https://api.hiapi.ai/v1/tasks

헤더

Authorizationstring필수

계정 API 키. 모든 요청에 필수입니다. 예: Bearer YOUR_HIAPI_API_KEY. API 키 받기

Content-Typestring선택

요청 본문은 항상 JSON으로 파싱됩니다. 전송 시 application/json(charset 포함 가능)만 허용되며, 다른 값은 415를 반환합니다. 예: application/json.

Idempotency-Keystring선택

멱등 키. 최대 255바이트. 같은 계정에서 같은 키의 재시도는 태스크를 한 번만 생성하며, 재전송 시 최초의 taskId를 반환합니다.

멱등 키

네트워크 타임아웃이나 클라이언트 자동 재시도 시 같은 키로는 태스크를 한 번만 생성하고 이중 과금되지 않습니다(범위 = API 키의 계정). 업무 고유 식별자(예: "order-42")를 키로 사용할 것을 권장합니다. 같은 키 재전송 시 최초 taskId를 반환하며, 키는 첫 제출 후 24시간 뒤 만료됩니다. 자세한 시나리오 표는 통합 비동기 API 소개 페이지를 참고하세요.

본문

modelstring필수

현재 고정 값: seedance-2.5/reference-to-video

routestring선택

현재 고정 값: default

inputobject필수

seedance-2.5/reference-to-video 및 루트 default의 비즈니스 파라미터 객체. 아래 파라미터 표를 참조하세요.

promptstring필수

생성 지시문으로, 참조 소재를 어떻게 사용할지 설명합니다. 참조 항목은 순서대로 @image1, @video1, @audio1 형식으로 인용합니다. 이 모델은 참조 기반 생성을 위한 것으로, 영상 편집이나 이어쓰기는 지원하지 않습니다.

durationinteger선택기본값: 5

출력 영상 길이(초)입니다. -1을 전달하면 자동 길이를 의미하며, 4에서 30 사이의 정수를 전달할 수 있습니다. 기본값 5입니다.

옵션:-145678910

전체 보기(20개)

1112131415161718192021222324252627282930

resolutionstring선택기본값: "480p"

출력 영상 해상도이며 480p, 720p, 1080p를 지원합니다. 기본값 480p입니다.

옵션:480p720p1080p

web_searchboolean선택기본값: false

모델이 프롬프트에 언급된 실시간 정보를 인터넷에서 검색할 수 있는지 여부입니다. 기본값 false입니다.

aspect_ratiostring선택기본값: "adaptive"

출력 화면 가로세로 비율이며, adaptive는 모델이 참조 소재의 비율을 따르는 것을 의미합니다. 기본값 adaptive입니다.

옵션:16:94:31:13:49:1621:9adaptive

output_formatstring선택기본값: "mp4"

출력 영상 컨테이너 형식이며, mp4는 호환성이 더 좋은 기본 형식이고 mov는 전문 후반 작업을 위한 형식입니다. 기본값 mp4입니다.

옵션:mp4mov

generate_audioboolean선택기본값: true

대사, 음향 효과, 배경 오디오를 동시에 생성할지 여부입니다. 기본값 true입니다.

reference_audio_urlsarray선택maxItems 10

참조 오디오 URL 배열로, 최대 10개까지 가능합니다. 각 오디오는 wav 또는 mp3여야 하고, 크기는 15 MB를 초과할 수 없으며, 길이는 2~30초이고, 누적 오디오 길이는 30초를 초과할 수 없습니다. 참조 오디오를 제공할 때는 최소 하나의 참조 영상도 함께 제공해야 합니다.

Array [ string ]

reference_image_urlsarray선택maxItems 30

참조 이미지 URL 배열로, 최대 30장까지 가능합니다. jpeg, png, webp, bmp, tiff, gif를 지원하며, 단일 이미지는 30 MB를 초과할 수 없고, 각 변은 300~6000픽셀이어야 하며, 가로세로 비율은 0.4~2.5여야 합니다. SVG, HEIC, HEIF는 지원하지 않습니다.

Array [ string ]

reference_video_urlsarray필수minItems 1maxItems 10

참조 영상 URL 배열로, 최대 10개까지 가능합니다. 각 영상은 mp4 또는 mov여야 하고, 총 픽셀 수는 409600 이상(예: 854x480 이상), 프레임 레이트는 24~60 fps, 크기는 200 MB를 초과할 수 없으며, 길이는 2~30초, 각 변은 300~6000픽셀, 가로세로 비율은 0.4~2.5여야 하고, 누적 영상 길이는 30초를 초과할 수 없습니다.

Array [ string ]

callbackobject선택

종료 상태 알림 설정. 생략하면 콜백이 전송되지 않으며 호출 측에서 폴링합니다.

콜백(Webhook)

생성 시 callback.url을 지정하면 태스크 종료 시 HiAPI가 서비스로 POST하여 폴링이 필요 없습니다. 콜백 본문은 태스크 상세와 동일한 구조입니다. 서명 검증·재시도·멱등에 대한 자세한 내용은 통합 비동기 API 소개 페이지의 콜백 설명을 참고하세요.

urlstring필수

callback 사용 시 필수. 태스크 종료 후 이 URL로 POST됩니다. 유효한 http(s) URL이어야 합니다.

whenstring선택기본값: "final"

현재는 final만 지원(success / fail 모두 알림).

옵션:final

storagestring선택기본값: "temp"

산출물 저장 등급: temp(기본·약 7일) 또는 persistent(장기 보관·용량 과금). 잔액 부족이나 저장 한도 초과 시 자동으로 temp로 강등됩니다. 실제 적용된 등급은 태스크 상세 응답에서 확인할 수 있습니다.

옵션:temppersistent

요청 예시

# 비동기 태스크 제출. 성공 시 즉시 taskId 반환(생성 완료 대기 없음)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "resolution": "480p",
    "web_search": false,
    "aspect_ratio": "adaptive",
    "output_format": "mp4",
    "generate_audio": true,
    "reference_video_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.5/reference-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "resolution": "480p",
      "web_search": false,
      "aspect_ratio": "adaptive",
      "output_format": "mp4",
      "generate_audio": true,
      "reference_video_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "seedance-2.5/reference-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "resolution": "480p",
          "web_search": False,
          "aspect_ratio": "adaptive",
          "output_format": "mp4",
          "generate_audio": True,
          "reference_video_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

작업 상세 조회

GET https://api.hiapi.ai/v1/tasks/:id

응답 필드

taskIdstring필수

태스크 ID. 접두사는 항상 tk-hiapi-.

modelstring필수

확인된 전체 모델명. route 파라미터로 제출한 태스크는 base@route(예: gpt-image-2/text-to-image@ext)를 반환하며, 그 외에는 제출 시의 모델명과 동일합니다.

routestring선택

route 파라미터를 명시해 제출한 태스크에만 나타나며, 제출한 값을 그대로 반환합니다.

statusstring필수

태스크 상태.

상태 값

queued 대기 중, 아직 시작되지 않음. handling 처리 중. archiving 처리 완료, 산출물 준비 중. success 종료: 완료. 산출물 사용 가능(output 반환). fail 종료: 실패(error 반환). 제출 후 status로 판단합니다: success와 fail이 종료 상태이며 나머지는 비종료입니다. 1~3초 간격으로 종료까지 폴링하세요. 성공 시 output[].url에서 산출물을 다운로드하고 expireAt 전에 옮기세요. 장기 보관이 필요하면 생성 시 storage: "persistent"를 사용하세요.

creatednumber필수

태스크 생성 시각(Unix 초).

completednumber필수

종료 상태가 된 Unix 초. 비종료 상태에서는 0.

outputarray선택

status == success일 때만 나타납니다. 산출물 목록 — 항상 배열이며, 하나의 태스크에서 여러 type을 동시에 반환할 수 있습니다(예: video + first_frame).

Array [ object ]

배열 항목

urlstring필수

산출물 URL. 바로 다운로드할 수 있습니다.

typestring필수

현재 가능한 값: video, image, audio, first_frame, last_frame, thumbnail. 이후 확장될 수 있습니다.

expireAtnumber필수

산출물 접근 가능 기한(Unix 초). 만료 전에 다운로드하거나 이전하세요.

errorobject선택

status == fail일 때만 나타납니다.

codestring필수

비즈니스 오류 코드.

messagestring필수

오류 설명.

응답 예시

성공

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

처리 중(비종료)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

실패

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}