素材库 · 火山兼容

使用与火山方舟素材库一致的 Action、Version、请求参数和响应字段，管理 Seedance 2.0 可引用的图片、视频、音频及真人素材。本页逐项列出全部 12 个 Action 的完整路径、参数、请求体、响应字段和成功示例，可独立用于接入。

请求方式

POST https://heiyutv.com/?Action={Action}&Version=2024-01-01
Authorization: Bearer sk-gw-XXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

字段	类型	必选	说明
`Action`	`query string`	是	取下方 12 个 Action 之一，大小写敏感。
`Version`	`query string`	是	固定为 2024-01-01。
`Content-Type`	`header`	是	固定为 application/json。
`Authorization`	`header`	是	Bearer API Key 或 HMAC-SHA256，二选一。

每个请求必须在 Bearer API Key 与 AK/SK HMAC-SHA256 中任选一种，不能混用；不接受控制台会话。Bearer Key 必须包含视频模型权限；沙箱账号不提供素材库能力。ProjectName 未填写时为default，大小写敏感。

AK/SK 签名

在控制台「API Keys → 素材库访问凭据」创建 Access Key 和 Secret Key。 Secret Key 只显示一次。签名固定使用 HMAC-SHA256、区域cn-beijing、服务 ark，请求时间与服务端偏差不得超过 5 分钟；不支持 X-Security-Token 临时凭据。

POST /?Action=CreateAssetGroup&Version=2024-01-01
Host: heiyutv.com
Content-Type: application/json
X-Date: YYYYMMDDTHHMMSSZ
X-Content-Sha256: <原始请求体的 SHA-256 小写十六进制>
Authorization: HMAC-SHA256 Credential=<AK>/<YYYYMMDD>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<hex>

Canonical Request 依次拼接 HTTP 方法、Canonical URI、按键和值排序并进行 URI 编码的 Canonical Query、四个小写 Canonical Headers、固定 Signed Headers 和请求体哈希。签名密钥依次按日期、cn-beijing、ark、request 派生。必须用完全相同的请求体字节计算哈希并发送；签名后不要重新格式化 JSON。Host 必须是上面实际请求的 Heiyu Endpoint。

完整 Action 列表

Action	用途	主要请求参数
`CreateAssetGroup`	创建素材组	Name；Description、GroupType、ProjectName 可选
`ListAssetGroups`	列出素材组	Filter、PageNumber、PageSize 必填；支持排序
`GetAssetGroup`	查询素材组	Id；ProjectName 可选
`UpdateAssetGroup`	更新素材组	Id；Name、Description 至少提供一个
`DeleteAssetGroup`	删除素材组	Id；ProjectName 可选
`CreateAsset`	从 URL 创建素材	GroupId、URL、AssetType；Name、ProjectName 可选
`ListAssets`	列出素材	Filter、分页、排序与 ProjectName 均可选
`GetAsset`	查询素材及处理状态	Id；ProjectName 可选
`UpdateAsset`	更新素材名称	Id、Name；ProjectName 可选
`DeleteAsset`	删除素材	Id；ProjectName 可选
`CreateVisualValidateSession`	创建真人认证会话	CallbackURL；ProjectName 可选
`GetVisualValidateResult`	取得真人素材组	BytedToken；ProjectName 可选

素材格式与限制

类型	格式	尺寸或时长	大小
图片	jpeg、png、webp、bmp、tiff、gif、heic、heif	宽高比 0.4–2.5；边长 300–6000 px	小于 30 MB
视频	mp4、mov	480p/720p/1080p；2–15 秒；宽高比 0.4–2.5；24–60 FPS	不超过 200 MB
音频	wav、mp3	2–15 秒	不超过 15 MB

素材 URL 必须能从公网直接访问，不支持 Base64、交互登录或仅在内网可用的下载地址。

CreateAssetGroup · 创建素材组

创建用于归集图片、视频或音频的普通素材组。

请求路径

POST https://heiyutv.com/?Action=CreateAssetGroup&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Name`	`string`	是	名称，最长 64 个字符。
`Description`	`string`	否	描述，最长 300 个字符。
`GroupType`	`string`	否	默认 AIGC；普通创建流程仅支持 AIGC。
`ProjectName`	`string`	否	默认 default，大小写敏感。

请求体示例

{
  "Name": "产品素材",
  "Description": "产品图片和视频",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	新素材组的 asg_… 业务 ID。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asg_0123456789abcdef0123456789abcdef"
  }
}

真人素材组由真人认证流程创建，类型为 LivenessFace。

ListAssetGroups · 查询素材组列表

按类型、ID 或名称分页查询当前账号的素材组。

请求路径

POST https://heiyutv.com/?Action=ListAssetGroups&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Filter`	`object`	是	过滤条件。
`Filter.GroupIds`	`string[]`	否	精确匹配的 asg_… ID 列表。
`Filter.GroupType`	`string`	是	AIGC 或 LivenessFace。
`Filter.Name`	`string`	否	名称搜索，最长 64 个字符。
`PageNumber`	`integer`	是	页码，从 1 开始。
`PageSize`	`integer`	是	每页数量，最大 100。
`SortBy`	`string`	否	CreateTime 或 UpdateTime，默认 CreateTime。
`SortOrder`	`string`	否	Desc 或 Asc，默认 Desc。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Filter": {
    "GroupType": "AIGC",
    "Name": "产品"
  },
  "PageNumber": 1,
  "PageSize": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`TotalCount`	`integer`	返回	符合条件的素材组总数。
`Items`	`object[]`	返回	素材组数组。
`Items.Id`	`string`	返回	素材组业务 ID，形如 asg_…。
`Items.Name`	`string`	返回	素材组名称，最长 64 个字符。
`Items.Description`	`string`	返回	素材组描述，最长 300 个字符。
`Items.GroupType`	`string`	返回	AIGC 或 LivenessFace。
`Items.ProjectName`	`string`	返回	所属项目。
`Items.CreateTime`	`string`	返回	创建时间。
`Items.UpdateTime`	`string`	返回	更新时间。
`PageNumber`	`integer`	返回	当前页码。
`PageSize`	`integer`	返回	当前每页数量。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "asg_0123456789abcdef0123456789abcdef",
        "Name": "产品素材",
        "Description": "产品图片和视频",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-08-26T00:00:00Z",
        "UpdateTime": "2026-08-26T00:00:00Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 20
  }
}

GetAssetGroup · 查询素材组详情

通过 asg_… 业务 ID 查询一个素材组。

请求路径

POST https://heiyutv.com/?Action=GetAssetGroup&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材组业务 ID。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "asg_0123456789abcdef0123456789abcdef",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	素材组业务 ID，形如 asg_…。
`Name`	`string`	返回	素材组名称，最长 64 个字符。
`Description`	`string`	返回	素材组描述，最长 300 个字符。
`GroupType`	`string`	返回	AIGC 或 LivenessFace。
`ProjectName`	`string`	返回	所属项目。
`CreateTime`	`string`	返回	创建时间。
`UpdateTime`	`string`	返回	更新时间。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asg_0123456789abcdef0123456789abcdef",
    "Name": "产品素材",
    "Description": "产品图片和视频",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-08-26T00:00:00Z",
    "UpdateTime": "2026-08-26T00:00:00Z"
  }
}

UpdateAssetGroup · 更新素材组

更新素材组名称或描述，不能修改类型或所属项目。

请求路径

POST https://heiyutv.com/?Action=UpdateAssetGroup&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材组业务 ID。
`Name`	`string`	条件必填	新名称，最长 64 个字符。
`Description`	`string`	条件必填	新描述，最长 300 个字符。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "asg_0123456789abcdef0123456789abcdef",
  "Name": "产品素材（新版）",
  "Description": "更新后的描述",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	已更新的素材组 ID。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "UpdateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asg_0123456789abcdef0123456789abcdef"
  }
}

Name 与 Description 至少提供一个。

DeleteAssetGroup · 删除素材组

删除素材组及组内全部素材，操作不可恢复。

请求路径

POST https://heiyutv.com/?Action=DeleteAssetGroup&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材组业务 ID。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "asg_0123456789abcdef0123456789abcdef",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Result`	`object`	返回	成功时为空对象。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "DeleteAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

删除前应确认组内素材不再被业务引用。
真人素材组受授权状态限制，不能删除时返回业务错误。

CreateAsset · 创建素材

从公共 URL 异步创建图片、视频或音频素材。

请求路径

POST https://heiyutv.com/?Action=CreateAsset&Version=2024-01-01

请求参数

字段	类型	必选	说明
`GroupId`	`string`	是	所属素材组的 asg_… ID。
`URL`	`string`	是	公网可访问 URL，不支持 Base64。
`Name`	`string`	否	名称，最长 64 个字符。
`AssetType`	`string`	是	Image、Video 或 Audio。
`ProjectName`	`string`	否	默认 default，必须与素材组一致。

请求体示例

{
  "GroupId": "asg_0123456789abcdef0123456789abcdef",
  "URL": "https://example.com/product.png",
  "Name": "产品主图",
  "AssetType": "Image",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	新素材的 ast_… 业务 ID。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "ast_0123456789abcdef0123456789abcdef"
  }
}

返回 ID 只表示进入预处理队列；继续调用 GetAsset 直到 Active 或 Failed。

ListAssets · 查询素材列表

按素材组、类型、状态或名称分页查询素材。

请求路径

POST https://heiyutv.com/?Action=ListAssets&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Filter`	`object`	否	过滤条件。
`Filter.GroupIds`	`string[]`	否	所属素材组 ID 列表。
`Filter.GroupType`	`string`	否	AIGC 或 LivenessFace。
`Filter.Statuses`	`string[]`	否	Active、Processing 或 Failed。
`Filter.Name`	`string`	否	名称搜索，最长 64 个字符。
`PageNumber`	`integer`	否	默认 1。
`PageSize`	`integer`	否	最大 100。
`SortBy`	`string`	否	CreateTime、UpdateTime 或 GroupId。
`SortOrder`	`string`	否	Desc 或 Asc。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Filter": {
    "GroupIds": [
      "asg_0123456789abcdef0123456789abcdef"
    ],
    "Statuses": [
      "Active"
    ]
  },
  "PageNumber": 1,
  "PageSize": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Items`	`object[]`	返回	素材数组。
`Items.Id`	`string`	返回	素材业务 ID，形如 ast_…。
`Items.Name`	`string`	返回	素材名称。
`Items.URL`	`string`	返回	Heiyu 临时下载地址，有效期 12 小时，支持 HTTP Range。
`Items.GroupId`	`string`	返回	所属素材组的 asg_… 业务 ID。
`Items.AssetType`	`string`	返回	Image、Video 或 Audio。
`Items.Status`	`string`	返回	Processing、Active 或 Failed。
`Items.Moderation.Strategy`	`string`	条件返回	内容审核策略，当前为 Default。
`Items.Error.Code`	`string`	失败时	预处理失败码。
`Items.Error.Message`	`string`	失败时	预处理失败说明。
`Items.CreateTime`	`string`	返回	创建时间。
`Items.UpdateTime`	`string`	返回	更新时间。
`Items.ProjectName`	`string`	返回	所属项目。
`TotalCount`	`integer`	返回	符合条件的素材总数。
`PageNumber`	`integer`	返回	当前页码。
`PageSize`	`integer`	返回	当前每页数量。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "ast_0123456789abcdef0123456789abcdef",
        "Name": "产品主图",
        "URL": "https://heiyutv.com/api/v1/assets/content/acl_0123456789abcdef0123456789abcdef",
        "GroupId": "asg_0123456789abcdef0123456789abcdef",
        "AssetType": "Image",
        "Status": "Active",
        "Moderation": {
          "Strategy": "Default"
        },
        "CreateTime": "2026-08-26T00:00:00Z",
        "UpdateTime": "2026-08-26T00:00:10Z",
        "ProjectName": "default"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 20
  }
}

GetAsset · 查询素材详情

查询素材详情和异步预处理状态；HTTP 200 不代表处理成功。

请求路径

POST https://heiyutv.com/?Action=GetAsset&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材业务 ID。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "ast_0123456789abcdef0123456789abcdef",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	素材业务 ID，形如 ast_…。
`Name`	`string`	返回	素材名称。
`URL`	`string`	返回	Heiyu 临时下载地址，有效期 12 小时，支持 HTTP Range。
`GroupId`	`string`	返回	所属素材组的 asg_… 业务 ID。
`AssetType`	`string`	返回	Image、Video 或 Audio。
`Status`	`string`	返回	Processing、Active 或 Failed。
`Moderation.Strategy`	`string`	条件返回	内容审核策略，当前为 Default。
`Error.Code`	`string`	失败时	预处理失败码。
`Error.Message`	`string`	失败时	预处理失败说明。
`CreateTime`	`string`	返回	创建时间。
`UpdateTime`	`string`	返回	更新时间。
`ProjectName`	`string`	返回	所属项目。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "ast_0123456789abcdef0123456789abcdef",
    "Name": "产品主图",
    "URL": "https://heiyutv.com/api/v1/assets/content/acl_0123456789abcdef0123456789abcdef",
    "GroupId": "asg_0123456789abcdef0123456789abcdef",
    "AssetType": "Image",
    "Status": "Active",
    "Moderation": {
      "Strategy": "Default"
    },
    "CreateTime": "2026-08-26T00:00:00Z",
    "UpdateTime": "2026-08-26T00:00:10Z",
    "ProjectName": "default"
  }
}

Processing 表示仍在处理；Active 才能使用；Failed 时检查 Error.Code 和 Error.Message。

UpdateAsset · 更新素材

更新素材名称，不能替换 URL、类型或所属素材组。

请求路径

POST https://heiyutv.com/?Action=UpdateAsset&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材业务 ID。
`Name`	`string`	是	新名称，最长 64 个字符。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "ast_0123456789abcdef0123456789abcdef",
  "Name": "产品主图（新版）",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Id`	`string`	返回	已更新的素材 ID。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "ast_0123456789abcdef0123456789abcdef"
  }
}

DeleteAsset · 删除素材

删除一个素材；删除后不能查询或继续用于视频生成。

请求路径

POST https://heiyutv.com/?Action=DeleteAsset&Version=2024-01-01

请求参数

字段	类型	必选	说明
`Id`	`string`	是	素材业务 ID。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "Id": "ast_0123456789abcdef0123456789abcdef",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`Result`	`object`	返回	成功时为空对象。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

删除不可恢复；如需保留内容，请先下载或转存。

CreateVisualValidateSession · 创建真人认证会话

创建一次性 H5 真人认证会话。

请求路径

POST https://heiyutv.com/?Action=CreateVisualValidateSession&Version=2024-01-01

请求参数

字段	类型	必选	说明
`CallbackURL`	`string`	是	认证完成后的跳转地址，最长 2048 个字符。
`ProjectName`	`string`	否	默认 default。

请求体示例

{
  "CallbackURL": "https://example.com/liveness-complete",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`BytedToken`	`string`	返回	vvs_… 不透明会话凭据。
`H5Link`	`string`	返回	终端用户打开的一次性真人认证 H5 页面地址，由真人认证服务托管。
`CallbackURL`	`string`	返回	原样返回请求中的回调地址。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "vvs_0123456789abcdef0123456789abcdef",
    "H5Link": "https://verify.example.com/liveness/authorize?token=eyJhbGci0...",
    "CallbackURL": "https://example.com/liveness-complete"
  }
}

BytedToken 与 H5Link 有效期 30 分钟，只能完成一次认证。
H5Link 可追加 &lng=zh、&lng=en 或 &lng=zh-Hant。
H5Link 由真人认证服务直接提供，请将终端用户跳转到该地址，不要改写其 Host 或参数。

GetVisualValidateResult · 查询真人认证结果

用户完成 H5 流程后，取得创建的 LivenessFace 素材组。

请求路径

POST https://heiyutv.com/?Action=GetVisualValidateResult&Version=2024-01-01

请求参数

字段	类型	必选	说明
`BytedToken`	`string`	是	创建会话返回的 vvs_… 凭据。
`ProjectName`	`string`	否	默认 default，必须与创建会话时一致。

请求体示例

{
  "BytedToken": "vvs_0123456789abcdef0123456789abcdef",
  "ProjectName": "default"
}

响应参数

字段	类型	必选	说明
`GroupId`	`string`	返回	真人认证创建的 LivenessFace 素材组 ID。

成功响应示例

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "GroupId": "asg_abcdef0123456789abcdef0123456789"
  }
}

认证未完成时可能返回待处理业务错误；完成后应立即查询。

异步处理与真人认证流程

CreateAsset 返回成功只表示进入预处理队列。轮询 GetAsset：Processing 表示仍在处理，Active 表示可以使用，Failed 时读取 Error.Code 与 Error.Message。

调用 CreateVisualValidateSession 并安全保存 BytedToken。
让终端用户在 30 分钟内打开 H5Link 完成一次认证。
调用 GetVisualValidateResult 取得 LivenessFace 素材组 ID。

响应与错误

{
  "ResponseMetadata": {
    "RequestId": "bc2c8d97b49d4daea70e57ab09468133",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { "Id": "asg_0123456789abcdef0123456789abcdef" }
}

失败时检查 ResponseMetadata.Error.Code 与ResponseMetadata.Error.Message。所有资源查询同时按账号和业务 ID 隔离；响应不会返回内部数据库主键、路由信息或服务侧资源 ID。

计费

当前上述 12 个素材库 Action 均不扣除账户余额，真人认证能力当前也免费。素材被视频生成任务引用后，该视频任务仍按视频生成计费规则结算；账单与余额可通过计费接口查询。