> ## 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 视频：素材管理

> 按火山方舟素材接口的格式创建、查询、修改、删除素材组和素材，生成视频时用 asset:// 引用自己的人物形象。

素材管理接口和火山方舟「素材」接口的格式相同：请求地址是 `https://code.heihuzi.ai/?Action=<接口名>&Version=2024-01-01`，方法都是 `POST`，正文是 JSON。把图片存成素材、等审核通过后，就能在[创建视频](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/create.md)时用 `asset://<素材 ID>` 作参考图，让同一个人物形象出现在多个视频里。

请使用绑定「Seedance 视频」分组的 API Key。创建、查询、修改、删除素材都不收费，生成视频按视频计费。

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url 'https://code.heihuzi.ai/?Action=CreateAssetGroup&Version=2024-01-01' \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"Name": "我的角色", "GroupType": "AIGC", "Description": "古风短剧人物"}'
```

运行前设置环境变量 `HEIHUZI_API_KEY`。上面的示例创建一个素材组。

## 使用流程

1. `CreateAssetGroup` 创建素材组，记下返回的 `Id`（形如 `group-…`）。
2. `CreateAsset` 把图片链接存进素材组，记下返回的 `Id`（形如 `asset-…`）。
3. 每隔几秒调用 `GetAsset`，直到 `Status` 变成 `Active`（审核通过）。
4. 创建视频时，在参考图里填 `asset://<素材 ID>`。
5. 不再需要时，用 `DeleteAsset`、`DeleteAssetGroup` 删除。

## 身份验证

两种方式任选一种：

* **API Key**：请求头 `Authorization: Bearer <你的 API Key>`，和其他接口一样。
* **火山签名**：沿用火山方舟官方 SDK 的签名方式，把 AccessKey 和 SecretKey **都填成你的便利店 API Key**，服务地址换成 `https://code.heihuzi.ai`，Region 填 `cn-beijing`，Service 填 `ark`。签名时间和服务器时间相差不能超过 15 分钟；同一个签名的写操作（创建、修改、删除）只能用一次，重发要重新签名。

不需要登录便利店网页，也不需要额外的确认步骤。

## 素材组

### CreateAssetGroup 创建素材组

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `Name` | string | 否 | 名称，最多 64 个字，建议填写，方便按名称筛选 |
| `GroupType` | string | 否 | 只能填 `AIGC`，不填时默认 `AIGC` |
| `Description` | string | 否 | 说明，最多 300 个字 |

返回 `{"Id": "group-…"}`。

每个账号最多 10 个素材组，已有 10 个时再创建返回 409 `AssetLimitExceeded`，请先删除不用的素材组。

### GetAssetGroup 查询素材组

正文 `{"Id": "group-…"}`。返回素材组的 `Id`、`Name`、`Description`、`ProjectName` 等信息，`ProjectName` 固定显示 `default`。

### ListAssetGroups 列出素材组

| 字段 | 类型 | 说明 |
| - | - | - |
| `Filter.Name` | string | 按名称筛选 |
| `MaxResults` | integer | 每页条数 |
| `NextToken` | string | 上一页返回的 `NextToken`，取下一页时填 |

返回 `Items`（素材组列表）和 `NextToken`（还有下一页时才有）。只列出你自己创建的素材组。

### UpdateAssetGroup 修改素材组

正文填 `Id`，以及要改的 `Name`、`Description`。

### DeleteAssetGroup 删除素材组

正文 `{"Id": "group-…"}`。

## 素材

### CreateAsset 创建素材

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url 'https://code.heihuzi.ai/?Action=CreateAsset&Version=2024-01-01' \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"GroupId": "group-20261101210510-qjdgs", "URL": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg", "AssetType": "Image", "Name": "红苹果"}'
```

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `GroupId` | string | 是 | 你自己创建的素材组 ID |
| `URL` | string | 是 | 公网可访问的图片链接（http 或 https），图片要求见[创建视频](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/create.md)的「图片」一节 |
| `AssetType` | string | 是 | 只能填 `Image`，填其他值返回 400 `InvalidParameter` |
| `Name` | string | 否 | 名称，最多 64 个字 |

返回 `{"Id": "asset-…"}`。

* 每个账号**大约每 20 秒只能创建 1 个素材**，太快会返回 429 `TooManyRequests`，响应头 `Retry-After` 写着要等几秒，等够后重试即可。查询、列表、修改、删除不受这个间隔限制。
* 素材入库前会经过内容审核。不是图片的文件会被直接拒绝（400 `InvalidParameter.FormatUnsupported`）。
* 本站**没有开放真人身份认证**，建议使用 AI 生成的虚拟人物形象；不保证真人照片能通过审核。
* 可以在请求头里带 `Idempotency-Key`（最长 128 个字符）：网络中断后用同一个键重发，会拿到同一个素材，不会重复创建。

### GetAsset 查询素材

正文 `{"Id": "asset-…"}`。返回素材的 `Id`、`Name`、`GroupId`、`AssetType`、`Status`、`URL`、`ProjectName` 等信息。

* `Status` 为 `Active` 表示审核通过，可以用来生成视频；为 `Failed` 表示未通过；其他状态表示还在处理，请稍后再查。
* `URL` 是素材的临时下载链接，会过期，不要长期保存。

### ListAssets 列出素材

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url 'https://code.heihuzi.ai/?Action=ListAssets&Version=2024-01-01' \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"Filter": {"GroupIds": ["group-20261101210510-qjdgs"], "Statuses": ["Active"]}, "MaxResults": 10}'
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `Filter.GroupIds` | string\[] | 按素材组筛选 |
| `Filter.Statuses` | string\[] | 按状态筛选，如 `["Active"]` |
| `MaxResults` | integer | 每页条数 |
| `NextToken` | string | 上一页返回的 `NextToken`，取下一页时填；筛选条件要和上一页相同 |

返回 `Items`（素材列表）和 `NextToken`（还有下一页时才有）。只列出你自己的素材。

### UpdateAsset 修改素材

正文填 `Id` 和新的 `Name`。

### DeleteAsset 删除素材

正文 `{"Id": "asset-…"}`。正在生成中的视频引用了这个素材时不能删除，返回 409 `ResourceInUse`，等视频结束后再删。

## 用素材生成视频

素材状态为 `Active` 后，在[创建视频](https://docs.heihuzi.ai/cn/api-reference/videos/seedance/create.md)的参考图里填素材 ID，一个视频里可以同时引用多个素材：

```json theme={null}
{
  "model": "doubao-seedance-2-0-mini-260615",
  "content": [
    {"type": "text", "text": "图片1的女剑客在月下的竹林里舞剑，镜头缓慢环绕"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20261101165309-6tc9s"}, "role": "reference_image"}
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}
```

## 素材有效期

素材和素材组不会永久保存，到期后自动删除：

* **用过的素材**：最后一次用它生成视频后保留 7 天；期间每用一次，都从那次重新算 7 天。
* **没用过的素材**：创建后保留 24 小时。
* **素材组**：最后一次往组里添加素材后保留 24 小时。组里还有素材时不会删除；组里的素材都删除后，到期的素材组随即自动删除。

到期删除的素材和素材组**不能恢复**，再用 `GetAsset`、`GetAssetGroup` 查询会返回 404 `ResourceNotFound`。需要长期使用的人物形象，请保存好原图，过期后重新创建素材。

## 响应格式

成功：

```json theme={null}
{
  "ResponseMetadata": {"RequestId": "…", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
  "Result": {"Id": "asset-20261101210526-mgqhj"}
}
```

失败时 `ResponseMetadata` 里多一个 `Error`：

```json theme={null}
{
  "ResponseMetadata": {"RequestId": "…", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing",
    "Error": {"Code": "ResourceNotFound", "Message": "asset or asset group not found"}}
}
```

## 与火山官方接口的差别

* 只有一个项目，`ProjectName` 不填或填 `default`，填其他值返回 400 `InvalidParameter`。
* 每个账号只能看到、修改、使用自己创建的素材组和素材，别人的素材 ID 一律当作不存在。
* 正文只接受上面列出的字段，带了其他字段返回 400 `InvalidParameter`。
* 不支持真人认证相关接口，调用返回 400 `InvalidActionOrVersion`。

## 错误响应

| HTTP | `Error.Code` | 说明 |
| - | - | - |
| 400 | `InvalidParameter` | 字段不符合要求，例如带了不支持的字段、`ProjectName` 不是 `default`、`AssetType` 不是 `Image` |
| 400 | `InvalidParameter.FormatUnsupported` | `URL` 指向的文件不是支持的图片格式 |
| 400 | `InvalidActionOrVersion` | 接口名不在上面列出的范围内，或 `Version` 不是 `2024-01-01` |
| 401 | — | API Key 不正确 |
| 401 | `SignatureDoesNotMatch` | 火山签名校验失败，例如签名后正文被改动 |
| 401 | `SignatureReplayed` | 同一个签名的写操作重复提交，请重新签名 |
| 401 | `RequestExpired` | 签名时间和服务器时间相差超过 15 分钟 |
| 404 | `ResourceNotFound` | 素材或素材组不存在，或不属于你 |
| 409 | `ResourceInUse` | 素材正被未结束的视频使用，暂时不能删除 |
| 409 | `AssetLimitExceeded` | 素材组已达 10 个上限，请先删除不用的素材组 |
| 429 | `TooManyRequests` | 创建素材太快，按响应头 `Retry-After` 等待后重试 |


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