素材资产（Assets）API 对接文档

本文档描述素材资产与素材资产组的外部调用接口。接口清单以当前路由为准，共 10 个：5 个素材接口和 5 个素材组接口。

1. 接入说明

1.1 请求地址

所有接口均使用 POST 方法，请求地址格式如下：

{BASE_URL}/api/v1/{Action}?Action={Action}&Version=2024-01-01

例如：

POST {BASE_URL}/api/v1/CreateAssetGroup?Action=CreateAssetGroup&Version=2024-01-01

1.2 公共查询参数

参数	类型	必选	说明
`Action`	string	是	必须与路径中的接口名称完全一致，区分大小写。例如调用 `/CreateAsset` 时必须传 `Action=CreateAsset`。
`Version`	string	是	固定为 `2024-01-01`。

缺失查询参数或参数值不正确时，接口返回 AssetLibrary.InvalidRequest。

1.3 公共请求头

请求头	必选	说明
`Authorization`	是	`Bearer API_KEY`，其中 `API_KEY` 为平台签发的访问令牌。
`Content-Type`	是	固定为 `application/json`。

1.4 公共响应结构

成功和业务失败均使用统一响应包：

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

字段	说明
`ResponseMetadata.RequestId`	请求追踪 ID，排查问题时请一并提供。
`ResponseMetadata.Action`	当前接口动作。
`ResponseMetadata.Version`	素材渠道协议版本。
`ResponseMetadata.Service`	素材渠道服务名称。
`ResponseMetadata.Region`	素材渠道区域。
`ResponseMetadata.Error`	业务失败时出现，包含 `Code` 和 `Message`。
`Result`	业务结果；业务失败时为空对象 `{}`。

业务错误仍可能返回 HTTP 200。调用方必须检查 ResponseMetadata.Error 是否存在，不能只依赖 HTTP 状态码判断业务是否成功。鉴权失败、网关异常或网络故障仍可能返回非 200 状态或非 JSON 响应。

1.5 ProjectName 和业务 ID

ProjectName 不传时使用当前素材渠道配置的默认项目，通常为 default；最大长度为 64 个字符。

创建接口返回的 Result.Id 是本系统素材库业务 ID。后续查询、更新、删除及筛选必须使用该 ID，不要改用上游渠道 ID。

素材的 ProjectName 必须与所属素材组的项目一致。

2. 接口清单

分类	Action	请求路径
素材	`CreateAsset`	`/api/v1/CreateAsset`
素材	`GetAsset`	`/api/v1/GetAsset`
素材	`UpdateAsset`	`/api/v1/UpdateAsset`
素材	`DeleteAsset`	`/api/v1/DeleteAsset`
素材	`ListAssets`	`/api/v1/ListAssets`
素材组	`CreateAssetGroup`	`/api/v1/CreateAssetGroup`
素材组	`GetAssetGroup`	`/api/v1/GetAssetGroup`
素材组	`UpdateAssetGroup`	`/api/v1/UpdateAssetGroup`
素材组	`DeleteAssetGroup`	`/api/v1/DeleteAssetGroup`
素材组	`ListAssetGroups`	`/api/v1/ListAssetGroups`

3. 素材接口

3.1 创建素材（CreateAsset）

在指定素材组中创建素材。该接口涉及上游异步处理，创建成功只表示素材已提交；请通过 GetAsset 或 ListAssets 查询后续状态。

POST /api/v1/CreateAsset?Action=CreateAsset&Version=2024-01-01

请求体

字段	类型	必选	说明
`GroupId`	string	是	所属素材组的业务 ID。
`URL`	string	是	公网可访问的绝对 HTTP/HTTPS 地址，最长 8192 字节；不支持 Base64。
`Name`	string	是	素材名称，最多 64 个字符，可用于列表模糊搜索。
`AssetType`	string	是	`Image`、`Video` 或 `Audio`。
`ProjectName`	string	否	项目名称，默认使用当前渠道的默认项目。

素材规格

以下规格由素材渠道处理并校验：

图片：jpeg、png、webp、bmp、tiff、gif、heic、heif；宽高比 (0.4, 2.5)；宽、高均在 (300, 6000) px；小于 30 MB。

视频：mp4、mov；480p 或 720p；时长 [2, 15] 秒；宽高比 [0.4, 2.5]；宽、高均在 [300, 6000] px；总像素数 [409600, 927408]；不超过 50 MB；帧率 [24, 60] FPS。

音频：wav、mp3；时长 [2, 15] 秒；不超过 15 MB。

请求示例

响应参数

字段	类型	说明
`Result.Id`	string	新建素材的业务 ID。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260328000000000-def34"
  }
}

3.2 查询素材（GetAsset）

查询单个素材的信息和当前处理状态。

POST /api/v1/GetAsset?Action=GetAsset&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材业务 ID。
`ProjectName`	string	否	素材所属项目，默认使用当前渠道的默认项目。

{
  "Id": "asset-20260328000000000-def34",
  "ProjectName": "default"
}

响应参数

字段	类型	说明
`Id`	string	素材业务 ID。
`GroupId`	string	所属素材组业务 ID。
`Name`	string	素材名称。
`URL`	string	素材访问地址；渠道返回临时地址时应及时使用或保存。
`AssetType`	string	`Image`、`Video` 或 `Audio`。
`Status`	string	`Pending`、`Uploading`、`Processing`、`Ready` 或 `Failed`。
`Error`	object	处理失败信息，存在时包含 `Code` 和 `Message`。
`Moderation`	object	内容审核信息，存在时包含 `Strategy`。
`LastInferenceTime`	string	最近推理时间，无数据时为空字符串。
`ProjectName`	string	项目名称。
`CreateTime`	string	RFC 3339 格式的创建时间。
`UpdateTime`	string	RFC 3339 格式的更新时间。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260328000000000-def34",
    "GroupId": "group-20260328000000000-abc12",
    "Name": "avatar",
    "URL": "https://example.com/avatar.png",
    "AssetType": "Image",
    "Status": "Ready",
    "LastInferenceTime": "",
    "ProjectName": "default",
    "CreateTime": "2026-03-28T00:00:00Z",
    "UpdateTime": "2026-03-28T00:00:00Z"
  }
}

3.3 更新素材（UpdateAsset）

更新单个素材的名称。

POST /api/v1/UpdateAsset?Action=UpdateAsset&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材业务 ID。
`Name`	string	是	新名称，最多 64 个字符。
`ProjectName`	string	否	素材所属项目，默认使用当前渠道的默认项目。

{
  "Id": "asset-20260328000000000-def34",
  "Name": "new-avatar-name",
  "ProjectName": "default"
}

成功响应

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260328000000000-def34"
  }
}

3.4 删除素材（DeleteAsset）

删除单个素材。删除后调用方不能再查询或使用该素材。

POST /api/v1/DeleteAsset?Action=DeleteAsset&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材业务 ID。
`ProjectName`	string	否	素材所属项目，默认使用当前渠道的默认项目。

{
  "Id": "asset-20260328000000000-def34",
  "ProjectName": "default"
}

成功响应

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

3.5 查询素材列表（ListAssets）

按条件分页查询当前用户的素材。查询时会同步当前渠道中的素材状态。

POST /api/v1/ListAssets?Action=ListAssets&Version=2024-01-01

请求体

字段	类型	必选	说明
`Filter`	object	否	筛选条件。
`Filter.GroupIds`	string[]	否	所属素材组业务 ID 列表。
`Filter.GroupType`	string	否	素材组类型，当前为 `AIGC`。
`Filter.Statuses`	string[]	否	状态列表：`Pending`、`Uploading`、`Processing`、`Ready`、`Failed`。
`Filter.Name`	string	否	素材名称，模糊匹配。
`PageNumber`	integer	是	页码，从 1 开始。
`PageSize`	integer	是	每页数量，范围为 1～100。
`SortBy`	string	否	`CreateTime`、`UpdateTime` 或 `GroupId`，默认为 `CreateTime`。
`SortOrder`	string	否	`Asc` 或 `Desc`，默认为 `Desc`。
`ProjectName`	string	否	项目名称，默认使用当前渠道的默认项目。

{
  "Filter": {
    "GroupIds": ["group-20260328000000000-abc12"],
    "GroupType": "AIGC",
    "Statuses": ["Ready"],
    "Name": "avatar"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

响应参数

字段	类型	说明
`Items`	object[]	素材列表，字段与 `GetAsset` 的 `Result` 一致。
`TotalCount`	integer	符合条件的素材总数。
`PageNumber`	integer	当前页码。
`PageSize`	integer	当前每页数量。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "asset-20260328000000000-def34",
        "GroupId": "group-20260328000000000-abc12",
        "Name": "avatar",
        "URL": "https://example.com/avatar.png",
        "AssetType": "Image",
        "Status": "Ready",
        "LastInferenceTime": "",
        "ProjectName": "default",
        "CreateTime": "2026-03-28T00:00:00Z",
        "UpdateTime": "2026-03-28T00:00:00Z"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 10
  }
}

4. 素材组接口

4.1 创建素材组（CreateAssetGroup）

创建用于管理素材的素材组。同一用户不能创建重名素材组。

POST /api/v1/CreateAssetGroup?Action=CreateAssetGroup&Version=2024-01-01

请求体

字段	类型	必选	说明
`Name`	string	是	素材组名称，最多 64 个字符。
`Description`	string	否	素材组描述，最多 300 个字符。
`GroupType`	string	否	素材组类型，当前仅支持 `AIGC`；不传时默认为 `AIGC`。
`ProjectName`	string	否	项目名称，默认使用当前渠道的默认项目。

{
  "Name": "virtual-avatar",
  "Description": "virtual avatar assets",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

成功响应

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260328000000000-abc12"
  }
}

4.2 查询素材组（GetAssetGroup）

查询单个素材组的信息。

POST /api/v1/GetAssetGroup?Action=GetAssetGroup&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材组业务 ID。
`ProjectName`	string	否	素材组所属项目，默认使用当前渠道的默认项目。

{
  "Id": "group-20260328000000000-abc12",
  "ProjectName": "default"
}

响应参数

字段	类型	说明
`Id`	string	素材组业务 ID。
`Name`	string	素材组名称。
`Description`	string	素材组描述。
`GroupType`	string	素材组类型。
`ProjectName`	string	项目名称。
`CreateTime`	string	RFC 3339 格式的创建时间。
`UpdateTime`	string	RFC 3339 格式的更新时间。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260328000000000-abc12",
    "Name": "virtual-avatar",
    "Description": "virtual avatar assets",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-03-28T00:00:00Z",
    "UpdateTime": "2026-03-28T00:00:00Z"
  }
}

4.3 更新素材组（UpdateAssetGroup）

更新素材组名称或描述。Name 和 Description 至少传一个。

POST /api/v1/UpdateAssetGroup?Action=UpdateAssetGroup&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材组业务 ID。
`Name`	string	条件必选	新名称，最多 64 个字符。与 `Description` 至少传一个。
`Description`	string	条件必选	新描述，最多 300 个字符。与 `Name` 至少传一个。显式传空字符串可清空描述。
`ProjectName`	string	否	素材组所属项目，默认使用当前渠道的默认项目。

{
  "Id": "group-20260328000000000-abc12",
  "Name": "new-group-name",
  "Description": "new description",
  "ProjectName": "default"
}

成功响应

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "UpdateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260328000000000-abc12"
  }
}

4.4 删除素材组（DeleteAssetGroup）

删除指定素材组，并同时删除组内全部素材。该操作对调用方不可恢复，请谨慎调用；渠道侧副本由系统异步清理。

POST /api/v1/DeleteAssetGroup?Action=DeleteAssetGroup&Version=2024-01-01

请求体

字段	类型	必选	说明
`Id`	string	是	素材组业务 ID。
`ProjectName`	string	否	素材组所属项目，默认使用当前渠道的默认项目。

{
  "Id": "group-20260328000000000-abc12",
  "ProjectName": "default"
}

成功响应

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

4.5 查询素材组列表（ListAssetGroups）

按条件分页查询当前用户的素材组。

POST /api/v1/ListAssetGroups?Action=ListAssetGroups&Version=2024-01-01

请求体

字段	类型	必选	说明
`Filter`	object	是	筛选条件。
`Filter.GroupIds`	string[]	否	素材组业务 ID 列表。
`Filter.GroupType`	string	是	素材组类型，当前为 `AIGC`。
`Filter.Name`	string	否	素材组名称，模糊匹配。
`PageNumber`	integer	是	页码，从 1 开始。
`PageSize`	integer	是	每页数量，范围为 1～100。
`SortBy`	string	否	`CreateTime` 或 `UpdateTime`，默认为 `CreateTime`。
`SortOrder`	string	否	`Asc` 或 `Desc`，默认为 `Desc`。
`ProjectName`	string	否	项目名称，默认使用当前渠道的默认项目。

{
  "Filter": {
    "GroupIds": ["group-20260328000000000-abc12"],
    "GroupType": "AIGC",
    "Name": "avatar"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

响应参数

字段	类型	说明
`Items`	object[]	素材组列表，字段与 `GetAssetGroup` 的 `Result` 一致。
`TotalCount`	integer	符合条件的素材组总数。
`PageNumber`	integer	当前页码。
`PageSize`	integer	当前每页数量。

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "group-20260328000000000-abc12",
        "Name": "virtual-avatar",
        "Description": "virtual avatar assets",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-03-28T00:00:00Z",
        "UpdateTime": "2026-03-28T00:00:00Z"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 10
  }
}

5. 真人认证 H5 与素材组

完整流程：创建认证会话 → 本人打开 H5Link 完成认证 → 浏览器回跳 → 查询真人 GroupId → 在组内创建素材并查询状态 → 视频请求引用素材 ID。平台回调页会自动查询素材组，调用方也可以使用同一平台用户的 API Key 主动查询。

5.0 真人与虚拟人像的区别

项目	虚拟人像 / AIGC 素材	真人素材
建组入口	`CreateAssetGroup`，普通模式使用 `GroupType: "AIGC"`	`CreateVisualValidateSession` 发起真人认证
获取素材组	创建接口返回 `Result.Id`	认证后通过 `GetVisualValidateResult` 获取 `Result.GroupId`
是否需要本人操作	普通建组不需要 H5 真人认证	本人打开返回的 `H5Link` 完成认证
后续上传及查询	`CreateAsset`、`GetAsset` 等	使用认证生成的组 ID 调用素材接口，操作能力以所选上游渠道为准
视频引用	`asset://` 加素材 ID	同样使用 `asset://` 加素材 ID

真人组通过认证流程获取，不要用普通 CreateAssetGroup 的 AIGC 示例代替认证，也不要自行猜测 GroupType 的真人枚举。这里的认证用于上游真人素材授权，不会把平台账号的个人或企业实名认证状态自动改为已认证。

以下示例面向平台调用方，统一使用平台 API Key。将 https://token.kelly.cloud 替换为你的平台 API 域名。

5.1 创建真人认证会话

参数	类型	必填	说明
`CallbackURL`	string	是	完成认证后打开的绝对 HTTP/HTTPS 回调地址，最多 4096 字节。平台不主动访问此地址。
`ProjectName`	string	否	不传时使用所选素材渠道的默认项目，未配置则使用 `default`，最多 64 字节。

成功响应保留上游 ResponseMetadata 和 Result，示例：

{
  "ResponseMetadata": {"RequestId":"upstream-request-id","Action":"CreateVisualValidateSession","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "BytedToken":"EXAMPLE_BYTED_TOKEN",
    "H5Link":"https://ark.volcengine.com/example-h5-link",
    "CallbackURL":"https://token.kelly.cloud/api/v1/VisualValidateCallback"
  }
}

H5Link 为上游返回的认证页地址，请让本人打开实际返回的完整链接完成操作。BytedToken 为认证凭证，需保存以查询结果，不要公开分享或写入普通访问日志。它的格式由上游决定，可能是时间戳加字母数字，也可能有前缀；不要求以 vvs- 开头，使用原始值即可。示例占位符不能直接用于查询。

5.2 获取真人素材组 ID

参数	类型	必填	说明
`BytedToken`	string	是	当前平台用户通过上一接口创建的认证凭证，最多 4096 字节。不接受其他用户或直接在上游创建的凭证。
`ProjectName`	string	否	不传时沿用创建会话的项目；传入时必须匹配。

{
  "ResponseMetadata": {"RequestId":"upstream-request-id","Action":"GetVisualValidateResult","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {"GroupId":"group-upstream-human-id"}
}

返回的 GroupId 是上游真人素材组 ID。平台会将其登记到现有素材组及渠道映射表，同一会话重复查询不会重复创建记录。之后可将其作为 GetAssetGroup.Id、CreateAsset.GroupId 使用；这些操作继续走认证时的素材渠道，不会把真人组复制到其他渠道。上游对真人组可执行操作的限制仍然适用。

5.3 平台回调页面与调试日志

平台提供 GET /api/v1/VisualValidateCallback，供完成 H5 认证后的浏览器跳转使用，不需要携带 API Key。

创建会话时可填写以下地址（替换为实际可访问的 API 域名）：

{
  "CallbackURL": "https://token.kelly.cloud/api/v1/VisualValidateCallback",
  "ProjectName": "default"
}

CallbackURL 填写不带查询参数的页面地址，回调参数由上游追加，不需要自行添加业务标识或认证凭证。手机端认证时，地址必须能由该手机访问，不能填写开发电脑的 localhost。

上游回跳后的地址示例：

https://token.kelly.cloud/api/v1/VisualValidateCallback?bytedToken=EXAMPLE_TOKEN&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time

页面仅展示认证状态及简短提示；成功回跳已匹配并保存后显示绿色圆形勾；素材组查询尚未完成时提示“已收到认证成功结果，素材信息暂未同步”，不展示回调参数或返回首页按钮。诊断参数仅保留在脱敏日志中。独立模板位于 controller/templates/asset_library_visual_callback.html，随 API 编译嵌入，更新 API 并重启即可，无需单独构建前端。API 服务控制台或日志文件中可搜索 [真人认证回调]：

[真人认证回调] 来源=浏览器回跳（未核验） params={"algorithmBaseRespCode":["0"],"bytedToken":["[已隐藏]"],"reqMeasureInfoValue":["1"],"resultCode":["10000"],"verify_type":["real_time"]}

日志保留 resultCode、resultMessage、algorithmBaseRespCode、reqMeasureInfoValue、verify_type 的值，bytedToken 和其他字段隐藏值；页面只显示结果图标和简短提示，不展示参数。服务访问日志也不记录该路径的查询字符串。若反向代理另有访问日志，需要自行配置其查询参数脱敏。

注意回调参数名是小写开头的 bytedToken，而创建响应及查询接口请求字段是 BytedToken。查询时将凭证值原样放入 BytedToken 字段。附加诊断字段仅供排查，不参与平台认证成功判定。真人认证上游日志包含 HTTP 状态、接口路径、版本、请求 ID 和错误码，不记录包含凭证的原始响应；HTTP 404 等查询错误归类为 AssetLibrary.UpstreamRequestFailed。

平台回调页面根据原始 bytedToken 精确匹配本地会话，保存最近回跳时间及结果码。收到 resultCode=10000 时，使用会话创建时的素材渠道、用户及项目自动调用 GetVisualValidateResult；页面区分“成功回跳”和“素材组同步完成”。上游确认返回有效 GroupId 且数据库事务提交成功后，才保存素材组、渠道映射、会话结果组 ID 及首次确认时间，并显示“认证成功”。重复回调不会重复建组，失败回跳不会清除已确认的结果。回跳码只是诊断信息，不能单独作为认证成功依据。

自动查询最长等待 15 秒；上游错误或暂未返回结果时，保留回跳记录，页面提示素材信息暂未同步，可重新打开回调地址或通过 GetVisualValidateResult 重试。没有唯一匹配会话时不会请求上游或新建会话。创建会话的服务与回调域名对应服务必须连接同一业务数据库：例如本地创建、线上回调且两者数据库不同，就无法更新本地记录。第三方客户也可使用自己的回调页面，再主动查询结果。

5.4 真人素材上传与视频引用示例

取得 Result.GroupId 后，可先确认组信息：

如果所选上游允许向该真人组添加图片，调用以下接口。使用有权使用的真人图片公网 URL，替换组 ID 和图片地址；不要再次调用 CreateAssetGroup 创建同名 AIGC 组。

保存实际返回的 Result.Id

检查 ResponseMetadata.Error 和上游返回的素材状态，确认可用后再引用。真人素材的审核、授权及支持的操作由上游执行，收到拒绝时需根据上游错误处理。

下面是开启视频原生请求示例：

此处 model 必须为视频上游支持且平台已配置的模型名；asset:// 后填写 CreateAsset 实际返回的素材 ID。GroupId、BytedToken、H5Link 都不是素材 ID。

5.6 回调、查询与数据库排查

现象	含义与处理
`callback_result_code=10000`，但 `provider_group_id`、`verified_at` 为空	成功回跳已记录，素材组查询或保存还未成功；不能据此判断素材组已经就绪。主动调用 `GetVisualValidateResult` 查看实际结果。
上游 `GetVisualValidateResult` 返回 404	检查 `[真人认证渠道]` 中的渠道 ID、目标地址，以及 `[素材库上游响应]` 的版本、请求 ID 和错误码。仅凭 HTTP 404 无法确定是接口地址、Action 支持情况还是认证资源问题；不要直接把目标改成官方地址。
上游返回 `403 AccessDenied`	检查认证会话原渠道所用 AK/SK 对该项目及接口的权限。
`AssetLibrary.VisualSessionUnavailable`	核对凭证是否由当前用户经本平台创建、回调是否连接同一数据库、原渠道是否仍启用且配置版本一致。
只打开 H5，没有收到回调	确认已完成 H5 操作并点击完成，检查手机是否能访问 `CallbackURL`。也可使用保存的凭证主动查询；无需额外添加 `trace_id` 参数。
`verified_at` 已填写但平台账号仍未实名认证	正常。这里保存的是素材真人认证结果，与平台账号的个人 / 企业实名认证分开。

数据库以业务库为准：会话及回跳信息在 asset_library_visual_sessions；获取成功的真人组在 asset_library_groups 和 asset_library_group_channels；后续素材在 asset_libraries 和 asset_library_channel_assets。byted_token 是原始认证凭证，provider_group_id 是上游真人组 ID，两者不要混用。

6. 素材状态说明

状态	说明
`Pending`	等待提交到素材渠道。
`Uploading`	正在向素材渠道提交。
`Processing`	渠道已受理，正在处理。
`Ready`	素材已处理完成，可以使用。
`Failed`	上传或处理失败，可结合 `Error` 查看原因。

视频素材通常比图片和音频需要更长处理时间。轮询 GetAsset 时建议采用退避策略，避免高频请求。

7. 错误响应

{
  "ResponseMetadata": {
    "RequestId": "20260328000000000000000000000000",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "AssetLibrary.InvalidRequest",
      "Message": "invalid request: Version query parameter must be 2024-01-01"
    }
  },
  "Result": {}
}

常见错误码：

错误码	说明
`AssetLibrary.InvalidRequest`	查询参数、JSON 或必填字段不符合要求。
`AssetLibrary.InvalidName`	名称为空或超过 64 个字符。
`AssetLibrary.InvalidDescription`	描述超过 300 个字符。
`AssetLibrary.InvalidGroupType`	`GroupType` 不受支持。
`AssetLibrary.InvalidAssetType`	`AssetType` 不受支持。
`AssetLibrary.InvalidProjectName`	`ProjectName` 超过 64 个字符。
`AssetLibrary.InvalidURL`	URL 无效、过长或不是绝对 HTTP/HTTPS 地址。
`AssetLibrary.InvalidPagination`	页码或每页数量不符合要求。
`AssetLibrary.InvalidSort`	排序字段或排序方向不受支持。
`AssetLibrary.InvalidStatus`	素材状态筛选值不受支持。
`AssetLibrary.GroupNotFound`	素材组不存在或不属于当前用户。
`AssetLibrary.AssetNotFound`	素材不存在或不属于当前用户。
`AssetLibrary.GroupNameConflict`	当前用户已存在同名素材组。
`AssetLibrary.ChannelNotConfigured`	尚未配置可用素材渠道。
`AssetLibrary.ChannelDisabled`	当前素材渠道已禁用。
`AssetLibrary.ChannelGroupSyncing`	素材组正在同步，请稍后重试。
`AssetLibrary.ChannelGroupNotReady`	素材组尚未在当前渠道准备完成。
`AssetLibrary.UpstreamRequestFailed`	素材渠道请求失败。
`AssetLibrary.UpstreamInvalidResponse`	素材渠道响应无效。
`AssetLibrary.DatabaseError`	数据库操作失败。
`AssetLibrary.InternalError`	未分类的内部错误。

素材资产（Assets）API 对接文档

1. 接入说明#

1.1 请求地址#

1.2 公共查询参数#

1.3 公共请求头#

1.4 公共响应结构#

1.5 ProjectName 和业务 ID#

2. 接口清单#

3. 素材接口#

3.1 创建素材（CreateAsset）#

请求体#

素材规格#

请求示例#

响应参数#

3.2 查询素材（GetAsset）#

请求体#

响应参数#

3.3 更新素材（UpdateAsset）#

请求体#

成功响应#

3.4 删除素材（DeleteAsset）#

请求体#

成功响应#

3.5 查询素材列表（ListAssets）#

请求体#

响应参数#

4. 素材组接口#

4.1 创建素材组（CreateAssetGroup）#

请求体#

成功响应#

4.2 查询素材组（GetAssetGroup）#

请求体#

响应参数#

4.3 更新素材组（UpdateAssetGroup）#

请求体#

成功响应#

4.4 删除素材组（DeleteAssetGroup）#

请求体#

成功响应#

4.5 查询素材组列表（ListAssetGroups）#

请求体#

响应参数#

5. 真人认证 H5 与素材组#

5.0 真人与虚拟人像的区别#

5.1 创建真人认证会话#

5.2 获取真人素材组 ID#

5.3 平台回调页面与调试日志#

5.4 真人素材上传与视频引用示例#

5.6 回调、查询与数据库排查#

6. 素材状态说明#

7. 错误响应#

1. 接入说明

1.1 请求地址

1.2 公共查询参数

1.3 公共请求头

1.4 公共响应结构

1.5 ProjectName 和业务 ID

2. 接口清单

3. 素材接口

3.1 创建素材（CreateAsset）

请求体

素材规格

请求示例

响应参数

3.2 查询素材（GetAsset）

请求体

响应参数

3.3 更新素材（UpdateAsset）

请求体

成功响应

3.4 删除素材（DeleteAsset）

请求体

成功响应

3.5 查询素材列表（ListAssets）

请求体

响应参数

4. 素材组接口

4.1 创建素材组（CreateAssetGroup）

请求体

成功响应

4.2 查询素材组（GetAssetGroup）

请求体

响应参数

4.3 更新素材组（UpdateAssetGroup）

请求体

成功响应

4.4 删除素材组（DeleteAssetGroup）

请求体

成功响应

4.5 查询素材组列表（ListAssetGroups）

请求体

响应参数

5. 真人认证 H5 与素材组

5.0 真人与虚拟人像的区别

5.1 创建真人认证会话

5.2 获取真人素材组 ID

5.3 平台回调页面与调试日志

5.4 真人素材上传与视频引用示例

5.6 回调、查询与数据库排查

6. 素材状态说明

7. 错误响应