跳到主要内容

查询分组详情

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

按分组 ID 查询单个素材分组的详情,包括虚拟素材分组与真人分组。

请求参数​

Action 与 Version 通过查询参数传递,其余参数放在 JSON 请求体中。

Idstring必填

分组 ID。传真人分组 ID(group-xxx)可查询真人分组详情。

默认值:-
字段与列表一致

返回的字段与 ListAssetGroups 中 Items 的元素完全一致。真人分组额外返回 AuthorizedAt 与 ModelIds。

真人分组的响应示例:

{
"Id": "group-20261112100048-z5wk7",
"Name": "张三",
"Description": null,
"GroupType": "LivenessFace",
"AuthorizedAt": "2026-11-12T10:00:48Z",
"ModelIds": ["Doubao-Seedance-2.5"],
"CreateTime": "2026-11-12T10:00:48Z",
"UpdateTime": "2026-11-12T10:00:48Z"
}

认证​

所有接口使用同一套 V4 签名,凭证与签名方式见火山方舟素材库 API 概览。以下请求头为通用要求:

Content-Typestring必填

固定为 application/json。

默认值:application/json
Hoststring必填

实际访问的域名和端口;包含端口时必须写入签名。

默认值:-
X-Datestring必填

UTC 时间,格式 yyyyMMdd'T'HHmmss'Z',例如 20261022T131900Z;与平台时间偏差不能超过 300 秒。

默认值:-
X-Content-Sha256string必填

原始请求体的 SHA-256 小写十六进制。

默认值:-
Authorizationstring必填

V4 HMAC-SHA256 签名。

默认值:-

响应​

Result.Idstring可选

分组 ID。真人分组为 group-xxx 形态。

默认值:-
Result.Namestring可选

分组名称。

默认值:-
Result.Descriptionstring可选

分组描述,通常为 null。

默认值:-
Result.GroupTypestring可选

分组类型:AIGC、LivenessFace。

默认值:-
Result.AuthorizedAtstring可选

真人分组的认证完成时间(ISO-8601);AIGC 分组不返回该字段。

默认值:-
Result.ModelIdsarray<string>可选

真人分组适用的模型列表;AIGC 分组不返回该字段。

默认值:-
Result.CreateTimestring可选

创建时间,UTC 时间字符串。

默认值:-
Result.UpdateTimestring可选

更新时间,UTC 时间字符串。

默认值:-

错误​

Code说明
400InvalidParameter:参数格式或取值非法
401SignatureDoesNotMatch、InvalidTimestamp、XContentSha256Mismatch、MissingParameter.Authorization 等签名或时间相关错误
403AccessDenied 凭证被禁用或无权限;ExpiredToken 凭证已过期
404NotFound.group_id 分组不存在
429QuotaWriteQPMExceeded 每分钟写入额度用尽;AccountFlowLimitExceeded 每秒请求上限触发;TooManyRequests 请求过于频繁

相关​