시댄스 2.5 APISeedance 2.5 API · 시댄스 2.0 API

시댄스 2.5 API는 바이트댄스의 동영상 생성 모델 시댄스 2.5(Seedance 2.5)를 내 서비스·앱·자동화 워크플로에서 바로 호출할 수 있는 영상 생성 API입니다. 텍스트 프롬프트 한 줄이나 이미지 한 장으로 최대 30초 1080p 영상을 만들고, 참조 이미지·영상· 오디오를 섞은 레퍼런스 생성부터 기존 영상 편집과 연장까지 하나의 REST API로 처리합니다. 더 가볍고 빠른 시댄스 2.0 · 2.0 Fast API도 같은 API 키로 함께 쓸 수 있습니다.

시댄스 2.5 API 요금은 웹사이트와 같은 크레딧 단가이며, 원화(KRW)로 충전한 유료 크레딧에서 차감됩니다. 생성 전에 정확한 비용을 미리 조회할 수 있고, 생성에 실패한 작업은 크레딧이 자동으로 환불됩니다. 아래 시댄스 2.5 API 사용법의 예제 코드를 복사 버튼으로 그대로 가져가 API 키 발급부터 첫 영상 생성까지 몇 분 안에 연동해 보세요.

시댄스 2.5 API 사용법

Base URL: https://api.seedance25.kr/v1

1. 시댄스 2.5 API 키 발급과 인증

로그인 후 설정 → API 키에서 키를 만듭니다. 키는 생성할 때 한 번만 표시되니 안전한 곳에 보관하세요. 모든 요청에 Authorization: Bearer <API 키> 헤더를 보냅니다. 키는 서버에서만 사용하고 브라우저·앱 코드에 넣지 마세요.

2. 시댄스 2.5 API 요금과 크레딧

  • 요금은 웹사이트와 동일한 크레딧 단가입니다. 정확한 금액은 POST /v1/estimate로 미리 확인할 수 있습니다.
  • API는 유료 크레딧만 사용합니다. 구독 크레딧과 크레딧 패키지 구매분이 해당되며, 가입·출석·쿠폰 등 무료 크레딧은 웹사이트에서만 사용할 수 있습니다.
  • 크레딧은 작업이 실제로 시작될 때 차감되고, 생성에 실패하면 자동으로 환불됩니다 (유료 크레딧은 유료 크레딧으로 환불).
  • 남은 크레딧은 GET /v1/credits로 조회합니다. 크레딧 구매

3. 동영상 생성 요청

POST /v1/videos/generations — 작업을 만들고 즉시 status: "queued"로 응답합니다. Idempotency-Key 헤더를 보내면 네트워크 오류로 재시도해도 작업과 과금이 한 번만 발생합니다.

curl https://api.seedance25.kr/v1/videos/generations \
  -H "Authorization: Bearer $SEEDANCE25_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9b1e-order-1042" \
  -d '{
    "model": "seedance-2.5-text-to-video",
    "prompt": "비 오는 서울 밤거리를 걷는 사람, 시네마틱 트래킹 샷",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'
{
  "id": "gen_V1StGXR8_Z5jdHi6B-myT",
  "object": "video.generation",
  "model": "seedance-2.5-text-to-video",
  "status": "queued",
  "progress": 0,
  "credits": { "amount": 226, "status": "estimated" },
  "output": null,
  "error": null,
  "created_at": "2026-11-07T09:00:00.000Z"
}
파라미터설명
model필수. 아래 모델 목록의 id
prompt프롬프트 (이미지→영상 2.0은 선택)
duration초 단위 정수. 모델별 범위 참고 (영상 편집은 원본 길이)
resolution480p · 720p · 1080p · 4k (모델별), 기본 720p
aspect_ratio16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9 · adaptive
generate_audio오디오 생성 여부, 기본 true
web_searchSeedance 2.5 텍스트→영상 전용, 기본 false
output_formatSeedance 2.5 전용 mp4 · mov, 기본 mp4
extend_direction영상 연장 전용 forward · backward
image_files / video_files / audio_files/v1/files로 업로드한 파일 id 배열

4. 결과 조회

GET /v1/tasks/{id} — 상태는 queued → processing → succeeded 또는 failed입니다. 5~10초 간격으로 조회하세요. 결과 링크는 2시간 동안 유효하며, 다시 조회하면 새 링크를 받습니다. 생성된 파일은 직접 내려받아 보관하세요.

curl https://api.seedance25.kr/v1/tasks/gen_V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer $SEEDANCE25_API_KEY"
{
  "id": "gen_V1StGXR8_Z5jdHi6B-myT",
  "status": "succeeded",
  "progress": 100,
  "credits": { "amount": 226, "status": "charged" },
  "output": {
    "videos": [
      {
        "url": "https://seedance25.kr/api/storage/replicate-file/...",
        "url_expires_at": "2026-11-07T11:05:00.000Z",
        "content_type": "video/mp4",
        "width": 1280,
        "height": 720,
        "duration_ms": 5000
      }
    ]
  }
}

5. 참조 파일 업로드

이미지(JPG · PNG · WEBP, 30MB), 영상(MP4 · MOV, 50MB), 오디오(MP3 · WAV, 15MB)를 올리고 받은 id를 생성 요청에 넣습니다.

# 파일 직접 업로드 (multipart, 필드 이름: file)
curl https://api.seedance25.kr/v1/files \
  -H "Authorization: Bearer $SEEDANCE25_API_KEY" \
  -F "file=@first-frame.png"

# 또는 공개 URL 가져오기
curl https://api.seedance25.kr/v1/files \
  -H "Authorization: Bearer $SEEDANCE25_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/first-frame.png" }'

# 응답: { "id": "file_id", "object": "file", "content_type": "image/png", ... }
{
  "model": "seedance-2.5-image-to-video",
  "prompt": "카메라가 천천히 다가가며 인물이 미소 짓는다",
  "duration": 8,
  "resolution": "1080p",
  "image_files": ["<첫 프레임 file id>", "<마지막 프레임 file id (선택)>"]
}

6. 지원 모델: 시댄스 2.5 · 2.0

GET /v1/models는 키 없이 호출할 수 있으며 아래 정보를 JSON으로 돌려줍니다. 크레딧은 기본 길이 기준 예시입니다.

model길이(초)참조 파일예시 크레딧
seedance-2.5-text-to-video4–30없음480p 5초 116 · 720p 5초 226 · 1080p 5초 567
seedance-2.5-image-to-video4–30이미지 1–2480p 5초 116 · 720p 5초 226 · 1080p 5초 567
seedance-2.5-reference-to-video4–30이미지 0–30, 영상 0–10, 오디오 0–10480p 5초 116 · 720p 5초 226 · 1080p 5초 567
seedance-2.5-video-edit원본 길이이미지 0–30, 영상 1–10, 오디오 0–10원본 길이에 따라 계산
seedance-2.5-video-extend4–30이미지 0–30, 영상 1–10, 오디오 0–10원본 길이에 따라 계산
seedance-2.0-text-to-video4–15없음480p 5초 75 · 720p 5초 160 · 1080p 5초 400 · 4k 5초 810
seedance-2.0-image-to-video4–15이미지 1–2480p 5초 75 · 720p 5초 160 · 1080p 5초 400 · 4k 5초 810
seedance-2.0-fast-text-to-video4–15없음480p 5초 50 · 720p 5초 105
seedance-2.0-fast-image-to-video4–15이미지 1–2480p 5초 50 · 720p 5초 105

7. 오류와 제한

오류는 HTTP 상태 코드와 함께 { "error": { "code": "...", "message": "..." } } 형식으로 응답합니다. 계정당 동시 작업 5개, 분당 새 작업 20개까지 가능합니다. 더 높은 한도가 필요하면 문의하세요.

HTTPcode의미
401invalid_api_keyAPI 키가 없거나 잘못됨 / 비활성 / 만료
403account_suspended · email_not_verified · api_access_disabled계정 정지, 이메일 미인증, API 사용 제한
402insufficient_paid_credits유료 크레딧 부족 (details에 필요 / 보유 크레딧)
404task_not_found · file_not_found작업 또는 파일을 찾을 수 없음
409idempotency_conflict같은 Idempotency-Key로 다른 요청을 보냄
413 · 415file_too_large · unsupported_media_type파일 크기 초과, 지원하지 않는 형식
422invalid_request · unsupported_model파라미터 오류 (message에 원인)
429concurrency_limit_exceeded · rate_limit_exceeded동시 작업 5개 / 분당 20개 초과 (Retry-After 헤더 참고)
500internal_error일시적 서버 오류, 같은 Idempotency-Key로 재시도

8. Node.js 예제

const API = 'https://api.seedance25.kr/v1';
const headers = {
  Authorization: `Bearer ${process.env.SEEDANCE25_API_KEY}`,
  'Content-Type': 'application/json',
};

const task = await fetch(`${API}/videos/generations`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    model: 'seedance-2.0-text-to-video',
    prompt: '해변을 달리는 강아지, 슬로모션',
    duration: 5,
    resolution: '720p',
  }),
}).then((r) => r.json());

let result = task;
while (result.status === 'queued' || result.status === 'processing') {
  await new Promise((r) => setTimeout(r, 10_000));
  result = await fetch(`${API}/tasks/${task.id}`, { headers }).then((r) => r.json());
}
console.log(result.status, result.output?.videos[0]?.url);

9. 콘텐츠 정책

API 작업에도 웹사이트와 같은 콘텐츠 정책과 프롬프트 검사가 적용됩니다. 정책을 위반하면 작업이 실패 처리되고, 반복되는 경우 API 사용이 제한될 수 있습니다.