> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heihuzi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 视频：创建任务

> 用 Seedance 2.0、2.0 Fast、2.0 mini、2.5 异步生成视频，支持文生视频、首帧、首尾帧、参考图和参考视频。

`POST https://code.heihuzi.ai/api/v3/contents/generations/tasks` 创建一个 Seedance 视频生成任务，请求和响应的格式与火山方舟「创建视频生成任务」接口相同。任务异步执行：创建后返回 `id`，再用[查询任务](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/status.md)获取成片链接；已结束的任务可以[删除](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/delete.md)。

请使用绑定「Seedance 视频」分组的 API Key。其他分组的 Key 调用会返回 403 `PermissionDenied`。

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果，阳光透过树叶，镜头缓慢推近"},
    {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"}, "role": "first_frame"}
  ],
  "resolution": "480p",
  "ratio": "adaptive",
  "duration": 5
}'
```

运行前设置环境变量 `HEIHUZI_API_KEY`。上面的示例用一张图作为视频的第一帧。

## 模型

| 模型 ID | 名称 | 清晰度 | 时长 |
| - | - | - | - |
| `doubao-seedance-2-0-260128` | Seedance 2.0 | `480p`、`720p`、`1080p`、`4k` | 4–15 秒 |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 Fast | `480p`、`720p` | 4–15 秒 |
| `doubao-seedance-2-0-mini-260615` | Seedance 2.0 mini | `480p`、`720p` | 4–15 秒 |
| `doubao-seedance-2-5-260628` | Seedance 2.5 | `480p`、`720p`、`1080p` | 4–30 秒 |

四个模型都支持文生视频、首帧、首尾帧、参考图和参考视频。参考图可以填图片链接，也可以填自己创建的[素材](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/assets.md) ID。参考素材的数量上限：

| 模型 | 参考图 | 参考视频 |
| - | - | - |
| Seedance 2.0、2.0 Fast、2.0 mini | 最多 9 张 | 最多 3 个，合计不超过 15 秒 |
| Seedance 2.5 | 最多 30 张 | 最多 10 个，合计不超过 30 秒 |

## 请求参数

**model** `string` *required*

模型 ID，见上表。其他模型返回 404 `model_not_found`。

**content** `object[]` *required*

输入内容列表，不能为空。首帧、首尾帧、参考素材（参考图、参考视频）是三种互斥的用法，不能混用。

* 文字：`{"type": "text", "text": "画面与动作描述"}`。
* 首帧：`{"type": "image_url", "image_url": {"url": "图片链接"}, "role": "first_frame"}`。
* 首尾帧：再加一张 `"role": "last_frame"` 的图片，视频从首帧过渡到尾帧。
* 参考图：`{"type": "image_url", "image_url": {"url": "图片链接"}, "role": "reference_image"}`，数量上限见上表。
* 参考视频：`{"type": "video_url", "video_url": {"url": "视频链接"}, "role": "reference_video"}`，数量和时长上限见上表，可以和参考图一起用。

**resolution** `string`

清晰度：`480p`、`720p`、`1080p`、`4k`，各模型可选的清晰度见上表。选了模型不支持的清晰度返回 400 `PricingNotConfigured`。清晰度越高，用量越大。

Seedance 2.5 的 `1080p` 和 Seedance 2.0 的 `4k` 成片是 10bit、H.265 编码，少数播放环境可能需要换播放器查看。

**ratio** `string`

画面比例：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`，或 `adaptive`（自动选择）。带首帧图或首尾帧时建议填 `adaptive`，由首帧图决定比例；Seedance 2.5 这时只能填 `adaptive`，填其他比例时任务创建后会失败，冻结的余额全额退回。

**duration** `integer`

时长（秒），整数。Seedance 2.0 系列为 4–15，Seedance 2.5 为 4–30。填 `-1` 时由模型在可选范围内自动决定时长，实际时长见[查询任务](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/status.md)返回的 `duration`，并按实际时长计费。

### 图片

填公网可访问的 https 图片链接，或图片的 Base64 编码（写法见下方「本机图片」）。

| 项目 | 要求 |
| - | - |
| 格式 | jpeg、png、webp、bmp、tiff、gif、heic、heif |
| 大小 | 单张小于 30 MB；请求体不超过 64 MB，大文件请用链接，不要用 Base64 编码 |
| 宽高 | 每条边 300–6000 像素 |
| 宽高比（宽/高） | 0.4–2.5 |
| 数量 | 首帧 1 张；首尾帧 2 张；参考图：Seedance 2.0 系列 1–9 张，Seedance 2.5 为 1–30 张 |

* **含真人人脸的图片会被拒绝**：返回 400 `InputImageSensitiveContentDetected.PrivacyInformation`，冻结的余额全额退回。
* 参考图可以填自己的素材 ID：`{"type": "image_url", "image_url": {"url": "asset://asset-xxx"}, "role": "reference_image"}`。素材要先用[素材管理接口](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/assets.md)创建，并等状态变成 `Active`，写法见下方「更多示例」。
* 参考图数量超出上限时，任务创建后会失败，冻结的余额全额退回。

### 参考视频

填公网可访问的视频链接。不支持 Base64 编码（返回 400 `InvalidParameter`）。

| 项目 | 要求 |
| - | - |
| 格式 | mp4、mov |
| 编码 | 视频 H.264、H.265；音频 AAC、MP3 |
| 数量和时长 | Seedance 2.0 系列：最多 3 个，单个 2–15 秒，合计不超过 15 秒。Seedance 2.5：最多 10 个，单个 2–30 秒，合计不超过 30 秒 |
| 大小 | 单个不超过 200 MB |
| 宽高 | 每条边 300–6000 像素，宽 × 高在 407696–8295044 之间 |
| 宽高比（宽/高） | 0.4–2.5 |
| 帧率 | 24–60 |

* 含真人人脸的视频会被拒绝。
* 在提示词里说明参考视频怎么用，写法见下方「更多示例」。

### 本机图片

把本机图片转换为 Base64 字符串，写成 `data:image/<图片格式>;base64,<Base64 编码>` 填入 `image_url.url`，`<图片格式>` 用小写，如 `data:image/png;base64,...`。首帧、尾帧和参考图都可以这样传。不要填本机文件路径（如 `/Users/...`、`file://...`）。

首帧（命令行，把 `first.png` 换成你的图片）：

```bash theme={null}
IMAGE_BASE64=$(base64 < first.png | tr -d '\n')
cat > request.json <<JSON
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果，阳光透过树叶，镜头缓慢推近"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,${IMAGE_BASE64}"}, "role": "first_frame"}
  ],
  "resolution": "480p",
  "ratio": "adaptive",
  "duration": 5
}
JSON
curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://code.heihuzi.ai/api/v3/contents/generations/tasks \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json
```

参考图（Python，把 `reference.jpg` 换成你的图片）：

```python theme={null}
import base64
import json
import os
import urllib.request

with open("reference.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode()

body = {
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "参考图片1里的苹果饮品，杯子放在果园的木桌上，镜头缓慢环绕"},
        {
            "type": "image_url",
            "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"},
            "role": "reference_image",
        },
    ],
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 5,
}
request = urllib.request.Request(
    "https://code.heihuzi.ai/api/v3/contents/generations/tasks",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["HEIHUZI_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())
```

## 响应

```json theme={null}
{"id":"cgt-20261005170037-c27t7"}
```

`id` 是任务号，用它[查询](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/status.md)和[删除](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/delete.md)任务。

## 更多示例

文生视频（只传文字）：

```json theme={null}
{
  "model": "doubao-seedance-2-5-260628",
  "content": [{"type": "text", "text": "海浪轻轻拍打沙滩，夕阳映在水面上"}],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5
}
```

首尾帧：

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "刚摘下的苹果变成一杯苹果饮品，镜头从果树拉远到果园"},
    {"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"}
  ],
  "resolution": "480p",
  "ratio": "adaptive",
  "duration": 5
}
```

参考视频：

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "参考视频1的运镜和节奏，把场景换成清晨的橘子果园，一只手摘下一个橘子"},
    {"type": "video_url", "video_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"}, "role": "reference_video"}
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5
}
```

参考图用素材 ID（两个素材出现在同一个视频里；素材创建方法见[素材管理](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/assets.md)）：

```json theme={null}
{
  "model": "doubao-seedance-2-0-mini-260615",
  "content": [
    {"type": "text", "text": "图片1的男子和图片2的女剑客并肩走在月下的古镇石板路上，镜头缓慢跟随"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20261101165247-rpf5s"}, "role": "reference_image"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20261101165309-6tc9s"}, "role": "reference_image"}
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}
```

参考图加参考视频：

```json theme={null}
{
  "model": "doubao-seedance-2-0-mini-260615",
  "content": [
    {"type": "text", "text": "参考视频1的运镜和节奏，图片1的柯基小狗在果园里跑向木桌，桌上放着图片2的苹果饮品"},
    {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_ref_2.png"}, "role": "reference_image"},
    {"type": "image_url", "image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.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"}
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5
}
```

## 计费

* 按任务完成后返回的实际用量（`usage.completion_tokens`）计费，不同模型、清晰度单价不同，价格以便利店当前分组配置和用量明细为准。
* 提交时按本次请求可能产生的最大用量冻结余额，生成成功后按实际用量扣费，多冻结的部分退回。
* 带参考视频时，参考视频的时长计入用量，并按含视频输入的单价计费。参考图不增加用量。
* 生成失败、超时、被取消，或请求被拒绝（例如图片含真人），冻结的余额全额退回。

## 限制

* 每个用户同时最多 5 个未完成的视频任务（排队中的也算，Seedance 和 MiniMax 的任务合计），超过返回 429 `TooManyActiveTasks`。
* 暂不支持：任务列表接口、联网搜索（`tools`）。
* 素材 ID 请填在参考图（`"role": "reference_image"`）里，只能用自己账号下创建的素材；视频还没结束时，它引用的素材不能删除。
* 已不支持请求里的 `portrait` 字段，会返回 400 `InvalidParameter`；人物形象请改用素材 ID。

## 错误响应

错误的格式为 `{"error": {"code": "…", "message": "…", "param": "", "type": "…"}}`。

| HTTP | `error.code` | 说明 |
| - | - | - |
| 400 | `InvalidParameter` | 参数不符合要求，例如 `content` 为空、base64 图片的内容不是图片、参考视频用了 base64、时长或画面比例超出该模型支持的范围 |
| 400 | `PricingNotConfigured` | 模型不支持这个清晰度，例如 mini 选 `1080p` |
| 400 | `ToolNotAllowed` | 使用了未开放的 `tools` |
| 400 | `InputImageSensitiveContentDetected.PrivacyInformation` | 图片可能含真人，审核未通过，冻结的余额已退回 |
| 402 | `InsufficientBalance` | 余额不足以冻结本次费用，返回里附 `required_amount` 和 `available_amount` |
| 403 | `PermissionDenied` | Key 没有绑定「Seedance 视频」分组 |
| 404 | `model_not_found` | 模型不在本站支持的列表里 |
| 404 | `ResourceNotFound` | 引用的素材 ID 不存在，或不是你自己的素材，本次未扣费 |
| 429 | `TooManyActiveTasks` | 未完成的任务太多，请等前面的完成后再提交 |
| 502 | `UpstreamOutcomeUnknown` | 提交结果暂时无法确认，**不要立即重复提交**；冻结保留，确认后自动结算或退回 |
| 503 | `UpstreamUnreachable` | 视频服务暂时连不上，本次未扣费，请稍后再试 |
| 503 | `RefundPending` | 视频服务连不上且退款还在核对中，**不要立即重复提交**，冻结的余额会由系统退回 |


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