# Seedance 2.5 API 연동: 모델 ID, Python, Node.js, BytePlus USD 30 활성화

> Seedance 2.5 API는 BytePlus와 Volcengine에서 정식 호출됩니다. 신규 계정은 USD 30(중국은 200위안) 이상으로 모델을 먼저 활성화해야 합니다.

- URL: https://blog.laozhang.ai/ko/posts/seedance-2-api
- Published: 2026-02-22
- Updated: 2026-10-22
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: AI 동영상 생성
- Tags: Seedance 2.5, Seedance API, 모델 ID, Python, Node.js, BytePlus ModelArk, Volcengine

---
2026년 10월 22일 기준 Seedance 2.5는 BytePlus ModelArk에서 `dreamina-seedance-2-5-260628`, 중국 본토 서비스인 Volcengine(火山方舟)에서 `doubao-seedance-2-5-260628`로 호출할 수 있습니다. 한국은 BytePlus ModelArk 이용 가능 국가에 들어 있어서 국내 개발자의 기본 경로는 BytePlus입니다. **API key를 만든 뒤에도 호출이 실패하는 가장 흔한 이유는 모델 미활성화입니다.** BytePlus는 USD 30 이상, Volcengine은 200위안 이상과 실명 인증을 갖춰야 Seedance 2.5를 활성화할 수 있습니다.

![Seedance 2.5 제품 공개, 공식 API 목록, provider별 모델 ID를 구분하는 검증 흐름](https://blog.laozhang.ai/posts/ko/seedance-2-api/img/model-id-check.webp)

*그림은 2026년 8월 4일 기준 판단 흐름입니다. 2026년 10월 22일 현재 BytePlus와 Volcengine 공식 목록에 Seedance 2.5 모델 ID가 올라 있으며, 현재 상태는 본문을 따릅니다.*

2.5 요청은 2.0 요청과 기본값이 다릅니다. `duration`을 비워 두면 모델이 4~30초 사이에서 길이를 정하고, `ratio` 기본값은 `adaptive`이며, 4K 출력은 없습니다. 아래 코드는 이 차이를 반영해 생성 → task ID 저장 → 콜백과 폴링 → 24시간 안에 다운로드·보관까지 한 흐름으로 처리합니다.

## Seedance 2.5 API는 BytePlus와 Volcengine에서 정식 호출된다

[BytePlus의 동영상 생성 작업 생성 API 문서](https://docs.byteplus.com/en/docs/modelark/create-video-generation-task-api)는 2026년 10월 20일 갱신본 상단에 "Dreamina Seedance 2.5 is now fully available"이라고 적고, 호출 주소로 `POST https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks`를 제시합니다. [BytePlus Seedance 2.5 튜토리얼](https://docs.byteplus.com/en/docs/modelark/seedance-2-5)의 모델 표에는 2.5와 2.0 계열 ID 네 개가 나란히 있고, [Volcengine Seedance 2.5 튜토리얼](https://docs.volcengine.com/docs/ark/seedance-2-5?lang=zh)(중국어)에는 같은 네 모델이 `doubao-*` 이름으로 있습니다. Volcengine Mini ID(`doubao-seedance-2-0-mini-260615`)도 문서에 명시돼 있어 접미사를 추측할 필요가 없습니다.

아직 "API는 곧 공개"라는 문장이 돌아다니는 이유는 2026년 7월 31일 자 [Seed의 Seedance 2.5 발표 글](https://seed.bytedance.com/zh/blog/one-take-creation-flexible-referencing-introducing-seedance-2-5)이 그 시점 문구 그대로 남아 있기 때문입니다. 제1자 API 공개일은 공식 문서에 날짜로 나오지 않고, 제3자 보도로는 2026년 8월 7일입니다. 출시 경과와 Dreamina 같은 제작 도구에서 쓸 수 있는지는 [Seedance 2.5 출시·접속 경로·사용 가능 여부·API 상태: 공식 API 공개 중](https://blog.laozhang.ai/ko/posts/seedance-2-5-release-access-api-status)에 정리돼 있습니다.

"네이티브 4K"라고 소개하는 제3자 페이지도 있지만 BytePlus 모델 표에서 2.5의 최고 해상도는 1080p(10비트)입니다. 4K는 2.0 Standard에만 있습니다.

## BytePlus·Volcengine·laozhang.ai 호출 경로별 host와 모델 ID

같은 "Seedance 2.5"라도 host, API key, 모델 ID, 경로는 한 행에서만 가져와야 합니다. 모델 ID 하나만 바꿔서 다른 경로로 옮기면 인증 오류나 모델 없음 오류가 납니다.

| 호출 경로 | base URL | API key | 2.5 모델 ID | 2.0 계열 모델 ID | 호출 전 조건 |
|---|---|---|---|---|---|
| BytePlus ModelArk (국제, 한국 이용 가능) | `https://ark.ap-southeast.bytepluses.com/api/v3` | ModelArk 콘솔 API Key 관리 페이지 | `dreamina-seedance-2-5-260628` | `dreamina-seedance-2-0-260128`, Fast `dreamina-seedance-2-0-fast-260128`, Mini `dreamina-seedance-2-0-mini-260615` | Model Activation에서 활성화, USD 30 이상 |
| Volcengine Ark (중국 본토 계정) | `https://ark.cn-beijing.volces.com/api/v3` | 火山方舟 콘솔 API Key 관리 페이지 | `doubao-seedance-2-5-260628` | `doubao-seedance-2-0-260128`, Fast `doubao-seedance-2-0-fast-260128`, Mini `doubao-seedance-2-0-mini-260615` | 실명 인증, 200위안 이상으로 활성화 |
| laozhang.ai 릴레이 | `https://api.laozhang.ai/seedance/api/v3` | `SeeDance2` 그룹에 배정된 토큰 | `doubao-seedance-2-5-260628` | Volcengine과 같은 `doubao-*` ID 세 개 | 토큰 단위 과금, 작업마다 사전 차감과 정산 두 줄 |
| 기타 제공업체 (OpenRouter, Replicate, fal 등) | 각 업체 문서 | 각 업체 키 | 예: OpenRouter `bytedance/seedance-2.5` | 업체마다 다름 | 해상도·참조 개수·실제 얼굴 규칙이 제1자와 다를 수 있음 |

*안내: [laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다](https://blog.laozhang.ai/ko/about#laozhang). 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.*

[BytePlus ModelArk 이용 가능 국가 목록](https://docs.byteplus.com/en/docs/modelark/availability)(2026년 4월 21일 갱신, 187개 항목)에는 한국, 일본, 대만, 홍콩이 있고 중국 본토, 러시아, 미국, 인도는 없습니다. 최종 이용 가능 여부는 구매 시점에 결정된다고 적혀 있습니다. Volcengine은 중국 본토 계정과 실명 인증이 필요한 서비스라서, 중국 법인이나 중국 리전 인프라가 이미 있는 팀이 아니라면 BytePlus부터 시작하는 편이 현실적입니다.

laozhang.ai는 Volcengine과 같은 `doubao-*` ID를 쓰지만 base URL에 `/seedance`가 붙습니다. [laozhang.ai Seedance 2.0·2.5 동영상 생성 API 문서](https://docs.laozhang.ai/en/api-capabilities/seedance2-video-generation)는 `https://api.laozhang.ai` 뒤에 공식 경로 `/api/v3/...`를 바로 붙이지 말라고 경고하고, `SeeDance2`가 아닌 그룹의 토큰은 채널 없음 오류로 실패한다고 설명합니다. 작업 상태 `completed`도 `succeeded`와 같은 성공으로 취급하고, 영상은 `content.video_url` 또는 `GET https://api.laozhang.ai/v1/videos/{id}/content`로 내려받습니다. `resolution`에 `4k`를 보내면 400으로 바로 거부되고 과금되지 않습니다.

## API key를 만들어도 실패한다면: 모델 활성화 USD 30과 200위안

BytePlus의 준비 순서는 계정 등록 → API Key 관리 페이지에서 **Create API Key** → Model Activation(모델 활성화)에서 Seedance 2.5 활성화입니다. 세 번째 단계를 건너뛰면 키와 주소가 맞아도 생성 요청이 실패합니다. [BytePlus Seedance 모델 활성화·사용·환불 안내](https://docs.byteplus.com/en/docs/modelark/seedance-model-activation-usage-and-refund)가 정한 조건은 다음 중 하나입니다.

- 인증된 Credits 잔액이 USD 30 이상
- USD 30 이상 전용 AI Savings Plan을 사서 잔액이 남아 있음 (USD 30 플랜은 1개월, 60·100 플랜은 3개월 유효)
- USD 30 이상 리소스 팩(resource pack)을 사서 남은 한도가 있음 (90일 유효)

차감 순서는 리소스 팩 → AI Savings Plan → 잔액입니다. 충전한 Credits는 인출할 수 없고, 플랜과 리소스 팩은 취소할 수 없습니다. 신규 사용자에게 모델별 무료 추론 한도가 주어지지만 [BytePlus 무료 추론 한도 문서](https://docs.byteplus.com/en/docs/modelark/free-inference-quota)의 동영상 모델 목록에는 Seedance의 무료 한도 항목이 없습니다. 무료 한도를 다 쓴 계정도 모델을 활성화하기 전까지 호출이 실패합니다.

Volcengine은 [Volcengine Seedance 모델 활성화·사용·환불 안내](https://docs.volcengine.com/docs/ark/seedance-model-activation-usage-and-refund?lang=zh)(중국어)에 따라 가용 잔액 200위안, 200위안 이상 전용 절감 플랜(200위안 플랜 30일, 500·1000위안 플랜 90일), 200위안 이상 리소스 팩(90일) 중 하나를 갖추고 실명 인증을 마쳐야 합니다. 모델이 활성화된 동안 잔액 중 200위안까지는 인출할 수 없습니다.

미활성화 상태에서 나오는 정확한 오류 코드는 공개 문서에 없으므로, 첫 실패 응답의 `code`와 `message`를 그대로 기록해 두세요. 이 실패는 프롬프트나 네트워크 문제가 아니라 계정 상태 문제라서 같은 요청을 다시 보내도 해결되지 않습니다.

비용은 BytePlus 공식 예시(16:9, 5초, 입력 영상 없음)로 환산하면 Seedance 2.5 720p가 초당 약 USD 0.231, 1080p가 약 USD 0.569이며, 성공한 영상만 과금됩니다. 경로별 비교와 30초 영상 비용은 [Seedance 2.5 API 가격: 경로별 초당 비교, 30초 비용과 무료 여부](https://blog.laozhang.ai/ko/posts/seedance-2-pricing-free-vs-paid-guide)를 보세요.

## 2.0 코드를 2.5로 바꿀 때: duration·ratio 기본값과 30초·참조 50개

2.0 설정에서 모델 ID와 숫자만 바꾸면 길이와 비율이 예상과 다르게 나오거나 요청이 거부될 수 있습니다. 차이는 BytePlus 2.5 튜토리얼의 모델 표 기준이며 Volcengine 표도 같습니다.

| 항목 | Seedance 2.5 | Seedance 2.0 계열 |
|---|---|---|
| `duration` | 4~30초 또는 `-1`, 기본값 `-1` (모델이 길이 선택) | 4~15초 또는 `-1` |
| `ratio` | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, `adaptive`; 기본값 `adaptive` | 같은 비율 목록 |
| 해상도 | 480p·720p (8비트), 1080p (10비트), 4K 없음 | Standard는 480p~1080p와 4k, Fast·Mini는 720p까지 |
| `output_format` | `mp4` (기본) 또는 `mov` | `mp4` |
| 참조 자료 | 최대 50개 (이미지 30, 영상 10, 오디오 10), 오디오만 참조 가능 | 최대 15개 (9, 3, 3), 오디오만은 불가 |
| Draft 모드 | 지원 (`draft=true`, 480p 미리보기) | 미지원 |

작업 종류마다 제약도 있습니다. 첫 프레임 또는 첫·끝 프레임 영상은 `ratio`가 `adaptive`여야 하고, 영상 편집은 `ratio`를 `adaptive`, `duration`을 `-1`로 둬야 하며 참조 영상은 4~30초입니다. 영상 연장도 `ratio`가 `adaptive`입니다. 새 파라미터 `omni_reference_task_type`의 기본값은 `auto`입니다.

텍스트→영상이라면 `duration`을 직접 정하는 편이 안전합니다. 비워 두면 모델이 길이를 고르고, 길이가 곧 토큰 사용량이라 비용도 따라 바뀝니다. `mov`는 H.264, yuv444p, PCM 조합이라 일부 플레이어에서 열리지 않으니 기본은 `mp4`로 두세요.

입력 한도는 이미지 한 장 30MB 미만, 요청 본문 64MB 이하이고 큰 파일은 Base64 대신 URL이나 asset ID로 보내야 합니다. 영상은 mp4·mov 200MB 이하, 오디오는 wav·mp3로 클립당 2~30초, 최대 10개, 합계 30초 이하, 클립당 15MB 이하입니다.

실제 사람 얼굴이 담긴 참조 이미지·영상은 2.5에서도 직접 올릴 수 없습니다. 같은 계정에서 생성한 결과물 재사용, 프리셋 가상 캐릭터, 승인된 실제 인물 asset만 쓸 수 있고, 오류 문구별 대처는 [Seedance 2.0·2.5 ‘input image may contain a real person’ 오류 해결법](https://blog.laozhang.ai/ko/posts/seedance-2-api-real-people)에 있습니다.

## Python과 Node.js에서 같은 task ID를 추적한다

세 환경 변수는 앞의 표에서 한 행을 골라 채웁니다. 예시는 BytePlus 기준이며, Volcengine은 `SEEDANCE_BASE_URL`을 `https://ark.cn-beijing.volces.com/api/v3`, `SEEDANCE_MODEL`을 `doubao-seedance-2-5-260628`로, laozhang.ai는 base를 `https://api.laozhang.ai/seedance/api/v3`로 바꾸고 같은 `doubao-*` ID를 씁니다. 경로 뒷부분(`/contents/generations/tasks`)은 세 곳이 같습니다.

*안내: [laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다](https://blog.laozhang.ai/ko/about#laozhang). 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.*

```bash
export SEEDANCE_BASE_URL="https://ark.ap-southeast.bytepluses.com/api/v3"
export SEEDANCE_API_KEY="BytePlus ModelArk에서 만든 API key"
export SEEDANCE_MODEL="dreamina-seedance-2-5-260628"
```

API key는 서버 환경 변수에만 두고 브라우저 코드, 모바일 앱, 공개 저장소에 넣지 마세요.

### curl

```bash
curl -X POST "$SEEDANCE_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [{
      "type": "text",
      "text": "A calm product shot, one slow camera move, clean studio light"
    }],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'
```

성공한 생성 응답은 완성된 MP4가 아니라 작업 `id`입니다. 이 `id`를 저장한 다음에 상태를 조회합니다.

### Python

```python
import os, time, requests

base = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}", "Content-Type": "application/json"}
payload = {
    "model": os.environ["SEEDANCE_MODEL"],
    "content": [{"type": "text", "text": "도자기 컵을 천천히 보여 주는 스튜디오 장면, 카메라는 한 번만 천천히 이동"}],
    "ratio": "16:9",       # 텍스트→영상은 고정 비율 가능. 첫 프레임·편집·연장은 "adaptive"
    "resolution": "720p",  # 2.5는 480p/720p/1080p, 4k 없음
    "duration": 5,         # 생략하면 -1: 모델이 4~30초 중에서 길이를 고름
    "generate_audio": True,
}
r = requests.post(f"{base}/contents/generations/tasks", headers=headers, json=payload, timeout=30)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")  # 미활성화·권한 오류는 code를 그대로 기록
task_id = r.json()["id"]  # 폴링 전에 저장
print("task_id", task_id)

while True:
    r = requests.get(f"{base}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    r.raise_for_status()
    task = r.json()
    status = task.get("status")
    if status in ("queued", "running"):
        time.sleep(10)
        continue
    if status in ("succeeded", "completed"):  # completed는 laozhang.ai 호환 상태
        url = task["content"]["video_url"]  # 24시간 안에 내려받아 보관
        with requests.get(url, stream=True, timeout=120) as v:
            v.raise_for_status()
            with open(f"{task_id}.mp4", "wb") as f:
                for chunk in v.iter_content(1 << 20):
                    f.write(chunk)
        print("saved", f"{task_id}.mp4")
    else:
        print("final", status, task.get("error"))
    break
```

### Node.js 18+

`seedance.mjs`로 저장하고 `node seedance.mjs`로 실행합니다.

```js
import { writeFile } from "node:fs/promises";

const base = process.env.SEEDANCE_BASE_URL.replace(/\/$/, "");
const headers = { Authorization: `Bearer ${process.env.SEEDANCE_API_KEY}`, "Content-Type": "application/json" };

async function call(path, init = {}) {
  const r = await fetch(`${base}${path}`, { ...init, headers: { ...headers, ...init.headers } });
  const type = r.headers.get("content-type") || "";
  if (!type.includes("application/json")) throw new Error(`JSON 대신 ${type} 응답 (base URL 확인)`);
  const data = await r.json();
  if (!r.ok) throw new Error(`${r.status}: ${JSON.stringify(data)}`);
  return data;
}

const created = await call("/contents/generations/tasks", {
  method: "POST",
  body: JSON.stringify({
    model: process.env.SEEDANCE_MODEL,
    content: [{ type: "text", text: "Slow studio shot of a ceramic cup" }],
    ratio: "16:9",
    resolution: "720p",
    duration: 5, // 2.5에서 생략하면 -1
    generate_audio: true,
  }),
});
const taskId = created.id; // 먼저 영구 저장

for (;;) {
  const task = await call(`/contents/generations/tasks/${taskId}`);
  if (["queued", "running"].includes(task.status)) {
    await new Promise((resolve) => setTimeout(resolve, 10000));
    continue;
  }
  if (["succeeded", "completed"].includes(task.status)) {
    const video = await fetch(task.content.video_url); // URL은 24시간 유효
    if (!video.ok) throw new Error(`다운로드 실패 ${video.status}`);
    await writeFile(`${taskId}.mp4`, Buffer.from(await video.arrayBuffer()));
    console.log("saved", `${taskId}.mp4`);
  } else {
    console.log("final", task.status, task.error);
  }
  break;
}
```

![Python과 Node.js가 공유하는 create, task ID 저장, polling, 결과 보관 흐름](https://blog.laozhang.ai/posts/ko/seedance-2-api/img/async-code-flow.webp)

두 코드는 2026년 10월 22일 기준 문법 검사(`python3 -m py_compile`, `node --check`)를 통과하고, 형식이 틀린 키로 BytePlus에 보내면 `401` `AuthenticationError` 본문을 그대로 출력합니다. 유효한 키로 영상을 생성하는 단계는 계정 활성화 후에 확인해야 합니다. 생성 요청이 `id`를 받기 전에 타임아웃되면 두 번째 `POST`를 자동으로 보내지 마세요. 첫 요청이 이미 접수됐을 수 있으므로 콜백, 요청 로그, 제공업체 지원 창구로 먼저 확인합니다.

## 모델 ID와 API key를 같은 설정 단위로 묶는다

환경 변수를 `API_KEY` 하나로 두기보다 호출 경로 하나를 통째로 설정해 두면 운영 중에 BytePlus 키로 `doubao-*` ID를 부르는 식의 혼선을 막기 쉽습니다.

```ts
const seedanceRoutes = {
  "byteplus-ap": {
    baseUrl: "https://ark.ap-southeast.bytepluses.com/api/v3",
    apiKey: process.env.BYTEPLUS_ARK_API_KEY,
    model: "dreamina-seedance-2-5-260628",
  },
  "volcengine-cn": {
    baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
    apiKey: process.env.VOLC_ARK_API_KEY,
    model: "doubao-seedance-2-5-260628",
  },
  "laozhang-relay": {
    baseUrl: "https://api.laozhang.ai/seedance/api/v3", // /seedance 빠지면 404
    apiKey: process.env.LAOZHANG_SEEDANCE2_KEY, // SeeDance2 그룹 토큰
    model: "doubao-seedance-2-5-260628",
  },
} as const;
```

BytePlus 키를 Volcengine host에 보내거나 다른 그룹의 laozhang.ai 토큰을 Seedance base에 쓰면 실패합니다. 키를 만들 때 모델이나 IP 제한을 걸었다면 그 조건도 배포 설정에 함께 적어 두세요.

*안내: [laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다](https://blog.laozhang.ai/ko/about#laozhang). 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.*

속도 제한은 주 계정과 모델 계열 단위로 걸립니다. BytePlus 2.5 튜토리얼 기준 RPM은 기업 600, 개인 180이고 동시 실행은 기업 10, 개인 3이며, 넘으면 429가 돌아옵니다. 개인 계정이라면 생성 요청을 큐에 넣고 동시에 세 개까지만 돌리는 편이 안전합니다.

BytePlus 엔드포인트 기반 온라인 추론에서는 Seedance 2.0 생성 요청에 `priority`를 `0`부터 `9`까지 넣을 수 있습니다. 큰 값은 **같은 엔드포인트에서 아직 대기 중인 낮은 우선순위 작업보다 앞서게 할 뿐**입니다. 실행 중인 작업을 멈추지 않고, 다른 엔드포인트의 대기열을 넘지 않으며, 생성 자체를 빠르게 하지도 않습니다. 이 범위는 2.0 기준으로 문서화돼 있어 2.5에 같은 효과를 기대하면 안 됩니다.

## 401, 404, HTML이면 prompt를 고치지 않는다

인증 전에 해 볼 수 있는 안전한 점검은 "요청이 어느 경계에 도착했는가"를 보는 것입니다. 2026년 10월 21일 기준 자격 증명 없이 빈 JSON `{}`를 POST하면 다음과 같이 응답합니다(7월 18일과 같은 패턴).

| 결과 | 뜻 | 다음 행동 |
|---|---|---|
| BytePlus AP `401` JSON `AuthenticationError` | 경로는 맞고 키가 없음 | 키, 모델 활성화, 잔액을 따로 확인 |
| Volcengine CN `401` JSON `AuthenticationError` | 중국 경로의 인증 단계까지 도달 | 중국 계정 키와 `doubao-*` ID 확인 |
| laozhang.ai `/seedance/api/v3/...` `401` JSON "Invalid token" | 릴레이 경로가 맞고 토큰이 필요 | 토큰의 `SeeDance2` 그룹 확인 |
| laozhang.ai `/api/v3/...` `404` JSON "Invalid URL" | `/seedance`가 빠짐 | base를 `/seedance/api/v3`로 수정 |
| laozhang.ai 옛 경로 `/seedance/v3/...` `200` HTML | API가 아니라 웹 페이지에 도달 | 상태 코드만 보지 말고 `Content-Type`과 JSON 본문 확인 |

*안내: [laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다](https://blog.laozhang.ai/ko/about#laozhang). 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.*

`401`은 모델 활성화나 생성 성공의 증거가 아닙니다. 반대로 `200`이어도 HTML이면 API 성공이 아닙니다. 첫 점검에서는 상태 코드, `Content-Type`, 본문이 JSON인지를 함께 기록하세요. 키가 맞는데도 생성이 거절되면 앞 절의 활성화 조건부터 확인합니다.

## 작업 ID를 먼저 저장하고 callback을 처리한다

생성 요청 직전에 로컬 작업과 요청 해시를 만들고, 응답의 task ID를 즉시 저장합니다. 해시에는 호출 경로, 모델 ID, 정규화한 프롬프트, 참조 asset ID, 출력 설정, 사용자·작업 ID를 넣을 수 있습니다.

```ts
type LocalJob = {
  id: string;
  route: "byteplus-ap" | "volcengine-cn" | "laozhang-relay";
  requestHash: string;
  providerTaskId?: string;
  status: "submitting" | "queued" | "running" | "succeeded" | "failed" | "expired";
  outputCopiedAt?: string;
};
```

[BytePlus 작업 생성 API 문서](https://docs.byteplus.com/en/docs/modelark/create-video-generation-task-api)는 `callback_url`을 선택 항목으로 두고, 상태가 바뀌면 작업 조회 응답과 같은 형태의 본문을 POST한다고 설명합니다. 상태는 `queued`, `running`, `succeeded`, `failed`, `expired`이며 끝 상태는 뒤의 세 가지입니다.

`succeeded` 또는 `failed` 전달에 대해 5초 안에 성공 응답을 받지 못하면 세 번 재시도한다고 문서에 적혀 있습니다. 모든 상태가 항상 세 번 온다는 뜻도, 콜백이 정확히 한 번만 온다는 뜻도 아닙니다. 웹훅 서명 방식은 공개 문서에 없으니 서명 검증을 지어내지 마세요.

대신 핸들러는 HTTPS, 허용 메서드와 content type, 본문 크기, 이미 알고 있는 task ID와 그 작업의 호출 경로를 확인하고, 같은 이벤트를 여러 번 받아도 결과가 같도록 만듭니다.

```ts
async function applySeedanceUpdate(event: ProviderTask) {
  const job = await jobs.findByProviderTaskId(event.id);
  if (!job) return { accepted: false, reason: "unknown_task" };

  // 끝 상태를 queued/running으로 되돌리는 이벤트는 무시한다.
  if (isIllegalRegression(job.status, event.status)) {
    return { accepted: true, changed: false };
  }

  await jobs.compareAndSet(job.id, normalize(event));
  if (event.status === "succeeded") await enqueueOutputCopy(job.id);
  return { accepted: true, changed: true };
}
```

콜백 핸들러는 빨리 응답하고 무거운 다운로드는 큐로 넘기세요. 별도 복구 워커가 살아 있는 작업을 간격을 늘려 가며 조회하면 배포 중 누락되거나 늦거나 순서가 뒤바뀐 콜백을 수습할 수 있습니다.

## create timeout은 두 번째 생성 허가가 아니다

| 실패 지점 | 안전한 판단 | 하지 말 것 |
|---|---|---|
| 생성 요청 타임아웃, task ID 미저장 | 요청 해시로 로컬 작업 확인, 제공업체 로그·지원으로 기존 작업 탐색 | 타임아웃 직후 새 생성 요청 |
| task ID 저장 후 콜백 없음 | 같은 ID로 폴링하고 콜백 엔드포인트 로그 확인 | 같은 프롬프트 재제출 |
| `401`/`403` | host, 키 권한 범위·그룹, 모델 활성화 확인 | 키를 클라이언트에 노출하거나 다른 host로 그냥 전송 |
| 활성화 전 생성 실패 | USD 30 / 200위안 기준 충족 후 Model Activation | 같은 요청 반복 |
| `404` 또는 HTML | base URL과 경로, `Content-Type` 수정 | 모델 ID나 프롬프트만 바꾸기 |
| `429` | 동시 실행을 3 또는 10 이하로 줄이고 간격을 늘려 재시도 | 고정 간격 병렬 재시도 |
| 끝 상태 `failed`/`expired` | 오류를 분류하고 사용자 의도에 따라 새 작업 여부 결정 | 기존 작업을 성공으로 덮어쓰기 |

기존 작업이 없다는 것을 확인할 수단이 없다면 자동 재제출보다 사람이 판단하는 `unknown_submit_outcome` 상태가 안전합니다. 중복 비용과 중복 영상이 조용히 생기는 것보다 낫습니다. 대기열이 오래 멈추거나 실패 사유를 읽어야 할 때는 [Seedance 2.5 오류·대기열·시간 초과 진단: 수락된 작업부터 확인](https://blog.laozhang.ai/ko/posts/seedance-2-not-working)에서 상태별로 이어서 확인하세요.

## 결과는 “완료”가 아니라 “보관”까지 추적한다

`succeeded` 응답에서 영상 URL을 받아도 작업은 아직 끝난 것이 아닙니다. BytePlus 2.5 튜토리얼 기준 영상 URL은 24시간 동안만 열리고 최대 100번까지 내려받을 수 있으며, 작업 기록은 7일간 보관됩니다. 다운로드 응답의 상태와 media type을 확인한 뒤 자체 저장소에 복사하고, 체크섬이나 객체 메타데이터와 `outputCopiedAt`을 기록하세요.

생성 요청의 `execution_expires_after` 기본값은 172800초(48시간)라서 그 안에 끝나지 않은 작업은 `expired`가 됩니다. Draft 모드로 만든 480p 미리보기의 task ID는 생성 시각부터 7일 동안 최종 영상 생성에 쓸 수 있고, 미리보기와 최종 영상은 각각 과금되는 작업 두 개입니다.

참조 자료를 보낼 때는 `content` 항목의 `role`을 정확히 씁니다. BytePlus 직접 경로는 `first_frame`, `last_frame`, `reference_image`, `reference_video`, `reference_audio` 같은 역할을 정의하고, 이미지 참조 예시는 `{"type":"image_url","image_url":{"url":"..."},"role":"reference_image"}` 형태입니다. 참조 이미지 구성과 샷 설계는 [Seedance 2 프롬프트 가이드: 참조 이미지, 샷 설계와 2.5 수정 예제](https://blog.laozhang.ai/ko/posts/seedance-2-prompt-guide)를 참고하세요.

## BytePlus·Volcengine·laozhang.ai 중 언제 바꿀까

- **BytePlus ModelArk**: 한국 계정으로 직접 계약하고, USD로 결제하고, Standard·Fast·Mini·2.5 전체 모델과 엔드포인트 수준 제어가 필요할 때 기본 선택입니다.
- **Volcengine Ark**: 중국 본토 법인·실명 계정과 중국 리전 인프라가 운영 요건일 때 고릅니다.
- **laozhang.ai 릴레이**: 다른 모델과 같은 계정·키 관리 안에서 Seedance를 쓰고 싶을 때 선택지가 됩니다. 2.5와 2.0 계열 ID 네 개를 같은 비동기 형식으로 부르고, 과금은 토큰 단위이며 작업마다 사전 차감과 정산 두 줄이 호출 로그에 남습니다.

*안내: [laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다](https://blog.laozhang.ai/ko/about#laozhang). 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.*

laozhang.ai에는 실제 인물·가상 인물 asset 흐름도 문서화돼 있습니다. [laozhang.ai Seedance 실제 인물·가상 인물 asset API 문서](https://docs.laozhang.ai/en/api-capabilities/seedance2-human-virtual-workflow)에 따르면 base는 `https://yingtu.ai`, 인증은 같은 laozhang.ai 키이고, 실제 인물은 공식 H5 동의와 생체 확인을 거쳐 asset을 만든 뒤 `Active`가 되면 `asset://...` URI를 `reference_image`로 씁니다. 이 기능은 별도 권한이 있는 계정에서만 열리고(권한이 없으면 `403 capability_unavailable`), 문서 예시는 2.0 ID로 작성돼 있습니다.

OpenRouter, Replicate, fal 같은 제3자 제공업체는 각자 모델 이름, 해상도, 실제 얼굴 규칙, 한도가 따로 있습니다. 2.0 시기 기준의 업체별 차이는 [2026년 Seedance 2.0 API 제공업체 비교: Kie, OpenRouter와 서드파티 경로 선택법](https://blog.laozhang.ai/ko/posts/seedance-2-api-providers-comparison)에 있고, 2.5 가격은 앞에서 링크한 가격 글에서 확인하세요. 어느 쪽이든 구현은 고른 한 경로의 문서에서 다시 시작해야 합니다.

## Seedance 2.5 API 출시 전 체크리스트

- host, API key, 모델 ID, 경로가 표의 같은 행에서 왔는가
- BytePlus는 Model Activation에서 Seedance 2.5가 활성화됐는가 (USD 30 이상), Volcengine은 실명 인증과 200위안 기준을 채웠는가
- `duration`을 직접 지정했는가, 첫 프레임·편집·연장 작업은 `ratio`를 `adaptive`로 뒀는가
- `resolution`이 1080p 이하인가 (2.5에는 4K 없음)
- 생성 응답의 task ID가 폴링보다 먼저 저장되는가
- 콜백이 중복되거나 늦게 와도 결과가 같은가, 폴링이 누락을 복구하는가
- 동시 실행이 계정 한도(개인 3, 기업 10) 안에 있는가
- 영상이 24시간 안에 자체 저장소로 복사되는가

하나라도 답할 수 없다면 유료 생성 요청을 멈추고 그 항목부터 해결하세요.

## Seedance 2.5 API 자주 묻는 질문

### Seedance 2.5 API는 무료인가요?

공개된 무료 Seedance 2.5 API 한도는 없습니다. BytePlus와 Volcengine은 신규 사용자에게 모델별 무료 추론 한도를 주지만 동영상 모델 목록에 Seedance 무료 한도 항목이 없고, 2.5를 쓰려면 USD 30(Volcengine은 200위안) 기준으로 모델을 활성화해야 합니다.

### Seedance API key는 어디서 만드나요?

BytePlus는 ModelArk 콘솔의 API Key 관리 페이지에서 **Create API Key**로 만듭니다. 키를 만든 다음 Model Activation에서 Seedance 2.5를 활성화해야 호출이 성공합니다. Volcengine 키는 火山方舟 콘솔에서 따로 만들며 BytePlus 키와 서로 바꿔 쓸 수 없습니다.

### Seedance 2.0 API 코드를 2.5에 그대로 쓸 수 있나요?

엔드포인트와 비동기 흐름은 같지만 요청 내용은 고쳐야 합니다. 2.5는 `duration` 기본값이 `-1`, `ratio` 기본값이 `adaptive`이고 4K가 없습니다. 길이를 직접 지정하고, 4k 설정을 1080p 이하로 내리고, 첫 프레임·편집·연장 작업의 `ratio`를 `adaptive`로 바꿔야 합니다.

### 한국에서 BytePlus Seedance API를 쓸 수 있나요?

BytePlus ModelArk 이용 가능 국가 목록(2026년 4월 21일 갱신)에 한국이 들어 있습니다. 최종 이용 가능 여부는 구매 시점에 결정되며, 중국 본토·러시아·미국·인도는 목록에 없습니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-22.

- [BytePlus의 동영상 생성 작업 생성 API 문서](https://docs.byteplus.com/en/docs/modelark/create-video-generation-task-api) (docs.byteplus.com)
- [BytePlus Seedance 2.5 튜토리얼](https://docs.byteplus.com/en/docs/modelark/seedance-2-5) (docs.byteplus.com)
- [Volcengine Seedance 2.5 튜토리얼](https://docs.volcengine.com/docs/ark/seedance-2-5?lang=zh) (docs.volcengine.com)
- [Seed의 Seedance 2.5 발표 글](https://seed.bytedance.com/zh/blog/one-take-creation-flexible-referencing-introducing-seedance-2-5) (seed.bytedance.com)
- [BytePlus ModelArk 이용 가능 국가 목록](https://docs.byteplus.com/en/docs/modelark/availability) (docs.byteplus.com)
- [BytePlus Seedance 모델 활성화·사용·환불 안내](https://docs.byteplus.com/en/docs/modelark/seedance-model-activation-usage-and-refund) (docs.byteplus.com)
- [BytePlus 무료 추론 한도 문서](https://docs.byteplus.com/en/docs/modelark/free-inference-quota) (docs.byteplus.com)
- [Volcengine Seedance 모델 활성화·사용·환불 안내](https://docs.volcengine.com/docs/ark/seedance-model-activation-usage-and-refund?lang=zh) (docs.volcengine.com)
