> ## 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

> 通过老张API调用 Seedance 2.0 与 2.5 生成视频：创建与查询任务、下载结果，了解 SeeDance2 分组美元单价和两条消费日志的对账方法。

用老张API调用 Seedance 2.0 与 2.5 生成视频：创建火山方舟兼容的异步任务，轮询状态后下载 MP4。令牌必须使用 `SeeDance2` 分组，费用按 token 计算。

| 项目 | 内容 |
| - | - |
| 模型 | `doubao-seedance-2-5-260628`（2.5）、`doubao-seedance-2-0-260128`（2.0 标准版）、`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` 直接取回 MP4 |
| 令牌分组 | `SeeDance2`，配置见[创建令牌](#创建令牌) |
| 计费 | 按 token 计费；分组倍率 0.18 把火山方舟人民币价格换算为美元，名义价格约为官方价的 1.26 倍。美元单价和单个视频估算见[计费与价格](#计费与价格) |
| 消费日志 | 每个任务产生预扣和结算两条日志，两条金额相加才是这个任务的费用；对账方法见[计费与价格](#计费与价格) |
| 结果有效期 | 结果链接是临时签名地址，通常 24 小时内有效，任务成功后请尽快下载并转存 |

<Warning>
  不要把火山方舟官方路径 `/api/v3/contents/generations/tasks` 直接拼到 `https://api.laozhang.ai` 后面，请求路径必须带 `/seedance` 前缀。
</Warning>

## 创建令牌

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

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

Seedance 模型只开放在 `SeeDance2` 分组，请求必须使用这个分组的令牌；`default`、`Wan` 等其他分组的令牌无法调用，会返回无可用渠道等错误。

## 计费与价格

Seedance 按 token 计费。2026 年 9 月 24 日公开价格配置中，`SeeDance2` 分组的倍率为 0.18，各模型的基础单价与火山方舟官方人民币单价数字相同，所以：

* 老张API美元单价 = 官方人民币单价 × 0.18；
* 按 1:7 固定汇率折算，0.18 × 7 = 1.26，名义价格约为火山方舟官方价的 1.26 倍。

这个倍率是人民币计价与美元余额之间的换算，不是折扣；调用日志里的金额已经换算过，不要再乘一次 0.18。

输入不含视频时，480p、720p、1080p 三档同价，每 1M tokens 的单价如下：

| 模型 ID | 火山方舟官方刊例价 | 老张API | 720p、5 秒约 | 1080p、5 秒约 |
| - | -: | -: | -: | -: |
| `doubao-seedance-2-5-260628` | ¥70 | \$12.60 | \$1.37 | \$3.09 |
| `doubao-seedance-2-0-260128` | ¥46 | \$8.28 | \$0.90 | \$2.03 |
| `doubao-seedance-2-0-fast-260128` | ¥37 | \$6.66 | \$0.73 | 不支持 |
| `doubao-seedance-2-0-mini-260615` | ¥23 | \$4.14 | \$0.45 | 不支持 |

官方刊例价是 480p、720p 不含视频的单价。「5 秒约」按 16:9、输出 5 秒、输入不含视频估算，按实际输出 121 帧计，720p 约 108,900 tokens，1080p 约 245,025 tokens。

实际 tokens 以任务返回的 `usage.completion_tokens` 为准，每个任务的最终费用以两条消费日志的合计金额为准。各模型单价也可在[控制台模型价格](https://api.laozhang.ai/account/pricing)查看，[模型与价格总表](/models)列出了分组与倍率。

### 按规格估算费用

火山方舟官方的费用估算公式：

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

token 单价按输出分辨率和输入是否含视频分档，时长也直接影响用量：

* 火山方舟官方的 1080p 单价高于 480p、720p（Seedance 2.5 为 ¥77，Seedance 2.0 为 ¥51，每 1M tokens）；老张API在输入不含视频时三档同价，按上表单价计算。fast 与 mini 最高支持 720p。
* 输入包含视频（`video_url`）时按更低一档的单价计费：Seedance 2.5 为每 1M tokens \$7.56，Seedance 2.0 输出 1080p 时为 \$5.58。但输入视频的时长也计入 token 用量，同样输出 5 秒，总价通常更高。
* 官方还为输入包含视频的任务设置了最低 token 用量，估算值低于最低用量时按最低用量计费。
* 输出越长，token 用量越多。Seedance 2.5 的 `duration` 默认为 `-1`，由模型在 4–30 秒内自选时长；需要控制成本时，请显式传入 `duration`。

下表是[火山方舟模型价格](https://www.volcengine.com/docs/82379/1544106?lang=zh)中的官方示例（人民币，16:9、输出 5 秒），可用来比较不同规格和输入条件的相对成本，老张API的美元单价以上文为准：

| 模型 | 输入条件 | 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 秒的输入视频，高值对应最长的输入视频（2.5 为 30 秒，2.0 系列为 15 秒）。

### 为什么一次任务会出现两条消费日志？

Seedance 视频生成是异步任务。创建任务时，系统还不知道最终视频会消耗多少 tokens，无法一次完成准确结算。因此系统先按预计用量预扣，任务结束后再按实际 `usage.completion_tokens` 补扣或退回差额。

一次任务会显示两条日志，但它们不是两次独立调用，也不是对同一个视频重复收取两次完整费用：

| 日志记录 | 出现时间 | 含义 | 日志中可见的信息 |
| - | - | - | - |
| 预扣费 | 创建任务时 | 按预计用量先扣除一部分费用 | 标记为“非流式”，显示调用令牌、`SeeDance2` 分组、`0.18x` 倍率和来源 IP |
| 实际补扣或退回 | 任务完成时 | 根据最终 `usage.completion_tokens` 重新结算，多退少补 | 标记为“流式”，显示补全 tokens；通常不重复显示令牌、分组和 IP |

第二条“流式”日志只是系统生成的结算记录，不代表客户端调用了流式视频接口，也不代表另一个 API Key 发起了新请求。它不显示令牌、分组或 IP 属于正常现象，请求来源请查看第一条预扣日志。

**最终费用 = 预扣日志金额 + 完成结算日志金额。**

例如，第一条预扣约 \$0.90，第二条补扣约 \$3.58，这一次任务的最终费用约为 \$4.48，而不是两次独立的视频消费。如果实际用量低于预估，第二条记录也可能是退回差额。

对账时建议：

1. 在[调用日志](https://api.laozhang.ai/log)中搜索 `doubao-seedance` 或所用的完整模型 ID。
2. 用预扣记录确认调用令牌、分组和来源 IP。
3. 用完成结算记录查看实际补全 tokens。
4. 在异步任务页按任务 ID、提交时间和完成时间核对视频结果，不要把两条日志当成两个视频。

任务失败或过期后，如果调用日志中仍有扣费，请带上任务 ID 联系支持团队（[hi@laozhang.ai](mailto:hi@laozhang.ai)）。

**任务详情里的倍率字段**：任务详情可能把 0.18 倍率显示为 `topup_convert_ratio: 0.18`，同时显示 `group_ratio: 1`。这两个字段用途不同，`group_ratio: 1` 不表示漏算了 0.18 倍率。

预扣日志会显示 `SeeDance2` 和 `0.18x`；完成结算日志不重复显示分组，也不代表按全价结算。

## 接口与任务流程

```text theme={null}
POST https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks
GET  https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/{id}
GET  https://api.laozhang.ai/v1/videos/{id}/content
```

第一条创建任务，第二条查询任务状态与结果，第三条是兼容下载接口（它使用 `/v1`，不带 `/seedance/api/v3` 前缀）。不带任务 ID 的 `GET /contents/generations/tasks` 列表查询在当前中转路径下会返回站点 HTML，不能作为业务接口使用。

<Steps>
  <Step title="创建任务">
    调用 `POST /contents/generations/tasks`，在 `model` 中传入纯模型 ID，并通过 `content` 数组传入提示词和可选素材。保存响应中的任务 `id`。
  </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` | 老张API兼容任务对象中的成功终态，等价于 `succeeded` |
| `failed` | 任务失败，查看 `error` |
| `expired` | 任务过期 |

读取查询响应顶层的 `status`，按以下规则处理：

* `queued`、`running`：继续轮询；
* `succeeded`、`completed`：任务成功，按以下顺序获取视频：
  1. `content.video_url`
  2. `data.content.video_url`
  3. 顶层 `result_url`
  4. 兼容下载接口 `/v1/videos/{id}/content`
* `failed`、`expired`：停止轮询，查看 `error`；
* 出现上表以外的值：停止轮询，保存完整响应并联系支持团队。

## 模型

| 模型 ID | 说明 | 适用场景 |
| - | - | - |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 fast | 快速生成；文生视频；图片、视频、音频及多模态参考；视频延长、轨道补齐 |
| `doubao-seedance-2-0-260128` | Seedance 2.0 标准版 | 标准质量、首尾帧、视频编辑、对稳定性要求更高的任务 |
| `doubao-seedance-2-0-mini-260615` | Seedance 2.0 mini | 追求更低成本；功能与标准版基本一致；最高 720p，4–15 秒 |
| `doubao-seedance-2-5-260628` | Seedance 2.5 | 4–30 秒；最多 30 张参考图、10 个参考视频、10 段参考音频，音频可单独作参考；最高 1080p；可输出 mp4 或 mov |

mini 与 2.5 的能力来自[火山方舟 Seedance 2.5 教程](https://docs.volcengine.com/docs/ark/seedance-2-5?lang=zh)中的模型能力对比。Seedance 2.5 的首帧/首尾帧、视频编辑和视频延长任务对 `ratio`、`duration` 有额外限制，改用 2.5 前请先阅读该教程。

`model` 只填纯模型 ID，老张API按纯模型 ID 匹配通道。不要传入控制台接入点 ID（`ep-...`），也不要在模型名后附加中文备注。

## 创建任务

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

### 请求头

| Header | 必填 | 说明 |
| - | - | - |
| `Authorization` | 是 | `Bearer $LAOZHANG_API_KEY`，使用 `SeeDance2` 分组的老张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` 秒，Seedance 2.5 为 `4`–`30` 秒；`-1` 表示由模型自选时长（2.5 默认 `-1`） |
| `frames` | integer | 否 | 按帧数控制时长，仅 Seedance 1.0 系列支持；Seedance 2.0 与 2.5 请用 `duration` |
| `resolution` | string | 否 | `480p`、`720p`、`1080p`，常用 `720p`；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` | 多模态参考音频 |

<Warning>
  Seedance 2.0 系列（标准版、fast、mini）不能只传音频参考：使用 `audio_url` 时，需要同时提供至少一个图片或视频素材。Seedance 2.5 可以单独使用音频参考。
</Warning>

### 真人与虚拟人素材

包含真人身份或需要人物一致性的任务，不能用普通真人人脸图片代替专用素材流程。

请先按[真人与虚拟人素材 API](/api-capabilities/seedance2-human-virtual-workflow)完成真人认证或创建虚拟人素材；素材状态变为 `Active` 后，把返回的 `asset://...` URI 作为 `reference_image` 提交。素材 API 托管在 `yingtu.ai`，同样使用老张API密钥鉴权。

## 文生视频

先设置密钥。下面的示例用 `jq` 提取任务 ID 和视频地址（macOS 可用 `brew install jq` 安装）：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

```bash theme={null}
curl -s -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LAOZHANG_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
  }' | tee seedance-create.json
```

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

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

取出任务 ID，后面的查询和下载都用它：

```bash theme={null}
TASK_ID=$(jq -r '.id // empty' seedance-create.json)
echo "$TASK_ID"
```

如果 `TASK_ID` 为空，查看 `seedance-create.json` 中的错误信息。

下面两个示例同样把响应保存到 `seedance-create.json`，创建后用同一条 `jq` 命令取出 `TASK_ID`。

## 首尾帧

```bash theme={null}
curl -s -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAOZHANG_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
  }' | tee seedance-create.json
```

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

```bash theme={null}
curl -s -X POST "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LAOZHANG_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
  }' | tee seedance-create.json
```

## 查询任务

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

```bash theme={null}
curl -s "https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -o seedance-task.json
jq -r '.status' seedance-task.json
```

定期查询（下面的 Python 示例每 15 秒一次），直到 `status` 进入终态。成功响应示例：

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

## 下载结果

查询结果中有签名地址时，可以直接下载，无需 `Authorization` 请求头：

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

查询响应中没有解析到视频地址，或只需要稳定取回视频文件时，调用兼容下载接口：

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

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

先安装依赖 `pip install requests`，并设置 `LAOZHANG_API_KEY` 环境变量。示例按上面的判定规则轮询，每 15 秒查询一次，总超时 20 分钟，成功后把视频保存为 `<任务 ID>.mp4`。

```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_BASE_URL = "https://api.laozhang.ai/v1"
POLL_INTERVAL = 15  # 秒
TIMEOUT = 20 * 60  # 总超时 20 分钟

PENDING_STATUSES = {"queued", "running"}
SUCCESS_STATUSES = {"succeeded", "completed"}
FAILED_STATUSES = {"failed", "expired"}

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


def task_status(task):
    # 方舟透传对象的状态在顶层；兼容任务对象可能放在 data 里
    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": "第一人称视角果茶广告，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("task 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:", status)

    if status in SUCCESS_STATUSES:
        break
    if status in FAILED_STATUSES:
        raise RuntimeError(f"任务失败（{status}）：{task.get('error')}")
    if status not in PENDING_STATUSES:
        raise RuntimeError(f"未识别的任务状态，请保存响应并联系支持团队：{task}")
    if time.monotonic() >= deadline:
        raise TimeoutError(f"任务 {task_id} 超过 20 分钟仍未完成，可稍后用同一个任务 ID 继续查询")
    time.sleep(POLL_INTERVAL)

video_url = find_video_url(task)
if video_url:
    # 签名地址直接下载，无需 Authorization 头
    video_resp = requests.get(video_url, timeout=300)
else:
    video_resp = requests.get(
        f"{DOWNLOAD_BASE_URL}/videos/{task_id}/content",
        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")
```

## 常见接入问题

<AccordionGroup>
  <Accordion title="一次请求出现两条日志，是扣了两次吗？">
    不是重复扣费：两条日志分别是预扣和完成结算，金额相加才是这个任务的费用，对账方法见[计费与价格](#计费与价格)中的两条消费日志说明。
  </Accordion>

  <Accordion title="任务失败或请求被拒绝会扣费吗？">
    都不计费。创建请求被直接拒绝（例如参数错误返回 4xx、没有拿到任务 ID）时不扣费；任务已创建但最终 `failed` 或 `expired` 时，创建时的预扣金额会在结算时退回。

    实际扣费以[调用日志](https://api.laozhang.ai/log)为准。如果失败或过期的任务仍有扣费，请带上任务 ID 联系支持团队（[hi@laozhang.ai](mailto:hi@laozhang.ai)）。
  </Accordion>

  <Accordion title="SeeDance2 的 0.18 倍率是折扣吗？">
    不是，0.18 是人民币价格换算为美元余额的系数，换算方法和各模型单价见[计费与价格](#计费与价格)。
  </Accordion>

  <Accordion title="三档同价，为何 1080p 更贵？竖屏呢？">
    因为 token 用量随输出像素增加。「三档同价」指输入不含视频时每 1M tokens 的单价相同；同样输出 5 秒，720p 约 108,900 tokens，1080p 约 245,025 tokens，所以 1080p 的单个视频更贵。

    同一分辨率下，各宽高比的像素数基本相同，例如 720p 的 16:9 为 1280×720、9:16 为 720×1280，横屏、竖屏和方形的费用也基本一致。估算公式见[按规格估算费用](#按规格估算费用)。
  </Accordion>

  <Accordion title="请求路径和 model 应该怎么写？">
    路径必须是 `/seedance/api/v3/contents/generations/tasks`，不要去掉官方路径里的 `/api`：写成 `/seedance/v3/...` 会返回站点 HTML 而不是 JSON。也不要调用不带任务 ID 的列表查询，它同样返回 HTML。

    `model` 只填纯模型 ID，例如 `doubao-seedance-2-0-260128`。不要传控制台接入点 ID（`ep-...`），也不要在模型名后附加备注，例如 `doubao-seedance-2-0-260128 (2.0-音画同生)`。
  </Accordion>

  <Accordion title="四个 Seedance 模型怎么选？">
    按需要的能力和成本选：

    * 需要 1080p：用 2.0 标准版或 2.5，fast 和 mini 最高 720p。
    * 需要超过 15 秒、超过 9 张参考图（2.0 系列最多 9 张图片、3 个视频、3 段音频）、只用音频作参考或输出 mov：用 2.5。
    * 成本优先：mini 单价最低，fast 介于 mini 和标准版之间；2.0 系列中追求最高画质用标准版。

    四个模型使用同一个端点和 `SeeDance2` 分组，单价见[计费与价格](#计费与价格)，能力对比见[模型](#模型)。
  </Accordion>

  <Accordion title="为什么生成的视频自带声音？怎么关掉？">
    因为 `generate_audio` 默认为 `true`：Seedance 2.0 与 2.5 会根据提示词和画面自动生成人声、音效和背景音乐，输出为单声道。

    需要无声视频时，在请求体中显式传 `"generate_audio": false`。需要生成对白时，把台词放在双引号里效果更好。
  </Accordion>

  <Accordion title="任务成功后视频地址在哪里？多久失效？">
    方舟透传详情里的视频地址在 `content.video_url`，24 小时内有效。老张API兼容任务对象也可能返回嵌套的 `data.content.video_url` 或顶层 `result_url`；只需要下载文件时，调用兼容下载接口 `/v1/videos/{id}/content`。

    按火山方舟说明，视频地址 24 小时内有效，Seedance 2.5 生成的视频地址最多可下载 100 次。任务成功后请立即下载并转存到自己的存储，不要把签名地址直接发给终端用户。
  </Accordion>

  <Accordion title="音频参考能单独传吗？">
    只有 Seedance 2.5 可以。Seedance 2.0 系列（标准版、fast、mini）要把音频和至少一个图片或视频素材一起传入。
  </Accordion>
</AccordionGroup>

## 相关文档

* [Seedance 真人与虚拟人素材 API](/api-capabilities/seedance2-human-virtual-workflow)
* [Wan 2.7 视频生成 API](/api-capabilities/wan-video-generation)
* [Sora 2 视频 API 已下线：迁移说明](/api-capabilities/sora2/official-forward)
* [模型与价格总表](/models)
* [调用日志](/faq/call-logs)
* [火山方舟模型价格](https://www.volcengine.com/docs/82379/1544106?lang=zh)


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