> ## 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 视频生成 API

> 通过 LaoZhang API 调用 Seedance 2.0 与 Seedance 2.0 fast，支持文生视频、图片参考、首尾帧、视频参考、音频参考、多模态参考、视频编辑、视频延长与轨道补齐。

<Info>
  **Base URL:** `https://api.laozhang.ai/seedance/api/v3`

  **接口：**

  1. `POST /contents/generations/tasks`：创建视频生成任务
  2. `GET /contents/generations/tasks/{id}`：查询任务状态与结果
  3. `GET https://api.laozhang.ai/v1/videos/{id}/content`：兼容下载已成功任务的视频文件

  视频生成是异步任务。创建接口通常只返回任务 `id`，需要轮询查询接口；成功后可以从 `content.video_url` 读取签名下载地址，或使用 `/v1/videos/{id}/content` 直接下载视频文件。
</Info>

<Warning>
  **真人面部能力说明**
  当前暂不支持包含真人人脸的输入或生成场景。系统改造完成后会开放对应调用能力；需要此能力的用户可关注
  TG 公告频道 [@laozhang\_ai](https://t.me/laozhang_ai)
  获取通知。上线前的预期接入流程请查看
  [真人与虚拟人流程说明](/api-capabilities/seedance2-human-virtual-workflow)。
</Warning>

## 创建令牌

在 [令牌管理](https://api.laozhang.ai/token) 创建用于 Seedance 2.0 的令牌时，按下面配置：

| 配置项  | 选择                                    |
| ---- | ------------------------------------- |
| 计费模式 | `按量优先`                                |
| 选择分组 | `SeeDance2`                           |
| 建议   | 为 Seedance 2.0 单独创建令牌，便于后续查看调用日志和扣费记录 |

<Warning>
  Seedance 2.0 请求必须使用选择了 `SeeDance2`
  分组的令牌。默认分组或其他视频分组的令牌可能出现无可用渠道、模型不匹配或计费分组不正确的问题。
</Warning>

<Warning>
  不要把官方路径 `/api/v3/contents/generations/tasks` 直接拼到
  `https://api.laozhang.ai` 后面。请使用带 `/seedance/api/v3` 前缀的 Base URL。
</Warning>

<Warning>
  当前中转路径下，`GET /contents/generations/tasks` 不带任务 ID
  的列表查询会返回站点 HTML，不应作为业务接口使用。业务侧请使用创建任务和按任务
  ID 查询两个接口完成闭环。
</Warning>

## 计费与价格

<Info>
  以下为上游官方公开价格口径，用于接入前成本预估。LaoZhang API
  实际扣费以控制台模型价格和调用日志为准；因税率、汇率、支付通道和上游结算差异，站内扣费可能在官方原价基础上上浮
  `0% - 10%`。
</Info>

官方参考：[火山方舟模型价格](https://www.volcengine.com/docs/82379/1544106?lang=zh)。

Seedance 2.0 官方采用 token 计费。费用与输出分辨率、宽高比、输出时长、是否包含输入视频以及任务实际 `usage.completion_tokens` 相关，不是固定的单次价格。官方估算公式：

```text theme={null}
费用 = token 单价 × token 用量
token 用量 ≈ (输入视频时长 + 输出视频时长) × 输出视频宽 × 输出视频高 × 帧率 / 1024
```

### 官方价格示例

以下示例来自官方价格页，规格固定为 `16:9`、输出 `5` 秒视频。

| 模型                                | 输入条件            | 480p 官方示例         | 720p 官方示例          | 1080p 官方示例          |
| --------------------------------- | --------------- | ----------------- | ------------------ | ------------------- |
| `doubao-seedance-2-0-260128`      | 不含输入视频          | `2.31 元/个`        | `4.97 元/个`         | `12.39 元/个`         |
| `doubao-seedance-2-0-fast-260128` | 不含输入视频          | `1.86 元/个`        | `4.00 元/个`         | 不支持                 |
| `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` | 包含 `2-15` 秒输入视频 | `1.99 - 4.42 元/个` | `4.28 - 9.50 元/个`  | 不支持                 |

<Note>
  包含 `video_url`
  输入时，官方会把输入视频处理量和输出视频生成量一起纳入计费。最终费用应以任务查询响应中的
  `usage.completion_tokens`、控制台账单和 LaoZhang API 调用日志为准。
</Note>

## 接口流程

<Steps>
  <Step title="创建任务">
    调用 `POST /contents/generations/tasks`，在 `model` 中传入纯模型 ID，并通过
    `content` 数组传入提示词和可选素材。
  </Step>

  <Step title="轮询状态">
    调用 `GET /contents/generations/tasks/{id}`，检查 `status` 是否进入终态。
  </Step>

  <Step title="下载结果">
    当任务成功后，从 `content.video_url` 下载视频，或调用兼容下载接口
    `/v1/videos/{id}/content` 下载视频文件；如果创建时设置了
    `return_last_frame=true`，还可以读取 `content.last_frame_url`。
  </Step>
</Steps>

状态值：

| 状态          | 说明                                    |
| ----------- | ------------------------------------- |
| `queued`    | 任务排队中                                 |
| `running`   | 任务生成中                                 |
| `succeeded` | 任务成功，结果在 `content` 中                  |
| `completed` | LaoZhang 兼容任务对象中的成功终态，等价于 `succeeded` |
| `failed`    | 任务失败，查看 `error`                       |
| `expired`   | 任务过期                                  |

<Note>
  `GET /contents/generations/tasks/{id}` 的方舟透传结构以 `status=succeeded` 和
  `content.video_url` 为准。LaoZhang 兼容任务对象可能同时出现
  `status=completed`、顶层 `result_url`，以及嵌套的
  `data.content.video_url`。客户端建议兼容这些成功结果。下载阶段建议保留
  `/v1/videos/{id}/content` 作为稳定入口。
</Note>

## 模型

`model` 只填纯模型 ID。不要填写控制台接入点 ID，也不要在模型名后附加中文备注。

| 模型 ID                             | 说明                | 推荐用途                                     |
| --------------------------------- | ----------------- | ---------------------------------------- |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 fast | 快速生成、文生视频、图片参考、视频参考、音频参考、多模态参考、视频延长、轨道补齐 |
| `doubao-seedance-2-0-260128`      | Seedance 2.0 标准版  | 标准质量、首尾帧、视频编辑、对稳定性要求更高的任务                |

<Warning>
  不要在客户端请求中传入 `ep-...` 接入点 ID。LaoZhang 中转按纯模型 ID 匹配通道。
</Warning>

## 创建任务

<ParamField method="POST" path="/contents/generations/tasks">
  创建 Seedance 2.0 视频生成任务。
</ParamField>

### 请求头

| Header            | 必填   | 说明                                                      |
| ----------------- | ---- | ------------------------------------------------------- |
| `Authorization`   | 是    | `Bearer $API_KEY`，使用选择了 `SeeDance2` 分组的 LaoZhang API 令牌 |
| `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 | 否  | Seedance 2.0 支持 `4` 到 `15` 秒，也支持 `-1` 自适应         |
| `frames`            | integer | 否  | 按帧数控制输出，优先级高于 `duration`                          |
| `resolution`        | string  | 否  | 常用 `720p`。Seedance 2.0 fast 不支持 `1080p`           |
| `watermark`         | boolean | 否  | 是否添加水印                                            |
| `generate_audio`    | boolean | 否  | 是否生成或使用音频                                         |
| `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` | 多模态参考音频 |

<Warning>
  音频不能作为唯一参考素材单独传入。使用 `audio_url`
  时，需要同时提供至少一个图片或视频素材。
</Warning>

## 文生视频

```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": "第一人称视角果茶广告，4秒，快节奏剪辑，展示苹果果茶制作与成品，清爽明亮风格"
      }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "watermark": false,
    "generate_audio": false,
    "return_last_frame": true
  }'
```

创建成功时通常只返回任务 ID：

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

## 首尾帧

```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": "首帧为图片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
  }'
```

## 图片、视频、音频参考

```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": "使用图片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
  }'
```

## 查询任务

<ParamField method="GET" path="/contents/generations/tasks/{id}">
  查询视频生成任务状态。
</ParamField>

```bash theme={null}
curl "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/cgt-example-task-id" \
  -H "Authorization: Bearer $API_KEY"
```

成功响应示例：

```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
  }
}
```

<Info>
  结果 URL 是临时签名地址，通常有效期为 24
  小时。生产环境建议任务成功后立即下载，并转存到自己的对象存储。
</Info>

## 下载结果

<ParamField method="GET" path="/v1/videos/{id}/content">
  通过 LaoZhang 兼容下载接口下载已成功任务的视频文件。
</ParamField>

兼容下载接口使用 `https://api.laozhang.ai/v1`，不是 `/seedance/api/v3`。任务成功后，该接口会根据服务端保存的任务结果定位视频文件，并返回或重定向到可下载的 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
```

<Info>
  如果查询详情接口正常返回
  `content.video_url`，可以直接下载该签名地址；如果查询响应体异常、没有解析到
  URL，或只需要稳定拿到视频文件，建议使用 `/v1/videos/{id}/content`。
</Info>

## Python 完整示例

```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": "第一人称视角果茶广告，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"]

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)
```

## 常见接入问题

<AccordionGroup>
  <Accordion title="为什么 /seedance/v3/contents/generations/tasks 返回 HTML？">
    当前路径是 `/seedance/api/v3/contents/generations/tasks`。不要去掉官方路径里的 `/api`。
  </Accordion>

  <Accordion title="模型名后面可以加中文备注吗？">
    不可以。请求里的 `model` 必须是纯模型 ID，例如
    `doubao-seedance-2-0-260128`。不要写成 `doubao-seedance-2-0-260128
          (2.0-音画同生)`。
  </Accordion>

  <Accordion title="可以传 ep 接入点 ID 吗？">
    不建议。LaoZhang 中转按纯模型 ID 匹配通道，请不要传入 `ep-...`。
  </Accordion>

  <Accordion title="任务成功后视频地址在哪里？">
    方舟透传详情里的视频地址通常在 `content.video_url`。LaoZhang
    兼容任务对象也可能返回顶层 `result_url` 或嵌套的
    `data.content.video_url`。

    只需要下载文件时，调用兼容下载接口：

    `/v1/videos/{id}/content`
  </Accordion>

  <Accordion title="音频参考能单独传吗？">
    不能。音频参考需要和至少一个图片或视频素材一起传入，否则请求会被官方接口拒绝。
  </Accordion>
</AccordionGroup>