> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 2.0·2.5 비디오 생성 API: 요금과 사용법

> Seedance 2.0과 2.5 비디오 작업을 만들어 MP4를 내려받고, 토큰당 USD 단가와 작업 하나에 기록되는 호출 로그 두 줄을 대조하는 방법을 안내합니다.

Seedance 2.0과 2.5는 텍스트, 이미지, 비디오, 오디오를 입력받아 비디오를 만드는 모델이며, Volcengine Ark 호환 비동기 작업 방식으로 호출합니다. `SeeDance2` 그룹의 API 키(콘솔에서는 '토큰'이라고 부릅니다)가 필요하고, 작업은 토큰 사용량으로 과금됩니다.

| 항목 | 내용 |
| - | - |
| 모델 | `doubao-seedance-2-5-260628`(2.5), `doubao-seedance-2-0-260128`(2.0 standard), `doubao-seedance-2-0-fast-260128`(fast), `doubao-seedance-2-0-mini-260615`(mini) |
| base URL | `https://api.laozhang.ai/seedance/api/v3` |
| 작업 생성 | `POST /contents/generations/tasks` |
| 작업 조회 | 작업이 성공할 때까지 `GET /contents/generations/tasks/{id}` |
| 비디오 다운로드 | `content.video_url` 또는 `GET https://api.laozhang.ai/v1/videos/{id}/content` |
| 토큰 그룹 | `SeeDance2` (아래 API 키 설정 참고) |
| 과금 | 토큰 사용량 기준. 그룹 배율 0.1714가 Volcengine의 위안화 목록 가격을 USD로 환산하며, 고정 환율 1:7 기준으로 목록 가격의 약 1.2배입니다. USD 단가와 비디오 한 편 예상 비용은 아래 과금과 가격 절에 있습니다 |
| 호출 로그 | 작업 하나에 두 줄이 기록됩니다. 생성 시점의 선차감과 완료 시점의 정산이며, 작업 비용은 두 줄의 합계입니다 |
| 결과 보관 | 서명된 비디오 URL은 보통 24시간 유효하므로 작업이 성공하면 바로 저장하세요 |

> [!WARNING]
>
> **base URL은 `https://api.laozhang.ai/seedance/api/v3`를 사용하세요.**
>
> * Ark 공식 경로 `/api/v3/...`를 `https://api.laozhang.ai`에 바로 붙이지 마세요.
> * 접두사에서 `/api`를 빼면 안 됩니다. `/seedance/v3/...`는 API JSON 대신 사이트의 HTML을 반환합니다.

## API 키 설정

| 설정 | 값 |
| - | - |
| 콘솔 | [토큰 관리](https://api.laozhang.ai/token) → 토큰 만들기 |
| 그룹 | `SeeDance2` |
| 과금 방식 | 사용량 우선(콘솔 표시: 按量优先, 권장) 또는 사용량 과금(按量计费) |
| 요청 헤더 | `Authorization: Bearer $LAOZHANG_API_KEY` |

Seedance 모델은 `SeeDance2` 그룹에서만 호출할 수 있으므로 키도 이 그룹으로 만들어야 합니다. `default`나 `Wan` 같은 다른 그룹의 키로 호출하면 사용 가능한 채널이 없다는 오류가 납니다. Seedance 전용 키를 따로 두면 로그와 청구 내역을 확인하기도 쉽습니다.

## 엔드포인트

```text theme={null}
Base URL: https://api.laozhang.ai/seedance/api/v3

작업 생성             POST /contents/generations/tasks
작업 상태·결과 조회   GET  /contents/generations/tasks/{id}

MP4 다운로드 (Seedance base URL 밖의 호환 엔드포인트):
                      GET  https://api.laozhang.ai/v1/videos/{id}/content
```

작업 ID 없이 `GET /contents/generations/tasks`를 호출하지 마세요. 이 릴레이에서는 목록 엔드포인트가 JSON 대신 사이트의 HTML을 반환합니다. 작업을 만든 뒤 ID로 하나씩 조회하세요.

## 과금과 가격

Seedance는 Volcengine Ark 목록 가격에 20%를 더해 토큰 사용량으로 과금합니다. 추가분은 세금, 환전과 국경 간 정산, 플랫폼 운영, 기술 지원 비용에 쓰입니다. 2026년 10월 14일부터 환산 방식은 다음과 같습니다.

* USD 가격 = Volcengine 위안화 목록 가격 × 0.1714 (`SeeDance2` 그룹 배율)
* 고정 환율 1:7에서 0.1714 × 7 ≈ 1.2이므로 목록 가격의 약 1.2배를 지불합니다

호출 로그의 금액에는 이미 배율이 반영되어 있으니 다시 곱하지 마세요. 가격은 모델, 출력 해상도, 입력 비디오 포함 여부에 따라 달라집니다. 아래는 100만 토큰당 가격입니다.

| 모델 ID | 출력 | 목록 가격 (입력 비디오 없음 / 있음) | LaoZhang API (입력 비디오 없음 / 있음) |
| - | - | -: | -: |
| `doubao-seedance-2-5-260628` | 480p, 720p | ¥70 / ¥42 | \$12.00 / \$7.20 |
| `doubao-seedance-2-5-260628` | 1080p | ¥77 / ¥46 | \$13.20 / \$7.88 |
| `doubao-seedance-2-0-260128` | 480p, 720p | ¥46 / ¥28 | \$7.88 / \$4.80 |
| `doubao-seedance-2-0-260128` | 1080p | ¥51 / ¥31 | \$8.74 / \$5.31 |
| `doubao-seedance-2-0-fast-260128` | 480p, 720p | ¥37 / ¥22 | \$6.34 / \$3.77 |
| `doubao-seedance-2-0-mini-260615` | 480p, 720p | ¥23 / ¥14 | \$3.94 / \$2.40 |

목록 가격은 [Volcengine Ark 모델 가격](https://www.volcengine.com/docs/82379/1544106?lang=zh)(중국어)을 따랐습니다. fast와 mini 모델은 720p까지 지원합니다.

출력 5초, 16:9, 입력 비디오 없음 조건에서 실제로 출력되는 121프레임 기준 비디오 한 편의 대략적인 비용입니다(720p 약 108,900토큰, 1080p 약 245,025토큰).

* Seedance 2.5: 720p 약 \$1.31, 1080p 약 \$3.23
* Seedance 2.0: 720p 약 \$0.86, 1080p 약 \$2.14
* fast: 720p 약 \$0.69
* mini: 720p 약 \$0.43

실제 토큰 수는 작업 결과의 `usage.completion_tokens`이고, 작업 비용은 호출 로그에 기록된 두 줄의 합계입니다. 모델 가격은 [콘솔 가격 페이지](https://api.laozhang.ai/account/pricing)에도 있으며, 그룹과 배율은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 볼 수 있습니다.

> [!TIP]
>
> 720p 안팎의 짧은 클립을 소리와 함께 만든다면 [MiniMax H3](https://docs.laozhang.ai/ko/api-capabilities/minimax-h3-video-generation.md)는 768P 5초에 \$0.25, [Muse](https://docs.laozhang.ai/ko/api-capabilities/muse-video-generation.md)는 10초에 \$0.30이며, 둘 다 `default` 그룹 키로 호출합니다. 모든 모델은 [비디오 API 비교](https://docs.laozhang.ai/ko/api-capabilities/video-generation-guide.md)에서 비교해 보세요.

작업 상세에는 `group_ratio: 1` 옆에 배율이 `topup_convert_ratio: 0.1714`로 표시될 수 있습니다. 두 필드는 용도가 다릅니다. `group_ratio: 1`이라고 해서 배율이 적용되지 않았다는 뜻은 아닙니다.

### 작업 비용 예상하기

Volcengine은 비용 추정에 다음 공식을 안내합니다.

```text theme={null}
비용 = 토큰 단가 × 토큰 사용량
토큰 사용량 ≈ (입력 비디오 길이 + 출력 비디오 길이) × 출력 가로 × 출력 세로 × 프레임 레이트 / 1024
```

단가는 출력 해상도와 입력 비디오 포함 여부에 따라 달라지고, 출력 길이는 사용량을 좌우합니다.

* 1080p 출력은 480p, 720p보다 토큰당 단가가 높습니다. 위 표를 참고하세요.
* 입력 비디오(`video_url`)가 있는 요청은 단가가 낮습니다(표의 '입력 비디오 있음' 값). 다만 입력 비디오의 길이도 사용량에 포함되므로, 같은 5초 출력이라도 전체 비용은 보통 더 높습니다.
* 입력 비디오가 있는 요청에는 Volcengine이 최소 토큰 사용량을 정해 두며, 추정값이 그보다 작으면 최소치로 과금합니다.
* 출력이 길수록 토큰을 더 씁니다. Seedance 2.5는 `duration` 기본값이 `-1`이라 모델이 4\~30초 사이에서 길이를 정하므로, 비용이 중요하면 `duration`을 직접 지정하세요.

아래는 출력 5초, 16:9 비디오에 대해 Volcengine이 공개한 위안화 가격입니다([Volcengine Ark 모델 가격](https://www.volcengine.com/docs/82379/1544106?lang=zh), 중국어). 해상도와 입력 조건을 비교하는 용도이며, LaoZhang API의 USD 가격은 위의 단가를 사용하세요.

| 모델 | 입력 | 480p | 720p | 1080p |
| - | - | - | - | - |
| `doubao-seedance-2-5-260628` | 입력 비디오 없음 | ¥3.36 | ¥7.56 | ¥18.71 |
| `doubao-seedance-2-5-260628` | 입력 비디오 2\~30초 | ¥3.63–14.12 | ¥8.16–31.75 | ¥20.12–78.25 |
| `doubao-seedance-2-0-260128` | 입력 비디오 없음 | ¥2.31 | ¥4.97 | ¥12.39 |
| `doubao-seedance-2-0-260128` | 입력 비디오 2\~15초 | ¥2.53–5.62 | ¥5.44–12.10 | ¥13.56–30.13 |
| `doubao-seedance-2-0-fast-260128` | 입력 비디오 없음 | ¥1.86 | ¥4.00 | 지원 안 함 |
| `doubao-seedance-2-0-fast-260128` | 입력 비디오 2\~15초 | ¥1.99–4.42 | ¥4.28–9.50 | 지원 안 함 |
| `doubao-seedance-2-0-mini-260615` | 입력 비디오 없음 | ¥1.16 | ¥2.48 | 지원 안 함 |
| `doubao-seedance-2-0-mini-260615` | 입력 비디오 2\~15초 | ¥1.27–2.81 | ¥2.72–6.05 | 지원 안 함 |

각 범위는 2\~4초짜리 입력 비디오부터 허용되는 가장 긴 입력 비디오까지의 값입니다. 가장 긴 입력은 Seedance 2.5가 30초, 2.0 모델이 15초입니다.

### 작업 하나에 호출 로그가 두 줄인 이유

작업을 만들 때는 최종 토큰 사용량을 알 수 없습니다. LaoZhang API는 먼저 추정치를 선차감하고, 작업이 끝나면 최종 `usage.completion_tokens`로 차액을 정산합니다. 두 줄은 한 작업에 속하며 별개의 요청도, 두 번의 전액 과금도 아닙니다.

| 로그 | 기록 시점 | 표시 내용 |
| - | - | - |
| 선차감 | 작업 생성 시 | 비스트리밍으로 표시되며 키, `SeeDance2` 그룹, 그룹 배율, 요청 IP가 나타납니다 |
| 정산 | 작업 완료 시 | 스트리밍으로 표시되며 completion 토큰 수와 추가 청구 또는 환불 금액이 나타납니다 |

**작업 비용 = 선차감 금액 + 정산 금액**입니다. 예를 들어 선차감이 약 \$0.90이고 정산이 약 \$3.58이면 한 작업의 비용은 약 \$4.48입니다. 실제 사용량이 추정치보다 적으면 정산 줄에서 차액을 환불합니다.

정산 줄의 '스트리밍' 표시는 정산 과정에서 붙는 것입니다. 클라이언트가 스트리밍 API를 썼다는 뜻도, 다른 키의 요청이라는 뜻도 아닙니다. 정산 줄에는 보통 키, 그룹, IP가 다시 나오지 않으므로 요청 출처는 선차감 줄로 확인하세요.

작업 하나를 대조하는 순서입니다.

1. [호출 로그](https://api.laozhang.ai/log)에서 `doubao-seedance` 또는 사용한 전체 모델 ID로 검색합니다.
2. 선차감 줄에서 키, 그룹, 요청 IP를 확인합니다.
3. 정산 줄에서 최종 completion 토큰 수를 읽습니다.
4. 비동기 작업 페이지에서 작업 ID와 생성·완료 시각을 맞춰 보고, 두 줄을 비디오 한 편으로 계산합니다.

작업이 실패하거나 만료되었는데 예상하지 못한 청구가 남아 있다면 호출 로그의 해당 줄을 확인한 뒤, 작업 ID와 함께 [고객 지원](mailto:hi@laozhang.ai)에 문의하세요.

## 작업 처리 흐름

**1. 작업 생성**

`model`에 모델 ID를, `content` 배열에 프롬프트와 미디어를 넣어 `POST /contents/generations/tasks`를 호출합니다. 반환된 `id`를 저장하세요.

**2. 작업 조회**

`status`가 최종 상태가 될 때까지 `GET /contents/generations/tasks/{id}`를 호출합니다.

**3. 비디오 다운로드**

작업이 성공하면 `content.video_url`에서 내려받거나 `/v1/videos/{id}/content`를 호출합니다.

`return_last_frame`을 `true`로 설정했다면 `content.last_frame_url`도 읽습니다.

## 작업 상태

| 상태 | 의미 | 할 일 |
| - | - | - |
| `queued` | 작업이 시작을 기다리는 중 | 계속 조회 |
| `running` | 비디오 생성 중 | 계속 조회 |
| `succeeded` | 작업 완료, 결과는 `content`에 있음 | 비디오 다운로드 |
| `completed` | 작업 완료(LaoZhang 호환 작업 객체), `succeeded`와 같음 | 비디오 다운로드 |
| `failed` | 작업 실패, 상세는 `error`에 있음 | 조회를 멈추고 요청을 수정 |
| `expired` | 작업 만료 | 조회를 멈추고 새 작업 생성 |

모든 응답에 같은 규칙을 적용하세요.

* `status`가 `queued` 또는 `running`이면 계속 조회합니다.
* `succeeded`와 `completed`는 성공으로 처리합니다.
* 그 밖의 값은 최종 상태로 봅니다. 최종 실패라면 조회를 멈추고 응답 전체를 로그에 남기세요.

조회 엔드포인트는 `status`와 `content.video_url`이 있는 Ark 형식의 작업 객체를 반환합니다. 응답 구조가 다르면 다음을 확인하세요.

* LaoZhang 호환 작업 객체는 URL을 최상위 `result_url` 또는 `data.content.video_url`에 담을 수 있습니다.
* URL을 찾을 수 없으면 `/v1/videos/{id}/content`로 내려받으세요.

## 모델

| 모델 ID | 버전 | 용도 |
| - | - | - |
| `doubao-seedance-2-0-260128` | Seedance 2.0 standard | 표준 품질, 첫·마지막 프레임, 비디오 편집, 더 안정적인 출력 |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 fast | 빠른 생성. 텍스트 투 비디오, 이미지·비디오·오디오 참조, 비디오 확장, 트랙 보완(track completion). 1080p 없음 |
| `doubao-seedance-2-0-mini-260615` | Seedance 2.0 mini | 가장 저렴하며 기능은 standard와 거의 같음. 720p까지, 4\~15초 |
| `doubao-seedance-2-5-260628` | Seedance 2.5 | 4\~30초. 참조 이미지 최대 30개, 비디오 10개, 오디오 10개이며 오디오만 참조로 쓸 수 있음. 1080p까지. 출력은 MP4 또는 MOV |

모델 ID는 2026년 9월 24일 기준 LaoZhang API 공개 가격표를 따랐고, mini와 2.5의 기능은 Volcengine [Seedance 2.5 가이드](https://docs.volcengine.com/docs/ark/seedance-2-5?lang=zh)(중국어)의 모델 비교표를 따랐습니다. Seedance 2.5는 첫 프레임, 첫·마지막 프레임, 비디오 편집, 비디오 확장 작업에 `ratio`와 `duration` 제약이 추가되므로, 작업을 2.5로 바꾸기 전에 해당 가이드를 읽어 보세요.

`model`에는 모델 ID만 보내세요. 콘솔 엔드포인트 ID(`ep-...`)를 보내거나 `(2.0-audio-video)` 같은 라벨을 이름 뒤에 붙이지 마세요. 릴레이는 모델 ID 그대로 채널을 찾습니다.

## 환경 설정

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_API_KEY"   # LaoZhang API 키로 바꾸세요
```

예제를 실행하기 전에 다음을 준비하세요.

* 셸 예제는 `curl`과 `jq`를 사용합니다. jq는 `brew install jq` 또는 `sudo apt-get install jq`로 설치합니다.
* Python 예제에는 `pip install requests`가 필요합니다.
* 각 생성 예제는 응답을 `create.json`에 저장하며, 아래 작업 조회 단계에서 이 파일을 읽습니다.

## 텍스트로 비디오 만들기

모든 생성 요청은 `POST /seedance/api/v3/contents/generations/tasks`로 보냅니다. 헤더, 요청 파라미터, `content` 항목은 예제 뒤의 작업 생성 절에서 설명합니다.

```bash theme={null}
curl -sS -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {
        "type": "text",
        "text": "1인칭 시점의 사과 과일차 광고, 4초, 빠른 편집, 사과차를 만드는 과정과 완성된 모습을 보여 주는 신선하고 밝은 스타일"
      }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "watermark": false,
    "generate_audio": false,
    "return_last_frame": true
  }' | tee create.json
```

생성 응답에는 보통 작업 ID만 들어 있습니다.

```json theme={null}
{
  "id": "cgt-example-task-id"
}
```

## 첫 프레임과 마지막 프레임

```bash theme={null}
curl -sS -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "첫 프레임은 이미지 1, 마지막 프레임은 이미지 2입니다. 빨간 사과 제품 클로즈업에서 완성된 사과 과일차 컵으로 이어지는 매끄러운 광고 전환 장면을 만들어 주세요. 제품 외형은 일관되게 유지하고 사람은 등장시키지 마세요."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
        },
        "role": "last_frame"
      }
    ],
    "ratio": "adaptive",
    "duration": 4,
    "resolution": "720p",
    "watermark": false,
    "generate_audio": false,
    "return_last_frame": true
  }' | tee create.json
```

## 이미지·비디오·오디오 참조

```bash theme={null}
curl -sS -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-raw '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {
        "type": "text",
        "text": "사과 제품의 디테일은 이미지 1을, 1인칭 카메라 움직임은 비디오 1을, 배경 음악은 오디오 1을 참고하세요. 재료를 빠르게 컷 편집으로 보여 준 뒤 완성된 컵을 클로즈업하는 간결한 사과 과일차 광고를 만들어 주세요."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
        },
        "role": "reference_audio"
      }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "watermark": false,
    "generate_audio": true
  }' | tee create.json
```

실제 인물의 신원이나 얼굴을 일관되게 유지하려면 일반 얼굴 이미지만으로는 부족합니다. 먼저 [실존 인물·가상 인물 에셋 절차](https://docs.laozhang.ai/ko/api-capabilities/seedance2-human-virtual-workflow.md)를 완료하세요. 에셋이 `Active` 상태가 되면 그 `asset://...` URI를 `reference_image`로 보냅니다.

## 작업 조회

```http theme={null}
GET https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/{id}
```

`create.json`에서 작업 ID를 읽어 작업 상태를 확인합니다.

```bash theme={null}
TASK_ID=$(jq -r '.id' create.json)

curl -sS "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Accept: application/json" | tee task.json | jq -r '.status'
```

`status`가 `queued` 또는 `running`인 동안 10\~15초마다 조회하세요. 성공 응답은 다음과 같습니다.

```json theme={null}
{
  "id": "cgt-example-task-id",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "succeeded",
  "ratio": "16:9",
  "duration": 4,
  "resolution": "720p",
  "content": {
    "video_url": "https://example.com/generated-video.mp4",
    "last_frame_url": "https://example.com/last-frame.jpeg"
  },
  "usage": {
    "completion_tokens": 87300,
    "total_tokens": 87300
  }
}
```

결과 URL은 임시 서명 URL이며 보통 24시간 유효합니다. 운영 환경에서는 작업이 성공하는 즉시 내려받아 자체 저장소에 복사하세요.

## 결과 다운로드

```http theme={null}
GET https://api.laozhang.ai/v1/videos/{id}/content
```

작업 상세에 비디오 URL이 있으면 바로 내려받습니다. 서명 URL이라 `Authorization` 헤더가 필요 없습니다.

```bash theme={null}
VIDEO_URL=$(jq -r '.content.video_url // .result_url // .data.content.video_url // empty' task.json)
curl -L -o seedance-output.mp4 "$VIDEO_URL"
```

파싱할 수 있는 URL이 없거나 파일만 필요하다면 호환 엔드포인트를 쓰세요. 이 엔드포인트는 `/seedance/api/v3`가 아니라 `https://api.laozhang.ai/v1` 아래에 있습니다. 작업이 성공한 뒤 서버에 저장된 결과를 찾아 MP4를 반환하거나 해당 위치로 리디렉션합니다.

```bash theme={null}
curl -L "https://api.laozhang.ai/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -o seedance-output.mp4
```

## Python 예제

텍스트 투 비디오 작업을 만들고 최대 20분 동안 상태를 조회한 뒤 MP4를 저장하는 예제입니다. 의존성은 `pip install requests`로 설치합니다.

```python theme={null}
import os
import time

import requests

API_KEY = os.environ["LAOZHANG_API_KEY"]
BASE_URL = "https://api.laozhang.ai/seedance/api/v3"
DOWNLOAD_URL = "https://api.laozhang.ai/v1/videos/{task_id}/content"
PENDING = {"queued", "running"}
SUCCESS = {"succeeded", "completed"}
POLL_INTERVAL = 15   # 상태 조회 간격(초)
TIMEOUT = 20 * 60    # 20분이 지나면 대기를 중단합니다. 긴 비디오는 값을 늘리세요

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
    "Accept-Encoding": "identity",
}


def task_status(task):
    status = task.get("status")
    if status is None and isinstance(task.get("data"), dict):
        status = task["data"].get("status")
    return str(status or "").lower()


def find_video_url(task):
    data = task.get("data") if isinstance(task.get("data"), dict) else {}
    for content in (task.get("content"), data.get("content")):
        if isinstance(content, dict) and content.get("video_url"):
            return content["video_url"]
    return task.get("result_url")


payload = {
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
        {
            "type": "text",
            "text": "1인칭 시점의 사과 과일차 광고, 4초, 빠른 편집, 신선하고 밝은 스타일",
        }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "watermark": False,
    "generate_audio": False,
    "return_last_frame": True,
}

create_resp = requests.post(
    f"{BASE_URL}/contents/generations/tasks",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
create_resp.raise_for_status()
task_id = create_resp.json()["id"]
print("작업 ID:", task_id)

deadline = time.monotonic() + TIMEOUT
while True:
    query_resp = requests.get(
        f"{BASE_URL}/contents/generations/tasks/{task_id}",
        headers=HEADERS,
        timeout=60,
    )
    query_resp.raise_for_status()
    task = query_resp.json()
    status = task_status(task)
    print("상태:", status)

    if status in SUCCESS:
        break
    if status not in PENDING:
        raise RuntimeError(f"작업 {task_id}이(가) {status!r} 상태로 끝났습니다: {task}")
    if time.monotonic() > deadline:
        raise TimeoutError(f"작업 {task_id}이(가) {TIMEOUT // 60}분 안에 끝나지 않았습니다")
    time.sleep(POLL_INTERVAL)

video_url = find_video_url(task)
if video_url:
    # 서명 URL이므로 Authorization 헤더 없이 내려받습니다.
    video_resp = requests.get(video_url, timeout=300)
else:
    video_resp = requests.get(
        DOWNLOAD_URL.format(task_id=task_id),
        headers={"Authorization": f"Bearer {API_KEY}", "Accept": "video/mp4,*/*"},
        timeout=300,
    )
video_resp.raise_for_status()
with open(f"{task_id}.mp4", "wb") as output:
    output.write(video_resp.content)
print(f"{task_id}.mp4 저장 완료")
```

## 작업 생성

```http theme={null}
POST https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks
```

### 헤더

| 헤더 | 필수 | 값 |
| - | - | - |
| `Authorization` | 필수 | `Bearer $LAOZHANG_API_KEY` (`SeeDance2` 그룹의 키) |
| `Content-Type` | 필수 | `application/json` |
| `Accept` | 권장 | `application/json` |
| `Accept-Encoding` | 선택(디버깅용) | `identity`. 일부 클라이언트가 압축 응답을 제대로 해석하지 못할 때 씁니다 |

### 요청 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 필수 | 모델 ID. 예: `doubao-seedance-2-0-fast-260128` |
| `content` | array | 필수 | 멀티모달 콘텐츠 배열. 텍스트 프롬프트도 여기에 넣습니다 |
| `ratio` | string | 선택 | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive` |
| `duration` | integer | 선택 | 2.0 모델은 4~~15초, Seedance 2.5는 4~~30초. `-1`이면 모델이 길이를 정함(2.5 기본값) |
| `frames` | integer | 선택 | 출력 길이(프레임 수). Seedance 1.0 전용이며 Seedance 2.0과 2.5에는 `duration`을 쓰세요 |
| `resolution` | string | 선택 | `480p`, `720p`, `1080p`. fast와 mini는 `720p`까지. 네 모델 모두 `4k`는 지원하지 않으며, 보내면 즉시 400이 반환되고 과금되지 않습니다 |
| `watermark` | boolean | 선택 | 워터마크 추가 여부 |
| `generate_audio` | boolean | 선택 | 비디오에 소리를 포함할지 여부. 기본값은 `true` |
| `return_last_frame` | boolean | 선택 | 마지막 프레임 URL을 반환할지 여부 |

### `content` 항목

| 필드 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `type` | string | 필수 | `text`, `image_url`, `video_url`, `audio_url` |
| `text` | string | `type`이 `text`일 때 | 프롬프트 텍스트 |
| `image_url.url` | string | `type`이 `image_url`일 때 | 이미지 URL |
| `video_url.url` | string | `type`이 `video_url`일 때 | 비디오 URL |
| `audio_url.url` | string | `type`이 `audio_url`일 때 | 오디오 URL |
| `role` | string | 미디어에 권장 | 에셋의 용도 |

자주 쓰는 `role` 값입니다.

| `role` | 용도 |
| - | - |
| `first_frame` | 첫 프레임 이미지 |
| `last_frame` | 마지막 프레임 이미지 |
| `reference_image` | 이미지 참조 |
| `reference_video` | 비디오 참조 |
| `reference_audio` | 오디오 참조 |

Seedance 2.0 모델(standard, fast, mini)에서는 오디오만 참조로 쓸 수 없습니다. `audio_url`을 보낼 때는 같은 요청에 이미지나 비디오를 하나 이상 넣으세요. Seedance 2.5는 오디오만 참조로 보내도 됩니다.

## 자주 묻는 질문

### Seedance 작업 하나에 두 번 과금되었나요?

아닙니다. 두 줄은 한 작업의 선차감과 정산이며, 두 줄의 합계가 작업 비용입니다. 대조하는 방법은 위의 작업 하나에 호출 로그가 두 줄인 이유 절을 참고하세요.

### 5초 비디오는 얼마인가요?

2026년 10월 14일 기준 가격으로, 입력 비디오 없는 16:9 작업에서 출력 5초(121프레임)의 비용입니다.

* Seedance 2.5: 720p 약 \$1.31, 1080p 약 \$3.23
* Seedance 2.0 standard: 720p 약 \$0.86, 1080p 약 \$2.14
* fast: 720p 약 \$0.69, mini: 720p 약 \$0.43

비용은 길이에 비례하므로 10초면 대략 두 배입니다. 실제 토큰 수는 작업 결과의 `usage.completion_tokens`이며, 계산 방법은 위의 작업 비용 예상하기 절에 있습니다.

### Seedance 2.5는 2.0보다 얼마나 비싼가요?

같은 해상도에서 토큰당 약 1.5배입니다. 입력 비디오가 없을 때 720p는 100만 토큰당 \$12.00 대 \$7.88, 1080p는 \$13.20 대 \$8.74입니다. 5초 720p 비디오는 2.5가 약 \$1.31, 2.0이 약 \$0.86입니다. 2.5에서 추가되는 기능(15초 초과 클립, 더 많은 참조 에셋, 오디오 단독 참조, MOV 출력)은 아래 모델 선택 질문에 정리했습니다.

### 요청이 거부되거나 작업이 실패해도 과금되나요?

과금되지 않습니다. 작업 ID 없이 4xx 파라미터 오류로 바로 거부된 생성 요청은 과금되지 않습니다. 작업이 만들어진 뒤 `failed` 또는 `expired`로 끝나면 정산 시점에 선차감액이 환불됩니다.

실제 청구 내역은 [호출 로그](https://api.laozhang.ai/log)에서 확인하세요. 실패하거나 만료된 작업에 청구가 남아 있다면 작업 ID와 함께 [고객 지원](mailto:hi@laozhang.ai)에 문의하세요.

### `SeeDance2` 그룹 배율은 할인인가요?

아닙니다. 0.1714 배율은 Volcengine의 위안화 목록 가격을 USD 잔액 기준으로 환산하는 값이며 결과적으로 목록 가격의 약 1.2배가 됩니다. 추가분은 세금, 환전과 국경 간 정산, 플랫폼 운영, 기술 지원 비용에 쓰입니다. 환산 방법과 토큰당 가격은 위의 과금과 가격 절을 참고하세요.

### 1080p는 왜 더 비싼가요? 세로 비율도 더 드나요?

1080p가 비싼 이유는 두 가지이고, 종횡비는 거의 영향이 없습니다. 토큰당 단가가 더 높고(위의 과금과 가격 절 참고), 출력 픽셀 수가 늘어 토큰 사용량도 커집니다. 5초 기준 720p는 약 108,900토큰, 1080p는 약 245,025토큰을 쓰므로 1080p 비디오는 훨씬 비쌉니다.

같은 해상도라면 어떤 종횡비든 픽셀 수가 거의 같습니다. 720p에서 16:9는 1280×720, 9:16은 720×1280입니다. 가로, 세로, 정사각형 비디오의 비용은 거의 같습니다. 공식은 위의 작업 비용 예상하기 절에 있습니다.

### 어떤 경로와 `model` 값을 보내야 하나요?

`/seedance/api/v3/contents/generations/tasks`로 요청을 보내세요. 접두사에서 `/api`를 빼면(`/seedance/v3/...`) JSON 대신 사이트의 HTML이 반환되며, 작업 ID 없는 목록 엔드포인트도 마찬가지입니다.

`model`에는 `doubao-seedance-2-0-260128`처럼 모델 ID만 보내세요. `ep-...` 엔드포인트 ID를 쓰거나 ID 뒤에 라벨을 붙이지 마세요.

### 2.0 standard, fast, mini, 2.5 중 무엇을 써야 하나요?

필요한 기능으로 고르세요.

* **1080p:** 2.0 standard 또는 2.5. fast와 mini는 720p까지입니다.
* **15초 초과, 참조 이미지 9개 초과, 오디오 단독 참조, MOV 출력:** 2.5. 2.0 모델은 이미지 9개, 비디오 3개, 오디오 3개까지 받습니다.
* **최저 비용:** mini가 가장 저렴하고, fast는 mini와 standard 사이입니다. 2.0 계열에서는 standard 품질이 가장 높습니다.

네 모델은 같은 엔드포인트와 `SeeDance2` 그룹을 씁니다. 가격은 위의 과금과 가격 절에서, 기능은 모델 절에서 비교하세요.

### 비디오에 소리가 들어가는 이유는 무엇이고, 어떻게 끄나요?

Seedance 2.0과 2.5는 `generate_audio` 기본값이 `true`라서, 프롬프트와 화면에 맞는 음성, 효과음, 배경 음악이 모노로 추가됩니다.

소리 없는 비디오가 필요하면 `"generate_audio": false`를 보내세요. 대사가 필요하면 대사를 큰따옴표로 감싸는 것이 도움이 됩니다.

### 최종 비디오 URL은 어디에 있고 얼마나 유효한가요?

Ark 형식의 작업 상세에서는 `content.video_url`이며 24시간 유효합니다. LaoZhang 호환 작업 객체는 최상위 `result_url` 또는 `data.content.video_url`로 반환할 수 있습니다. 파일만 필요하면 `/v1/videos/{id}/content`를 호출하세요.

Volcengine은 비디오 URL을 24시간 유지하며, Seedance 2.5 비디오의 URL은 최대 100번까지 내려받을 수 있습니다. 작업이 성공하면 바로 내려받아 직접 저장하고, 사용자에게는 자체 URL을 제공하세요.

### 오디오만 참조로 쓸 수 있나요?

Seedance 2.5에서만 가능합니다. Seedance 2.0 모델(standard, fast, mini)에서는 오디오와 함께 이미지나 비디오를 하나 이상 보내야 합니다.

## 관련 문서

* [Seedance 실존 인물·가상 인물 에셋 API](https://docs.laozhang.ai/ko/api-capabilities/seedance2-human-virtual-workflow.md)
* [Wan 2.7 비디오 생성 API](https://docs.laozhang.ai/ko/api-capabilities/wan-video-generation.md)
* [Sora 2 API 종료: Wan 또는 Seedance로 이전](https://docs.laozhang.ai/ko/api-capabilities/sora2/official-forward.md)
* [모델 및 가격](https://docs.laozhang.ai/ko/models.md)
* [호출 로그 확인 방법](https://docs.laozhang.ai/en/faq/call-logs.md)
* [Volcengine Ark 모델 가격](https://www.volcengine.com/docs/82379/1544106?lang=zh)(중국어)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.