시댄스 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/v11. 시댄스 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 | 초 단위 정수. 모델별 범위 참고 (영상 편집은 원본 길이) |
| resolution | 480p · 720p · 1080p · 4k (모델별), 기본 720p |
| aspect_ratio | 16:9 · 9:16 · 1:1 · 4:3 · 3:4 · 21:9 · adaptive |
| generate_audio | 오디오 생성 여부, 기본 true |
| web_search | Seedance 2.5 텍스트→영상 전용, 기본 false |
| output_format | Seedance 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-video | 4–30 | 없음 | 480p 5초 116 · 720p 5초 226 · 1080p 5초 567 |
| seedance-2.5-image-to-video | 4–30 | 이미지 1–2 | 480p 5초 116 · 720p 5초 226 · 1080p 5초 567 |
| seedance-2.5-reference-to-video | 4–30 | 이미지 0–30, 영상 0–10, 오디오 0–10 | 480p 5초 116 · 720p 5초 226 · 1080p 5초 567 |
| seedance-2.5-video-edit | 원본 길이 | 이미지 0–30, 영상 1–10, 오디오 0–10 | 원본 길이에 따라 계산 |
| seedance-2.5-video-extend | 4–30 | 이미지 0–30, 영상 1–10, 오디오 0–10 | 원본 길이에 따라 계산 |
| seedance-2.0-text-to-video | 4–15 | 없음 | 480p 5초 75 · 720p 5초 160 · 1080p 5초 400 · 4k 5초 810 |
| seedance-2.0-image-to-video | 4–15 | 이미지 1–2 | 480p 5초 75 · 720p 5초 160 · 1080p 5초 400 · 4k 5초 810 |
| seedance-2.0-fast-text-to-video | 4–15 | 없음 | 480p 5초 50 · 720p 5초 105 |
| seedance-2.0-fast-image-to-video | 4–15 | 이미지 1–2 | 480p 5초 50 · 720p 5초 105 |
7. 오류와 제한
오류는 HTTP 상태 코드와 함께 { "error": { "code": "...", "message": "..." } } 형식으로 응답합니다. 계정당 동시 작업 5개, 분당 새 작업 20개까지 가능합니다. 더 높은 한도가 필요하면 문의하세요.
| HTTP | code | 의미 |
|---|---|---|
| 401 | invalid_api_key | API 키가 없거나 잘못됨 / 비활성 / 만료 |
| 403 | account_suspended · email_not_verified · api_access_disabled | 계정 정지, 이메일 미인증, API 사용 제한 |
| 402 | insufficient_paid_credits | 유료 크레딧 부족 (details에 필요 / 보유 크레딧) |
| 404 | task_not_found · file_not_found | 작업 또는 파일을 찾을 수 없음 |
| 409 | idempotency_conflict | 같은 Idempotency-Key로 다른 요청을 보냄 |
| 413 · 415 | file_too_large · unsupported_media_type | 파일 크기 초과, 지원하지 않는 형식 |
| 422 | invalid_request · unsupported_model | 파라미터 오류 (message에 원인) |
| 429 | concurrency_limit_exceeded · rate_limit_exceeded | 동시 작업 5개 / 분당 20개 초과 (Retry-After 헤더 참고) |
| 500 | internal_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 사용이 제한될 수 있습니다.