Active 状态后,可以在创建视频生成任务时以 asset://<素材ID> 引用。
接口列表
所有管理动作使用同一个地址,通过Action 区分:
BaseUrl为https://api-vip.apigo.ai,见使用概述。Version固定为2024-01-01。- 请求和响应字段区分大小写,例如
URL、AssetType、GroupId、Status。 ProjectName为可选参数,可传default或不传。
鉴权
签名参数:
请求示例:
X-Date为 UTC 时间,格式YYYYMMDDTHHMMSSZ,与服务端时间相差不能超过 15 分钟。- 签名基于实际发送的请求体字节。签名后修改请求体、
Action、Host或X-Date都需要重新签名。
签名算法
<YYYYMMDD> 取同一个 X-Date 的日期部分。SK 直接使用 API Key,不加任何前缀。
签名代码
- Go(火山 SDK)
- Python(标准库)
使用火山引擎 Go SDK,调用其他动作时,修改
DoCall 自动完成签名。需要 Go 1.22 或更高版本。main.go
Action 和请求体即可。X-Date、X-Content-Sha256 和 Authorization,再按原样发送同一份请求体。
响应结构
成功时 HTTP 200,业务数据位于Result:
Result,错误位于 ResponseMetadata.Error:
素材状态
CreateAsset 返回素材 ID 后,素材通常处于 Processing。通过 GetAsset 轮询到 Active 后再用于生成,处理时长不固定。
真人素材
素材组分为两种类型:
以真人人像作为参考生成视频时,需先由本人完成活体认证,再把本人照片导入认证生成的真人素材组:
- 调用 CreateVisualValidateSession,取得
BytedToken和H5Link。 - 本人在手机浏览器中打开
H5Link完成刷脸。 - 调用 GetVisualValidateResult 轮询,成功后取得
GroupId。 - 调用 CreateAsset,
GroupId传上一步的真人素材组 ID,URL传本人照片。 - GetAsset 返回
Active后,在生成任务中以asset://<素材ID>引用。
- 每次认证成功都会生成一个新的真人素材组,组名称为空,可用 UpdateAssetGroup 设置名称和描述。
- 真人素材组只能导入认证本人的照片。照片与认证人不一致时,素材状态变为
Failed,Error.Code为FaceMismatch。 - 查询真人素材组或其中的素材时,
ListAssetGroups/ListAssets的Filter.GroupType传LivenessFace。 - 真人素材组可通过 DeleteAssetGroup 删除,组内素材一并删除。
分页
ListAssetGroups 和 ListAssets 支持两种分页方式,每次请求只能选择一种。
NextToken 分页(默认)
- 响应不含
NextToken时表示已到最后一页。 - 翻页时保持
Filter、SortBy、SortOrder不变,NextToken原样传回。 - 此方式不返回
TotalCount。
页码分页
PageNumber和PageSize必须同时传,且不能与MaxResults、NextToken同时使用。- 响应返回
TotalCount、PageNumber、PageSize。 - 翻页深度上限:
ListAssetGroups为PageNumber × PageSize ≤ 10000,ListAssets为PageNumber × PageSize ≤ 20000,超出返回400 InvalidParameter。需要遍历更多数据时使用 NextToken 分页。
错误码
素材导入失败可能以两种形式出现:
CreateAsset 直接返回错误,或创建成功后 GetAsset 返回 Status=Failed。