方舟 Seedance：素材库

通过 Gateway 代理火山方舟私域素材 OpenAPI。客户使用平台签发的 AK/SK 按火山兼容 HMAC 签名调用；不接受 Bearer。字段命名与方舟 OpenAPI 一致（PascalCase）。素材调用不计费。平台**不提供「项目组」**层级，仅「本地项目 → 素材组 → 素材」。签名算法见火山引擎签名方法。

相关：创建视频任务 · 查询任务状态

接口地址

POST /openapi/volcengine/?Action=<Action>&Version=2024-01-01

Base 示例：https://ai.youqi.tech。Version 固定为 2024-01-01。

认证

火山兼容 HMAC-SHA256（AccessKeyId / SecretAccessKey）。AK/SK 在 Portal「素材访问密钥」页创建（账号级，不绑定单个项目）。不要使用普通或视频 API Key 的 Bearer。

通用约定

项	说明
`ProjectName`	必填；等于 Portal 本地项目名（不是上游方舟项目名）。响应回写本地名
`model` / `Model`	禁止；渠道由项目绑定的分组名决定
隔离	列表 / 查询按本地项目过滤，仅返回本用户该项目下的素材与组
组名 / 素材名	中文、字母、数字、`_`、`-`，按字符计最长 64；组 Description ≤300
项目名 `ProjectName`	仍为 ASCII（字母、数字、`_`、`-`）；中文请用显示别名
Id	平台自有 Id（`group-…` / `asset-…`）；出站改写为上游 Id
上传	公网可直接 GET（方舟服务端下载，不带你的登录态）。私有 TOS / 过期签名 → `DownloadFailed`。联调：`https://placehold.co/64x64.png`
响应信封	成功一般为 `ResponseMetadata` + `Result`；鉴权/归属错误可能直接返回 `{"error":"..."}`
状态	`Active` / `Processing` / `Failed` / `PendingRebuild`

成功响应外形：

json

{
  "ResponseMetadata": {
    "RequestId": "2026062415283493B3836D523A0F3F0AFB",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { }
}

支持的 Action

Action	说明
`CreateAssetGroup` / `GetAssetGroup` / `ListAssetGroups` / `UpdateAssetGroup` / `DeleteAssetGroup`	素材组
`CreateAsset` / `GetAsset` / `ListAssets` / `UpdateAsset` / `DeleteAsset`	素材

素材组

CreateAssetGroup — 创建素材组

POST /openapi/volcengine/?Action=CreateAssetGroup&Version=2024-01-01

请求参数

参数	类型	必填	说明
`Name`	string	是	素材组逻辑名，1～64 字符，可含中文；同用户、同一 `ProjectName` 下不可重复
`Description`	string	否	描述，最长 300 字符，可含中文
`GroupType`	string	否	类型，默认 / 当前仅支持 `AIGC`
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	新建素材组 ID（如 `group-…`）
`Result.Name`	string	你传入的逻辑名（平台还原）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Name":"figures","Description":"角色参考","GroupType":"AIGC","ProjectName":"my_project"}'

响应示例

json

{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn",
    "Name": "figures"
  }
}

GetAssetGroup — 查询素材组

POST /openapi/volcengine/?Action=GetAssetGroup&Version=2024-01-01

请求参数

参数	类型	必填	说明
`Id`	string	条件	素材组 ID；与 `Name` 二选一
`Name`	string	条件	素材组逻辑名；与 `Id` 二选一
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	素材组 ID
`Result.Name`	string	逻辑名
`Result.Description`	string	描述
`Result.GroupType`	string	类型
`Result.ProjectName`	string	上游项目名（平台注入）
`Result.CreateTime`	string	创建时间（UTC，ISO 8601）
`Result.UpdateTime`	string	更新时间（UTC）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","ProjectName":"my_project"}'

ListAssetGroups — 素材组列表

POST /openapi/volcengine/?Action=ListAssetGroups&Version=2024-01-01

平台会按本用户 binding 自动限定可见组；无需也不应依赖跨账号的 GroupIds。

请求参数

参数	类型	必填	说明
`PageNumber`	integer	否	页码，默认 `1`
`PageSize`	integer	否	每页条数，默认 `10`，最大约 `100`
`Filter.Name`	string	否	按名称过滤
`Filter.GroupType`	string	否	类型过滤，如 `AIGC`
`Filter.GroupIds`	string[]	否	组 ID 列表（平台会与本用户可见集合取交集/改写）
`ProjectName`	string	是	本地项目名

嵌套字段写法：Filter.Name 对应 {"Filter":{"Name":"…"}}。

响应参数

参数	类型	说明
`Result.TotalCount`	integer	命中总数
`Result.PageNumber`	integer	当前页
`Result.PageSize`	integer	页大小
`Result.Items[]`	array	素材组列表
`Result.Items[].Id`	string	组 ID
`Result.Items[].Name`	string	逻辑名
`Result.Items[].Description`	string	描述
`Result.Items[].GroupType`	string	类型
`Result.Items[].ProjectName`	string	项目名
`Result.Items[].CreateTime` / `UpdateTime`	string	时间（UTC）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"PageNumber":1,"PageSize":10,"Filter":{"GroupType":"AIGC"},"ProjectName":"my_project"}'

UpdateAssetGroup — 更新素材组

POST /openapi/volcengine/?Action=UpdateAssetGroup&Version=2024-01-01

GroupType 创建后不可变更。

请求参数

参数	类型	必填	说明
`Id`	string	是	素材组 ID
`Name`	string	否	新逻辑名，1～64 字符
`Description`	string	否	新描述
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	素材组 ID
`Result.Name`	string	更新后的逻辑名（若有改名）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","Name":"figures_v2","Description":"更新说明","ProjectName":"my_project"}'

DeleteAssetGroup — 删除素材组

POST /openapi/volcengine/?Action=DeleteAssetGroup&Version=2024-01-01

建议删除前先 ListAssets 确认组内素材已清理。

请求参数

参数	类型	必填	说明
`Id`	string	条件	素材组 ID；与 `Name` 二选一
`Name`	string	条件	逻辑名；与 `Id` 二选一
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	已删除的素材组 ID

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","ProjectName":"my_project"}'

素材

CreateAsset — 创建（入库）素材

POST /openapi/volcengine/?Action=CreateAsset&Version=2024-01-01

异步受理：返回成功仅表示任务已接收；须轮询 GetAsset 至 Status=Active 后再在视频任务中引用 asset://<Id>。

请求参数

参数	类型	必填	说明
`GroupId`	string	是	所属素材组 ID（须为本用户已创建的组）
`URL`	string	是	方舟服务端会下载该地址，须无登录即可 GET。私有 TOS / 过期签名会返回上游 `InvalidParameter.DownloadFailed`（TOS 403）。联调可用 `https://placehold.co/64x64.png`
`AssetType`	string	是	`Image` / `Video` / `Audio`
`Name`	string	否	素材名，1～64 字符，可含中文；仅用于列表搜索
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	新建素材 ID（如 `asset-…`）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=CreateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260624152835-lb6rn",
    "URL":"https://placehold.co/64x64.png",
    "AssetType":"Image",
    "Name":"产品主图",
    "ProjectName":"my_project"
  }'

响应示例

json

{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb"
  }
}

GetAsset — 查询素材

POST /openapi/volcengine/?Action=GetAsset&Version=2024-01-01

用于入库后轮询处理 / 审核状态。

请求参数

参数	类型	必填	说明
`Id`	string	是	素材 ID
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	素材 ID
`Result.Name`	string	素材名
`Result.URL`	string	临时下载链接；仅 `Active` 时有值，约 12 小时有效；`Processing` 时多为空串
`Result.AssetType`	string	`Image` / `Video` / `Audio`
`Result.GroupId`	string	所属组 ID
`Result.Status`	string	`Processing` / `Active` / `Failed`
`Result.Moderation`	object	审核信息
`Result.Moderation.Strategy`	string	审核策略，如 `Default`
`Result.CreateTime` / `UpdateTime`	string	时间（UTC）
`Result.ProjectName`	string	项目名

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=GetAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","ProjectName":"my_project"}'

响应示例（Active）

json

{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb",
    "Name": "产品主图",
    "URL": "https://….tos-cn-beijing.volces.com/…/product.png?X-Tos-Algorithm=…",
    "AssetType": "Image",
    "GroupId": "group-20260624152835-lb6rn",
    "Status": "Active",
    "Moderation": { "Strategy": "Default" },
    "CreateTime": "2026-06-24T07:28:50Z",
    "UpdateTime": "2026-06-24T07:28:52Z",
    "ProjectName": "default"
  }
}

建议轮询：首次约 3 秒后查询；图片通常数秒～十余秒到 Active；视频 / 音频更久。Failed 或 DownloadFailed 时，用无痕窗口打开源 URL：打不开则方舟也拉不到（不要用需登录的 TOS 私有链）。

ListAssets — 素材列表

POST /openapi/volcengine/?Action=ListAssets&Version=2024-01-01

平台按本用户素材 binding 过滤，不会返回他户素材。

请求参数

参数	类型	必填	说明
`Filter.GroupIds`	string[]	否	按组过滤（会与本用户可见组取交集）
`Filter.Statuses`	string[]	否	`Processing` / `Active` / `Failed`
`Filter.Name`	string	否	名称模糊匹配
`Filter.AssetType`	string	否	`Image` / `Video` / `Audio`
`Filter.GroupType`	string	否	组类型，如 `AIGC`
`PageNumber`	integer	否	页码，默认 `1`
`PageSize`	integer	否	每页条数，默认 `10`，最大约 `100`
`SortBy`	string	否	如 `CreateTime`、`GroupId`
`SortOrder`	string	否	`Asc` / `Desc`（默认多为 `Desc`）
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.TotalCount`	integer	命中总数
`Result.PageNumber` / `PageSize`	integer	分页
`Result.Items[]`	array	素材列表（字段同 `GetAsset` 的 `Result`）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=ListAssets&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {
      "GroupIds": ["group-20260624152835-lb6rn"],
      "Statuses": ["Active", "Processing"],
      "Name": "figure"
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "my_project"
  }'

UpdateAsset — 更新素材

POST /openapi/volcengine/?Action=UpdateAsset&Version=2024-01-01

仅支持改名；URL / AssetType / GroupId 不可变更，需更换请删除后重新 CreateAsset。

请求参数

参数	类型	必填	说明
`Id`	string	是	素材 ID
`Name`	string	否	新名称，1～64 字符
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result.Id`	string	素材 ID

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=UpdateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","Name":"产品主图-v2","ProjectName":"my_project"}'

DeleteAsset — 删除素材

POST /openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01

物理删除，不可恢复。进行中的视频任务若仍引用该素材，可能导致生成失败。

请求参数

参数	类型	必填	说明
`Id`	string	是	素材 ID
`ProjectName`	string	是	本地项目名

响应参数

参数	类型	说明
`Result`	object	成功时多为空对象或含 `Id`（以上游为准）

请求示例

bash

curl "https://ai.youqi.tech/openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","ProjectName":"my_project"}'

素材状态与视频引用

CreateAsset → Processing → Active（可引用）
                    ↘ Failed（仅可删除）

状态	含义	可操作
`Processing`	拉取 / 审核中	轮询 `GetAsset`、可 `DeleteAsset`
`Active`	可用	全量操作；视频任务中 `asset://<Id>`
`Failed`	审核失败或源 URL 不可达	仅建议 `DeleteAsset`

入库后在创建视频任务的 content 中引用，例如：

json

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": { "url": "asset://asset-20260624152850-mftbb" }
}

须为本用户在对应本地项目下创建的素材，且状态为 Active（PendingRebuild 将使创建任务进入等待）。

方舟 Seedance：素材库 ​

接口地址 ​

认证 ​

通用约定 ​

支持的 Action ​

素材组 ​

CreateAssetGroup — 创建素材组 ​

请求参数 ​

响应参数 ​

请求示例 ​

响应示例 ​

GetAssetGroup — 查询素材组 ​

请求参数 ​

响应参数 ​

请求示例 ​

ListAssetGroups — 素材组列表 ​

请求参数 ​

响应参数 ​

请求示例 ​

UpdateAssetGroup — 更新素材组 ​

请求参数 ​

响应参数 ​

请求示例 ​

DeleteAssetGroup — 删除素材组 ​

请求参数 ​

响应参数 ​

请求示例 ​

素材 ​

CreateAsset — 创建（入库）素材 ​

请求参数 ​

响应参数 ​

请求示例 ​

响应示例 ​

GetAsset — 查询素材 ​

请求参数 ​

响应参数 ​

请求示例 ​

响应示例（Active） ​

ListAssets — 素材列表 ​

请求参数 ​

响应参数 ​

请求示例 ​

UpdateAsset — 更新素材 ​

请求参数 ​

响应参数 ​

请求示例 ​

DeleteAsset — 删除素材 ​

请求参数 ​

响应参数 ​

请求示例 ​

素材状态与视频引用 ​

方舟 Seedance：素材库

接口地址

认证

通用约定

支持的 Action

素材组

CreateAssetGroup — 创建素材组

请求参数

响应参数

请求示例

响应示例

GetAssetGroup — 查询素材组

请求参数

响应参数

请求示例

ListAssetGroups — 素材组列表

请求参数

响应参数

请求示例

UpdateAssetGroup — 更新素材组

请求参数

响应参数

请求示例

DeleteAssetGroup — 删除素材组

请求参数

响应参数

请求示例

素材

CreateAsset — 创建（入库）素材

请求参数

响应参数

请求示例

响应示例

GetAsset — 查询素材

请求参数

响应参数

请求示例

响应示例（Active）

ListAssets — 素材列表

请求参数

响应参数

请求示例

UpdateAsset — 更新素材

请求参数

响应参数

请求示例

DeleteAsset — 删除素材

请求参数

响应参数

请求示例

素材状态与视频引用