> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Seedance 2.0 동영상 생성 API 레퍼런스
> 대화형 플레이그라운드를 포함한 Seedance 2.0 동영상 생성 API 레퍼런스입니다. 텍스트-투-비디오, 첫+마지막/첫 프레임, 그리고 멀티모달 reference-to-video를 하나의 비동기 엔드포인트에서 지원하며, 전체 폴링 및 다운로드 코드가 포함되어 있습니다.
오른쪽의 플레이그라운드를 사용합니다: **Authorization**을 `Bearer sk-your-api-key`로 설정하고( Token에는 `SeeDance2` 그룹이 활성화되어 있어야 합니다), `model` / `content`를 입력한 다음 전송합니다. 성공적으로 제출되면 작업 `id`이 반환됩니다. 폴링 및 다운로드 흐름은 아래 코드 샘플에서 다룹니다.
**플레이그라운드의 "no response received" 오류에 관하여**: 이 엔드포인트는 비동기 작업 엔드포인트이며, 브라우저에서 Send를 클릭하면 해당 메시지가 표시될 수 있습니다. 브라우저의 cross-origin 안전 검사가 응답을 차단한 것이지만, **작업은 실제로 성공적으로 제출되었습니다**(아래 조회 엔드포인트 또는 콘솔 로그로 확인하십시오). 또한 플레이그라운드는 작업만 생성할 수 있으며, 동영상을 폴링하거나 다운로드할 수는 없습니다. 전체 create → poll → download 흐름을 실행하려면 아래 **코드 샘플**(cURL / Python / Node.js)을 복사하여 실행하십시오.
이것은 Seedance 2.0의 작업 생성 엔드포인트입니다. 텍스트-투-비디오, first+last/first frame, 그리고 멀티모달 reference-to-video가 모두 이를 공유하며 — `content` 배열이 모드를 선택합니다. 모델 선택, 요금, 해상도/픽셀 표, 그리고 FAQ는 [Seedance 2.0 개요](/ko/api-capabilities/seedance2/overview)를 참조하십시오.
* 경로 접두사는 `/seedance/api/v3`입니다 — **`/api` 세그먼트를 삭제하지 마십시오**, 그리고 `/v1/videos`를 사용하지 마십시오
* Token에는 **`SeeDance2` 그룹**이 활성화되어 있어야 합니다. 그렇지 않으면 "이 모델에 사용할 수 있는 채널이 없습니다"가 표시됩니다
* `generate_audio`의 기본값은 true입니다(출력에 소리가 포함됨) — 무음 동영상을 위해 `false`를 명시적으로 전달하십시오
* Python requests는 `"Accept-Encoding": "identity"` 헤더가 필요합니다 — 이것이 없으면 gzip 디코딩 오류, 잘린 non-JSON 본문(예: 앞의 `{"`가 사라지고 `id":"cgt-xxx"}`만 수신됨), 또는 간헐적인 400 오류가 발생할 수 있습니다
* 성공 상태 코드는 `succeeded`입니다(`completed` 아님); 동영상 URL은 `content.video_url`에 있으며 **24시간 후 만료됩니다**
## 코드 예제
```bash cURL (텍스트-투-비디오) theme={null}
curl -X POST "https://api.apiyi.com/seedance/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{"type": "text", "text": "Drone shot flying over an autumn valley, golden forests and a winding river, cinematic"}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": false
}'
# Returns {"id":"cgt-2026xxxx-xxxxx"} — poll the query endpoint with this id
```
```python Python (전체 흐름: 생성 → 폴링 → 다운로드) theme={null}
import time
import requests
BASE = "https://api.apiyi.com/seedance/api/v3/contents/generations/tasks"
HEADERS = {
"Authorization": "Bearer sk-your-api-key",
"Content-Type": "application/json",
# Required: the gateway's gzip header does not match the actual encoding.
# Without this you may get gzip decode errors, a truncated non-JSON body
# (e.g. id":"cgt-xxx"} with the leading {" lost), or intermittent 400s
"Accept-Encoding": "identity",
}
# 1. Create the task
body = {
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{"type": "text", "text": "Waves crashing on rocks at sunset, slow motion, serene mood"}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
# "generate_audio": False, # defaults to True; uncomment for silent video
# "seed": 12345, # fix the seed for similar, reproducible results
}
task_id = requests.post(BASE, json=body, headers=HEADERS, timeout=60).json()["id"]
print("task_id:", task_id)
# 2. Poll until a terminal state (succeeded / failed / expired)
while True:
time.sleep(20)
task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
status = task.get("status")
print("status:", status)
if status in ("succeeded", "failed", "expired"):
break
# 3. Download the video (the URL expires in 24 h — copy it out immediately)
if status == "succeeded":
video_url = task["content"]["video_url"] # note: under content, not top-level
print("tokens:", task["usage"]["completion_tokens"])
with requests.get(video_url, stream=True, timeout=300) as r:
r.raise_for_status()
with open(f"{task_id}.mp4", "wb") as f:
for chunk in r.iter_content(chunk_size=1 << 20):
f.write(chunk)
print(f"saved {task_id}.mp4")
else:
print("task did not succeed:", task.get("error"))
```
```python Python (첫/마지막 프레임 / 참조 모드) theme={null}
# First + last frame: 2 images, roles required; mutually exclusive with reference mode
body_first_last = {
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "Smooth transition from the first frame to the last, slow camera move"},
{"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"},
"role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"},
"role": "last_frame"},
],
"resolution": "720p",
"ratio": "adaptive", # match the first frame's ratio to avoid cropping
"duration": 5,
}
# Multi-modal reference: 0-9 reference images + 0-3 reference videos + 0-3 reference audios
# (at least 1 image or 1 video); can create / edit / extend videos
body_reference = {
"model": "doubao-seedance-2-0-260128",
"content": [
{"type": "text", "text": "Using the reference character and style, the character walks down a rainy street at night"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.png"},
"role": "reference_image"},
# {"type": "video_url", "video_url": {"url": "..."}, "role": "reference_video"},
# {"type": "audio_url", "audio_url": {"url": "..."}, "role": "reference_audio"},
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
}
# Images also accept Base64 (data:image/png;base64,xxx) and platform asset IDs (asset://xxx)
```
```javascript Node.js (fetch) theme={null}
const BASE = "https://api.apiyi.com/seedance/api/v3/contents/generations/tasks";
const HEADERS = {
"Authorization": "Bearer sk-your-api-key",
"Content-Type": "application/json",
};
// 1. Create the task
const { id } = await fetch(BASE, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
model: "doubao-seedance-2-0-fast-260128",
content: [{ type: "text", text: "A mountain lake reflecting the starry sky, time-lapse" }],
resolution: "720p",
ratio: "9:16", // portrait costs the same as landscape
duration: 5,
}),
}).then(r => r.json());
console.log("task_id:", id);
// 2. Poll until a terminal state
let task;
do {
await new Promise(r => setTimeout(r, 20000));
task = await fetch(`${BASE}/${id}`, { headers: HEADERS }).then(r => r.json());
console.log("status:", task.status);
} while (!["succeeded", "failed", "expired"].includes(task.status));
// 3. The video link (expires in 24 h — re-host immediately)
if (task.status === "succeeded") console.log(task.content.video_url);
```
```bash cURL (작업 폴링) theme={null}
curl "https://api.apiyi.com/seedance/api/v3/contents/generations/tasks/cgt-2026xxxx-xxxxx" \
-H "Authorization: Bearer sk-your-api-key"
```
## 매개변수 참조
| 매개변수 | Type | Required | Default | 비고 |
| ------------------------- | ------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string | ✓ | — | `doubao-seedance-2-0-260128` (표준, 1080p) / `doubao-seedance-2-0-fast-260128` (고속, 최대 720p) / `doubao-seedance-2-0-mini-260615` (Mini/Lite, 최대 720p, 표준 가격의 약 절반). 일반 ID이며 `ep-` 접두사는 없습니다 |
| `content` | array | ✓ | — | 입력 배열 — 아래의 ‘생성 모드’를 참조하십시오 |
| `resolution` | string | | `720p` | `480p` / `720p` / `1080p` (1080p는 표준 전용이며, 고속과 mini는 720p로 제한됩니다) |
| `ratio` | string | | `adaptive` | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`; 한 티어의 모든 비율은 동일한 비용입니다 |
| `duration` | int | | `5` | 정수 초 4-15; `-1`면 모델이 선택하며(실제 출력 기준으로 과금됩니다) |
| `generate_audio` | bool | | `true` | 동기화된 오디오(voice/SFX/music, mono) |
| `watermark` | bool | | `false` | AI가 생성한 워터마크를 추가합니다 |
| `seed` | int | | `-1` | \[-1, 2^32-1]; 같은 seed를 사용하면 유사한(동일하지는 않은) 결과를 얻습니다 |
| `return_last_frame` | bool | | `false` | 클립 연결용 워터마크가 없는 마지막 프레임 png를 반환합니다 |
| `execution_expires_after` | int | | `172800` | 초 단위의 작업 만료 임계값입니다. 범위는 \[3600, 259200]입니다 |
Seedance 2.0은 `frames`, `camera_fixed`, 또는 `service_tier`(온라인 추론 전용)을 지원하지 않습니다. 이들은 Seedance 1.x 매개변수이며 무시되거나 거부됩니다.
### 생성 모드 (콘텐츠 조합)
| Mode | content items | role values |
| --------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| 텍스트-투-비디오 | 1 `text` | — |
| 첫 프레임 + 마지막 프레임 | 선택적 텍스트 + 2 `image_url` | 필수: `first_frame` / `last_frame` |
| 첫 프레임 | 선택적 텍스트 + 1 `image_url` | `first_frame` 또는 생략 가능 |
| 멀티모달 참조-투-비디오 | text + 0-9 `image_url` (+ 선택적 0-3 `video_url` / 0-3 `audio_url`, 최소 1개의 image 또는 1개의 video 필요) | `reference_image` / `reference_video` / `reference_audio` |
세 가지 이미지 모드는 **상호 배타적**입니다. 이미지는 공개 URL, Base64 (`data:image/png;base64,...`), 그리고 에셋 ID (`asset://...`)를 지원합니다. 실제 인간 얼굴이 포함된 입력은 거부됩니다. 오디오는 최소 하나의 이미지 또는 video와 함께 전송해야 합니다. 엔드투엔드 에셋 참조 코드(ingest → `asset://` → generate → download)는 [에셋 참조 가이드](/ko/api-capabilities/seedance2/asset-reference)를 참조하십시오.
## 응답 형식
생성은 작업 ID만 반환합니다(**동영상은 아님**):
```json theme={null}
{ "id": "cgt-20260606160057-6bbjd" }
```
`GET /seedance/api/v3/contents/generations/tasks/{id}`를 폴링하십시오. 성공한 작업은 다음과 같습니다(저희 테스트의 실제 샘플입니다):
```json theme={null}
{
"id": "cgt-20260606160057-6bbjd",
"model": "doubao-seedance-2-0-fast-260128",
"status": "succeeded",
"content": {
"video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/....mp4?X-Tos-Expires=86400&..."
},
"usage": { "completion_tokens": 108900, "total_tokens": 108900 },
"created_at": 1780732857,
"updated_at": 1780732991,
"seed": 97151,
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"framespersecond": 24,
"generate_audio": true,
"draft": false
}
```
* 동영상 URL은 최상위가 아니라 \*\*`content.video_url`\*\*에 있습니다. 서명된 링크이며 **24시간 후 만료됩니다** — 즉시 다운로드하십시오
* 상태 머신: `queued → running → succeeded / failed / expired`; 성공은 **`succeeded`**
* 링크는 일반 GET으로 다운로드하십시오 — 서명된 URL에는 **`Authorization` 헤더를 보내지 마십시오**
`usage.completion_tokens`는 과금된 token 수이며 `tokens ≈ duration × width × height × 24 / 1024`를 따릅니다(저희 테스트에서는 0.1% 이내입니다). `duration: -1` 또는 `ratio: adaptive`를 사용하면 실제 길이와 비율이 응답의 `duration` / `ratio` 필드에 보고됩니다.
## OpenAPI
````yaml api-reference/seedance2-video-openapi-en.yaml POST /seedance/api/v3/contents/generations/tasks
openapi: 3.1.0
info:
title: Seedance 2.0 Video Generation API
description: >
ByteDance Seedance 2.0 video generation (official Volcengine Mainland China
resource).
Capabilities:
- Text-to-video / image-to-video (first+last frame, first frame) /
multi-modal reference-to-video (0-9 reference images + 0-3 reference videos
+ 0-3 reference audios, at least 1 image or 1 video)
- Resolutions 480p / 720p / 1080p (fast model caps at 720p), 6 aspect ratios
plus adaptive; all ratios in the same tier share the same pixel area and
price
- Duration 4-15 s (or -1 for model-chosen length), fixed 24 fps,
synchronized audio ON by default (generate_audio defaults to true)
- Async task flow: create returns a task id, poll GET
/seedance/api/v3/contents/generations/tasks/{id} until succeeded, then
download from content.video_url (expires in ~24 hours)
Authentication: Bearer Token (the Token must have the SeeDance2 group
enabled and use the Pay-as-you-go Priority billing model).
Get your key from the APIYI console → Token management.
version: 1.0.0
servers:
- url: https://api.apiyi.com
description: Primary endpoint
- url: https://vip.apiyi.com
description: Backup endpoint
security:
- bearerAuth: []
paths:
/seedance/api/v3/contents/generations/tasks:
post:
tags:
- Video Generation
summary: Create a Seedance 2.0 video generation task
description: >
Async endpoint: returns a task `id` immediately — **not the video
itself**.
- Required: `model` + `content` (text only, text+images,
text+images+video+audio, etc.)
- The three image modes are mutually exclusive: first+last frame (2
images, role required) / first frame (1 image) / multi-modal
reference-to-video (0-9 images + 0-3 videos + 0-3 audios, at least 1
image or 1 video, image role = reference_image)
- Inputs containing real human faces are rejected; audio must be sent
together with at least one image or video
- `frames` / `camera_fixed` are NOT supported (Seedance 1.x only)
- Billing is pre-charged on submit and settled on completion; rejected
requests are not billed
After creation, poll `GET
/seedance/api/v3/contents/generations/tasks/{id}`.
Status flow: `queued → running → succeeded / failed / expired`.
On success, download the mp4 from `content.video_url` (expires in ~24
hours).
See the "Seedance 2.0 Overview" doc for details.
operationId: createSeedance2VideoTaskEn
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Seedance2CreateTaskRequest'
example:
model: doubao-seedance-2-0-fast-260128
content:
- type: text
text: >-
Drone shot flying over an autumn valley, golden forests and
a winding river, cinematic
resolution: 720p
ratio: '16:9'
duration: 5
generate_audio: false
responses:
'200':
description: Task created. Returns the task ID for polling
content:
application/json:
schema:
$ref: '#/components/schemas/Seedance2TaskCreated'
example:
id: cgt-20260606160057-6bbjd
'400':
description: >-
InvalidParameter — e.g. 1080p with the fast model, duration outside
4-15, or an unsupported ratio. The error message names the offending
parameter; not billed
'401':
description: Unauthorized - invalid API key
'403':
description: Content moderation rejection (real human faces, policy violations)
'429':
description: Rate limited or insufficient quota
'500':
description: Internal server error
security:
- bearerAuth: []
components:
schemas:
Seedance2CreateTaskRequest:
type: object
required:
- model
- content
properties:
model:
type: string
description: >-
Model ID (plain ID, no ep- prefix). Standard supports 1080p; fast
caps at 720p but generates faster — both bill at the same rate on
APIYI
enum:
- doubao-seedance-2-0-260128
- doubao-seedance-2-0-fast-260128
example: doubao-seedance-2-0-fast-260128
content:
type: array
description: >-
Input array. Text-to-video: a single text item. Image-to-video: add
image_url items (role: first_frame / last_frame). Multi-modal
reference-to-video: 0-9 image_url items (role: reference_image) plus
optional 0-3 video_url / 0-3 audio_url (at least 1 image or 1 video;
can create / edit / extend videos). The three image modes are
mutually exclusive
items:
type: object
properties:
type:
type: string
description: Content type
enum:
- text
- image_url
- video_url
- audio_url
example: text
text:
type: string
description: >-
Prompt (required when type=text). Up to ~1000 English words;
put spoken lines in double quotes to improve generated
voice-over
example: Waves crashing on rocks at sunset, slow motion, serene mood
image_url:
type: object
description: >-
Image object (required when type=image_url). Accepts public
URL, Base64 (data:image/png;base64,...), or asset ID
(asset://...). Formats jpeg/png/webp/bmp/tiff/gif/heic/heif;
aspect ratio (0.4, 2.5); sides (300, 6000) px; under 30 MB
each. Real human faces are not allowed
properties:
url:
type: string
description: Image URL / Base64 / asset:// ID
example: https://example.com/first.jpg
video_url:
type: object
description: >-
Reference video object (required when type=video_url);
multi-modal reference mode only
properties:
url:
type: string
description: Video URL
audio_url:
type: object
description: >-
Reference audio object (required when type=audio_url).
wav/mp3, 2-15 s per clip, up to 3 clips and 15 s total; must
accompany at least one image or video
properties:
url:
type: string
description: Audio URL
role:
type: string
description: >-
Media role. Required for first+last frame
(first_frame/last_frame); optional for a single first frame;
reference media use reference_*
enum:
- first_frame
- last_frame
- reference_image
- reference_video
- reference_audio
resolution:
type: string
description: >-
Resolution tier (defines pixel area — every ratio in a tier costs
the same). 1080p is not available on the fast model
enum:
- 480p
- 720p
- 1080p
default: 720p
ratio:
type: string
description: >-
Aspect ratio. adaptive auto-fits the input (recommended for
image-to-video to avoid cropping); the actual ratio is returned in
the task's ratio field
enum:
- '16:9'
- '4:3'
- '1:1'
- '3:4'
- '9:16'
- '21:9'
- adaptive
default: adaptive
duration:
type: integer
description: >-
Video length in whole seconds, 4-15; or -1 to let the model choose
(billed by actual output). Cost scales linearly with duration
default: 5
example: 5
generate_audio:
type: boolean
description: >-
Generate synchronized audio (voice, SFX, background music; mono).
Note it DEFAULTS TO TRUE — pass false explicitly for silent video
default: true
watermark:
type: boolean
description: Add an AI-generated watermark in the bottom-right corner
default: false
seed:
type: integer
description: >-
Random seed, [-1, 2^32-1]. The same seed produces similar (not
identical) results; -1 means random
default: -1
return_last_frame:
type: boolean
description: >-
Return the last frame as a watermark-free png (same dimensions as
the video) — chain it as the first frame of the next task to produce
continuous multi-clip videos
default: false
execution_expires_after:
type: integer
description: >-
Task expiry threshold in seconds; tasks exceeding it are marked
expired. Range [3600, 259200]
default: 172800
Seedance2TaskCreated:
type: object
description: >-
Creation response. Poll GET
/seedance/api/v3/contents/generations/tasks/{id}; on success the video
URL is at content.video_url (expires in ~24 h) and billed tokens at
usage.completion_tokens
properties:
id:
type: string
description: Video generation task ID (kept for 7 days)
example: cgt-20260606160057-6bbjd
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key from the APIYI console (Token must have the SeeDance2 group
enabled)
````