---
url: https://limapi.com/docs/guide/seedance.md
---
# 视频生成 Seedance

```
POST /api/v1/seedance/videos
Authorization: Bearer sk-xxx
Content-Type: application/json
```

异步视频生成接口：输入一段文字描述即可生成视频（文生视频）；Seedance **2.5 / 2.0 标准档**另支持传入参考图 / 参考视频 / 参考音频做图生视频。任务完成后通过网关代理下载 mp4。

> ⚠️ 参考素材限制：仅 **`doubao-seedance-2-5` 与 `doubao-seedance-2-0`** 支持参考素材；素材 URL **必须是公网可访问的 `https://` 地址，或本站登记后的 `asset://<assetId>`**（不支持 base64、内网 / 本地文件）。传入不合规的 URL、或在 Fast / Mini 上带参考素材，会被网关拒绝（`400`）。参考素材是否加价以供应商报价为准，当前按下方时长档位计收。
>
> 👤 **含人物的素材请先登记为素材**，用 `asset://` 引用，见 [素材登记](#素材登记-asset)。

## 支持模型

模型 ID 用火山官方家族名，**分辨率由请求里的 `resolution` 决定**（不再烧进模型 ID）。

| 模型 ID | 可选分辨率 | 时长（秒） | 单价（元 / 百万 tokens） | 约合（元 / 秒） |
|---------|-----------|-----------|--------------------------|-----------------|
| `doubao-seedance-2-0-fast` | 720p | 4~15 | 37.00 | 0.7992 |
| `doubao-seedance-2-0-mini` | 720p | 4~15 | 23.00 | 0.4968 |
| `doubao-seedance-2-0` | 720p / 1080p / 4k | 4~15 | 46.00 / 51.00 / 26.00 | 0.9936 / 2.748 / 2.8568 |
| `doubao-seedance-2-5` | 480p / 720p / 1080p | 4~30 | 70.00 / 70.00 / 77.00 | 0.6726 / 1.512 / 4.1164 |

> `480p` 与 `720p` 的**每百万 token 单价相同**（上游价目里 480P/720P 就是同一行），480p 省的是每秒 token 数（854×480 的面积约为 1280×720 的 44.5%），不是折扣。

> **时长上限按模型代际区分**：Seedance **2.0 系列最长 15 秒**，Seedance **2.5 系列最长 30 秒**（火山官方规格）。超出上限的请求会被网关直接拒绝（上游不校验时长、纯按秒计费，放行超限会造成按请求秒数多扣而实际交付更短）。
>
> **分辨率只认已开档**：传白名单外的值（如给 `doubao-seedance-2-0-fast` 传 `1080p`）会被拒（`400`）；不传按 `720p` 出片并按 `720p` 计费。

## 素材登记

参考素材可以直接给公网 https 链，也可以先**登记成本站素材**，拿到 `asset://<assetId>` 再引用。登记这一步**不收费**，素材按租户隔离（只能引用自己登记过的素材，别人的 ID 一律按"不存在"处理）。

什么时候必须走登记：素材里含人物面孔时，上游对公网直链会做内容审核，两道都可能拦：

* **入站**（创建任务时就拒）：`400 InputImageSensitiveContentDetected.PrivacyInformation`，任务没有开始，不扣费；
* **成品**（生成完再拒）：`OutputVideoSensitiveContentDetected.PolicyViolation`，状态 `failed`，同样不扣费。

2026-10-14 实测：同一张含人像的图（字节完全相同），公网直链两种形态都被拒且账单零行；登记后用 `asset://` 引用则 `succeeded` 出片。

> ⚖️ 素材须为您**自有或已获授权**的内容。真人本人出镜的授权认证（活体识别）暂未开放接入；每租户每日登记上限 200 条，超出返回 `429`（一条素材登记一次可反复引用，无需重复登记）。

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/seedance/assets` | 登记一条素材，返回 `assetId`，初始状态 `Processing` |
| `GET` | `/api/v1/seedance/assets/{assetId}` | 查单条素材状态，等到 `Active` 才能用 |
| `GET` | `/api/v1/seedance/assets` | 分页列本租户素材（`pageSize` ≤100、`pageNumber` 从 1 起） |
| `DELETE` | `/api/v1/seedance/assets/{assetId}` | 删除素材 |
| `GET` | `/api/v1/seedance/asset-group` | 查本租户的素材组 ID（登记时自动创建，一般用不上） |

登记请求体：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 素材的公网 https 地址（登记时由上游拉取，需要当时可访问） |
| `type` | string | 是 | `image` / `video` / `audio` |
| `name` | string | 可选 | 自定义名称，便于后续检索 |

```json
{
  "assetId": "asset-20261014185412-99q4w",
  "groupId": "group-20261014184513-cfx84",
  "status": "Processing",
  "assetType": "Image"
}
```

> ⏱️ **登记是异步入库**：拿到 `assetId` 时状态还是 `Processing`，实测约 4 秒变 `Active`（失败为 `Failed`）。请按 2~3 秒轮询 `/api/v1/seedance/assets/{assetId}`，见到 `Active` 再去发起视频任务，否则会报素材不可用。

```python
import requests, time

H = {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}

# 1. 登记
aid = requests.post("https://limapi.com/api/v1/seedance/assets", headers=H,
                    json={"url": "https://example.com/person.jpg",
                          "type": "image", "name": "主角形象"}).json()["assetId"]

# 2. 等到 Active
for _ in range(30):
    st = requests.get(f"https://limapi.com/api/v1/seedance/assets/{aid}", headers=H).json()["status"]
    if st == "Active":
        break
    time.sleep(2)

# 3. 用 asset:// 发起图生视频
requests.post("https://limapi.com/api/v1/seedance/videos", headers=H, json={
    "model": "doubao-seedance-2-0", "resolution": "720p", "duration": 4,
    "content": [{"type": "text", "text": "让图片1中的人物转身走向镜头"},
                {"type": "image", "image_url": {"url": f"asset://{aid}"},
                 "role": "reference_image"}]})
```

> 素材删除后 `asset://` 引用即失效；已生成的视频不受影响。

## 创建视频任务

### Request

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | \* | 模型 ID，见上方支持模型列表 |
| `content` | array | 二选一 | 输入内容数组，可含 `text` 提示词项与参考图 / 视频 / 音频项（后者仅 2.5 / 2.0 标准档支持） |
| `prompt` | string | 二选一 | 提示词简写，与 `content` 里的 `text` 项等价（二者都在时以 `prompt` 为准） |
| `resolution` | string | 可选 | 输出分辨率：`480p` / `720p` / `1080p` / `4k`（按模型可选档，默认 `720p`）。**只读顶层字段**，塞在 `metadata` 里不生效 |
| `duration` | integer | 可选 | 视频时长（秒）。**Seedance 2.0 系列 4~15，Seedance 2.5 系列 4~30**，默认 `5`；超限会被拒 |
| `ratio` | string | 可选 | 画面比例：`16:9`（横屏） / `9:16`（竖屏） / `1:1`（方形） / `4:3` / `3:4`，不传则由上游按默认处理 |

> **不要用 `size` 或像素值传分辨率。** 输出分辨率用 `resolution`，画面比例用 `ratio`；例如要 1280×720 就是 `resolution:"720p"` + `ratio:"16:9"`。传 `size` 会被网关忽略。

`content` 数组元素：

| `type` | 字段 | 说明 |
|--------|------|------|
| `text` | `text` | 文字描述（提示词） |
| `image` | `image_url.url` | 参考图，公网 https 或 `asset://<assetId>`；`role` 可选 `reference_image`（默认）/ `first_frame` / `last_frame` |
| `video` | `video_url.url` | 参考视频，公网 https 或 `asset://<assetId>`；`role`＝`reference_video` |
| `audio` | `audio_url.url` | 参考音频，公网 https 或 `asset://<assetId>`；`role`＝`reference_audio` |

> 提示词里用「图片1 / 图片2 / 视频1 / 音频1」按 `content` 中素材出现的顺序引用。

### 请求示例

**文字生成视频：**

```json
{
  "model": "doubao-seedance-2-5",
  "resolution": "1080p",
  "content": [
    {"type": "text", "text": "一只猫在花园里追蝴蝶，阳光明媚，电影级画质"}
  ],
  "duration": 4,
  "ratio": "16:9"
}
```

**参考图生视频（2.5 / 2.0 标准档）：**

```json
{
  "model": "doubao-seedance-2-0",
  "resolution": "720p",
  "content": [
    {"type": "text", "text": "让图片1中的人物转身走向镜头，夕阳逆光，电影感"},
    {"type": "image", "image_url": {"url": "https://example.com/person.jpg"}, "role": "reference_image"}
  ],
  "duration": 5,
  "ratio": "16:9"
}
```

**用 prompt 简写：**

```json
{
  "model": "doubao-seedance-2-0-mini",
  "prompt": "海浪拍打沙滩，夕阳西下",
  "duration": 4
}
```

### 响应

```json
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-5",
  "status": "queued",
  "progress": 0,
  "created_at": 1789977781
}
```

记下返回的 `id`，用于后续查询与下载。

## 查询任务详情

```
GET /api/v1/seedance/videos/{taskId}
Authorization: Bearer sk-xxx
```

**响应示例（生成成功）：**

```json
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "model": "doubao-seedance-2-5",
  "status": "succeeded",
  "created_at": 1789977781,
  "content": {
    "video_url": "https://limapi.com/api/v1/seedance/videos/task_xxxxxxxxxxxxxxxx/content"
  },
  "usage": {
    "total_tokens": 213840,
    "completion_tokens": 213840
  }
}
```

**响应字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 任务 ID |
| `status` | string | 任务状态：`queued` / `running` / `succeeded` / `failed` |
| `content.video_url` | string | 生成成功后的下载地址（网关代理，需带同一个 API Key 访问） |
| `usage.total_tokens` | integer | 总 token 用量（用于计费，按 `时长 × 每秒 token 数` 折算） |

**状态说明：**

| status | 含义 | 说明 |
|--------|------|------|
| `queued` | 排队中 | 任务已创建，等待上游处理 |
| `running` | 生成中 | 视频正在生成 |
| `succeeded` | 已完成 | 生成成功，返回 `content.video_url`，此时按 token 用量扣费 |
| `failed` | 失败 | 生成失败，不扣费 |

> 💡 **建议轮询间隔 5~15 秒**。视频生成通常需要 1~6 分钟（排队 + 出流），超时预算请留足 6 分钟再判定失败。

## 下载视频

```
GET /api/v1/seedance/videos/{taskId}/content
Authorization: Bearer sk-xxx
```

任务 `succeeded` 后，用上一步返回的 `content.video_url`（或直接拼此路径）下载，响应为 `video/mp4` 字节流。

```bash
curl "https://limapi.com/api/v1/seedance/videos/$TASK_ID/content" \
  -H "Authorization: Bearer sk-xxx" \
  --output video.mp4
```

> 上游直链为明文 http 且需鉴权，因此统一由网关代理回源，客户端只需带本站 API Key 即可下载。

## Seedance 模型定价

计费单位为**元 / 百万 tokens**，成本 = `时长（秒）× 每秒 token 数 × 单价 ÷ 1,000,000`。下表同时给出折算后的每秒参考价：

| 模型 ID | 分辨率 | 元 / 百万 tokens | 约合 元 / 秒 |
|---------|--------|------------------|--------------|
| `doubao-seedance-2-0-mini` | 720p | 23.00 | 0.4968 |
| `doubao-seedance-2-0-fast` | 720p | 37.00 | 0.7992 |
| `doubao-seedance-2-0` | 720p | 46.00 | 0.9936 |
| `doubao-seedance-2-0` | 1080p | 51.00 | 2.748 |
| `doubao-seedance-2-0` | 4k | 26.00 | 2.8568 |
| `doubao-seedance-2-5` | 720p | 70.00 | 1.512 |
| `doubao-seedance-2-5` | 1080p | 77.00 | 4.1164 |

> 每秒 token 数按分辨率档不同：720p 为 21,600，1080p 约 5.3 万，4k 约 11 万 —— 所以「4k 单价更低但每秒更贵」。任务成功后按 `usage.total_tokens` 扣费，失败不扣。

## Python 完整示例

```python
import requests, time

API_KEY = "sk-xxx"
BASE_URL = "https://limapi.com/api/v1/seedance"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. 创建视频任务
resp = requests.post(f"{BASE_URL}/videos", headers=HEADERS, json={
    "model": "doubao-seedance-2-5",
    "resolution": "1080p",
    "content": [{"type": "text", "text": "一只猫在花园里追蝴蝶，阳光明媚"}],
    "duration": 4,
    "ratio": "16:9"
})
task_id = resp.json()["id"]
print(f"任务已创建: {task_id}")

# 2. 轮询任务状态
while True:
    result = requests.get(f"{BASE_URL}/videos/{task_id}", headers=HEADERS).json()
    status = result.get("status")
    if status == "succeeded":
        video_url = result["content"]["video_url"]
        print(f"视频已生成: {video_url}")
        # 3. 下载（带同一个 API Key）
        with requests.get(video_url, headers={"Authorization": f"Bearer {API_KEY}"}, stream=True) as r:
            with open("video.mp4", "wb") as f:
                for chunk in r.iter_content(chunk_size=8192):
                    f.write(chunk)
        break
    elif status == "failed":
        print("任务失败，未扣费")
        break
    print(f"状态: {status}，等待中...")
    time.sleep(10)
```