> ## 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 Video Generation API
> Use LaoZhang API to call Seedance 2.0 and Seedance 2.0 fast for text-to-video, image references, first/last frames, video references, audio references, multimodal references, video editing, video extension, and track completion.
**Base URL:** `https://api.laozhang.ai/seedance/api/v3`
**Endpoints:**
1. `POST /contents/generations/tasks`: create a video generation task
2. `GET /contents/generations/tasks/{id}`: query task status and result
3. `GET https://api.laozhang.ai/v1/videos/{id}/content`: compatibility endpoint for downloading a completed video
Video generation is asynchronous. The create endpoint may return only the task `id`; poll the query endpoint until the task succeeds. You can download from the signed `content.video_url`, or use `/v1/videos/{id}/content` to download the final video file.
**Real-person face support** Inputs or generation workflows involving
real-person faces are not supported yet. This capability will be enabled after
the required system changes are complete. Users who need it can follow the TG
announcement channel [@laozhang\_ai](https://t.me/laozhang_ai) for updates. See
[Real-Person And Virtual Human
Workflow](/en/api-capabilities/seedance2-human-virtual-workflow) for the expected
pre-launch integration flow.
## Token Setup
When creating a token for Seedance 2.0 in [Token management](https://api.laozhang.ai/token), use:
| Setting | Value |
| -------------- | ----------------------------------------------------------------------- |
| Billing mode | `Volume priority` / pay-as-you-go |
| Group | `SeeDance2` |
| Recommendation | Create a dedicated Seedance 2.0 token for easier log and billing review |
Seedance 2.0 requests must use a token assigned to the `SeeDance2` group.
Tokens in the default group or other video groups may produce no-channel,
model mismatch, or billing-group errors.
Do not directly append the official path `/api/v3/contents/generations/tasks`
to `https://api.laozhang.ai`. Use the Base URL with the `/seedance/api/v3`
prefix.
Under the current relay path, `GET /contents/generations/tasks` without a task
ID returns the site HTML instead of API JSON. Do not use the list endpoint in
client integrations. Use create task plus query by task ID.
## Billing And Pricing
The table below uses the official upstream public pricing as a cost-estimation
baseline. LaoZhang API billing is determined by the console model price and
call logs; because of tax, FX, payment-channel, and upstream settlement costs,
the LaoZhang API charge may be `0% - 10%` above the official upstream list
price.
Official reference: [Volcengine Ark model pricing](https://www.volcengine.com/docs/82379/1544106?lang=zh).
Seedance 2.0 official billing is token-based. Cost depends on output resolution, aspect ratio, output duration, whether the request includes input video, and the final `usage.completion_tokens` returned by the task. It is not a fixed per-request price. Official estimation formula:
```text theme={null}
Cost = token unit price x token usage
token usage ~= (input video duration + output video duration) x output width x output height x frame rate / 1024
```
### Official Pricing Examples
The examples below are from the official pricing page and assume `16:9` output with a `5` second generated video.
| Model | Input condition | Official 480p example | Official 720p example | Official 1080p example |
| --------------------------------- | -------------------------------------- | ---------------------- | ----------------------- | ------------------------ |
| `doubao-seedance-2-0-260128` | No input video | `2.31 RMB/task` | `4.97 RMB/task` | `12.39 RMB/task` |
| `doubao-seedance-2-0-fast-260128` | No input video | `1.86 RMB/task` | `4.00 RMB/task` | Not supported |
| `doubao-seedance-2-0-260128` | Includes `2-15` seconds of input video | `2.53 - 5.62 RMB/task` | `5.44 - 12.10 RMB/task` | `13.56 - 30.13 RMB/task` |
| `doubao-seedance-2-0-fast-260128` | Includes `2-15` seconds of input video | `1.99 - 4.42 RMB/task` | `4.28 - 9.50 RMB/task` | Not supported |
When the request includes `video_url`, official billing includes both
input-video processing and output-video generation. Reconcile final cost using
the task `usage.completion_tokens`, upstream billing records, and LaoZhang API
call logs.
## API Flow
Call `POST /contents/generations/tasks`, put the plain model ID in `model`,
and provide the prompt plus optional assets in the `content` array.
Call `GET /contents/generations/tasks/{id}` until `status` reaches a
terminal state.
After the task succeeds, download the video from `content.video_url`, or
call the compatibility download endpoint `/v1/videos/{id}/content` to
download the video file. If `return_last_frame=true` was set, read
`content.last_frame_url` as well.
Status values:
| Status | Meaning |
| ----------- | ------------------------------------------------------------------------------------------ |
| `queued` | The task is queued |
| `running` | The task is generating |
| `succeeded` | The task succeeded and result data is in `content` |
| `completed` | Success terminal state used by LaoZhang-compatible task objects; equivalent to `succeeded` |
| `failed` | The task failed; check `error` |
| `expired` | The task expired |
The Ark-style detail response from `GET /contents/generations/tasks/{id}` uses
`status=succeeded` and `content.video_url`. A LaoZhang-compatible task object
may also expose `status=completed`, top-level `result_url`, and nested
`data.content.video_url`. Client code should tolerate these success shapes and
keep `/v1/videos/{id}/content` as a stable download entry point.
## Models
`model` must be a plain model ID. Do not use console endpoint IDs, and do not append human-readable labels to the model name.
| Model ID | Description | Recommended use |
| --------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 fast | Fast generation, text-to-video, image reference, video reference, audio reference, multimodal reference, video extension, track completion |
| `doubao-seedance-2-0-260128` | Seedance 2.0 standard | Standard quality, first/last frames, video editing, and workflows that need more stable output |
Do not pass an `ep-...` endpoint ID in client requests. The LaoZhang relay
matches channels by plain model ID.
## Create Task
Create a Seedance 2.0 video generation task.
### Headers
| Header | Required | Description |
| ----------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `Authorization` | Yes | `Bearer $API_KEY`, using a LaoZhang API token assigned to the `SeeDance2` group |
| `Content-Type` | Yes | `application/json` |
| `Accept` | Recommended | `application/json` |
| `Accept-Encoding` | Recommended for debugging | `identity`, which avoids compression decoding noise in some clients |
### Request Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `model` | string | Yes | Plain model ID, for example `doubao-seedance-2-0-fast-260128` |
| `content` | array | Yes | Multimodal content array; text prompts also go here |
| `ratio` | string | No | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, or `adaptive` |
| `duration` | integer | No | Seedance 2.0 supports `4` to `15` seconds, or `-1` for adaptive duration |
| `frames` | integer | No | Control output by frame count; takes priority over `duration` |
| `resolution` | string | No | Common value: `720p`. Seedance 2.0 fast does not support `1080p` |
| `watermark` | boolean | No | Whether to add a watermark |
| `generate_audio` | boolean | No | Whether to generate or use audio |
| `return_last_frame` | boolean | No | Whether to return the final frame image URL |
### `content` Items
| Field | Type | Required | Description |
| --------------- | ------ | ------------------------------ | ------------------------------------------------ |
| `type` | string | Yes | `text`, `image_url`, `video_url`, or `audio_url` |
| `text` | string | Required when `type=text` | Prompt text |
| `image_url.url` | string | Required when `type=image_url` | Image URL |
| `video_url.url` | string | Required when `type=video_url` | Video URL |
| `audio_url.url` | string | Required when `type=audio_url` | Audio URL |
| `role` | string | Recommended for assets | Asset purpose |
Common `role` values:
| role | Purpose |
| ----------------- | -------------------------- |
| `first_frame` | First-frame image |
| `last_frame` | Last-frame image |
| `reference_image` | Multimodal image reference |
| `reference_video` | Multimodal video reference |
| `reference_audio` | Multimodal audio reference |
Audio cannot be the only reference asset. When using `audio_url`, include at
least one image or video asset in the same request.
## Text-to-Video
```bash theme={null}
curl -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer $API_KEY" \
--data-raw '{
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "First-person apple fruit tea ad, 4 seconds, fast-paced edit, show apple tea preparation and finished product, fresh bright style"
}
],
"ratio": "16:9",
"duration": 4,
"resolution": "720p",
"watermark": false,
"generate_audio": false,
"return_last_frame": true
}'
```
The create response usually contains only the task ID:
```json theme={null}
{
"id": "cgt-example-task-id"
}
```
## First and Last Frame
```bash theme={null}
curl -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
--data-raw '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "The first frame is image 1 and the final frame is image 2. Create a smooth commercial transition from a red apple product close-up to a finished apple fruit tea cup. Keep product appearance consistent and avoid people."
},
{
"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
}'
```
## Image, Video, and Audio References
```bash theme={null}
curl -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
--data-raw '{
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "Use image 1 for the apple product details, video 1 for first-person camera motion, and audio 1 as the background music. Generate a concise apple fruit tea commercial with quick ingredient cuts and a clean finished cup close-up."
},
{
"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
}'
```
## Query Task
Query the status of a video generation task.
```bash theme={null}
curl "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/cgt-example-task-id" \
-H "Authorization: Bearer $API_KEY"
```
Successful response example:
```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
}
}
```
Result URLs are temporary signed URLs, usually valid for 24 hours. In
production, download successful results immediately and copy them to your own
object storage.
## Download Result
Download the video file for a completed task through the LaoZhang
compatibility endpoint.
This compatibility endpoint uses `https://api.laozhang.ai/v1`, not `/seedance/api/v3`. After the task succeeds, it resolves the stored task result server-side and returns or redirects to a downloadable MP4.
```bash theme={null}
curl -L "https://api.laozhang.ai/v1/videos/cgt-example-task-id/content" \
-H "Authorization: Bearer $API_KEY" \
--output seedance-output.mp4
```
If the task detail response contains `content.video_url`, you can download
that signed URL directly. If the detail body is abnormal, no URL can be
parsed, or you only need the video file, use `/v1/videos/{id}/content`.
## Full Python Example
```python theme={null}
import os
import time
import requests
API_KEY = os.environ["API_KEY"]
BASE_URL = "https://api.laozhang.ai/seedance/api/v3"
DOWNLOAD_BASE_URL = "https://api.laozhang.ai/v1"
SUCCESS_STATUSES = {"succeeded", "completed", "success"}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
"Accept-Encoding": "identity",
}
def find_video_url(data):
if isinstance(data, dict):
for key in ("video_url", "videoUrl", "result_url", "url"):
value = data.get(key)
if isinstance(value, str) and value.startswith("http"):
return value
for value in data.values():
found = find_video_url(value)
if found:
return found
if isinstance(data, list):
for item in data:
found = find_video_url(item)
if found:
return found
return None
def task_status(data):
status = data.get("status")
if isinstance(status, str):
return status.lower()
nested = data.get("data")
if isinstance(nested, dict):
return task_status(nested)
return "unknown"
payload = {
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "First-person apple fruit tea ad, 4 seconds, fast-paced edit, fresh bright style",
}
],
"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"]
while True:
query_resp = requests.get(
f"{BASE_URL}/contents/generations/tasks/{task_id}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Accept": "application/json",
"Accept-Encoding": "identity",
},
timeout=60,
)
query_resp.raise_for_status()
task = query_resp.json()
status = task_status(task)
if status in SUCCESS_STATUSES:
video_url = find_video_url(task)
if video_url:
video_resp = requests.get(video_url, timeout=180)
else:
video_resp = requests.get(
f"{DOWNLOAD_BASE_URL}/videos/{task_id}/content",
headers={"Authorization": f"Bearer {API_KEY}", "Accept": "video/mp4,*/*"},
allow_redirects=True,
timeout=180,
)
video_resp.raise_for_status()
with open(f"{task_id}.mp4", "wb") as output:
output.write(video_resp.content)
break
if status in {"failed", "expired"}:
raise RuntimeError(task)
time.sleep(15)
```
## Common Integration Questions
The current path is `/seedance/api/v3/contents/generations/tasks`. Do not remove `/api` from the official path.
No. The request `model` must be the plain model ID, such as
`doubao-seedance-2-0-260128`. Do not send `doubao-seedance-2-0-260128
(2.0-audio-video)`.
Not recommended. The LaoZhang relay matches channels by plain model ID, so do
not pass `ep-...`.
In the Ark-style detail response, the final video URL is usually
`content.video_url`. LaoZhang-compatible task objects may also return
top-level `result_url` or nested `data.content.video_url`.
For download-only clients, call the compatibility download endpoint:
`/v1/videos/{id}/content`
No. Audio references must be sent with at least one image or video asset, otherwise the official API rejects the request.