跳转到主要内容
素材库用于管理视频生成的参考图片、音频和视频。素材导入并处于 Active 状态后,可以在创建视频生成任务时以 asset://<素材ID> 引用。

接口列表

所有管理动作使用同一个地址,通过 Action 区分:
  • BaseUrl 为 https://api-vip.apigo.ai,见使用概述。
  • Version 固定为 2024-01-01。
  • 请求和响应字段区分大小写,例如 URL、AssetType、GroupId、Status。
  • ProjectName 为可选参数,可传 default 或不传。

鉴权

素材库管理接口使用 HMAC-SHA256 签名,不支持 Authorization: Bearer。视频生成接口使用 Bearer。两者使用同一个 ApiGo API Key。
签名参数: 请求示例:
  • X-Date 为 UTC 时间,格式 YYYYMMDDTHHMMSSZ,与服务端时间相差不能超过 15 分钟。
  • 签名基于实际发送的请求体字节。签名后修改请求体、Action、Host 或 X-Date 都需要重新签名。

签名算法

<YYYYMMDD> 取同一个 X-Date 的日期部分。SK 直接使用 API Key,不加任何前缀。

签名代码

使用火山引擎 Go SDK,DoCall 自动完成签名。需要 Go 1.22 或更高版本。
main.go
调用其他动作时,修改 Action 和请求体即可。
curl 不能自动生成签名。使用 curl 时,先用上面的代码算出 X-Date、X-Content-Sha256 和 Authorization,再按原样发送同一份请求体。

响应结构

成功时 HTTP 200,业务数据位于 Result:
失败时没有 Result,错误位于 ResponseMetadata.Error:

素材状态

CreateAsset 返回素材 ID 后,素材通常处于 Processing。通过 GetAsset 轮询到 Active 后再用于生成,处理时长不固定。

真人素材

素材组分为两种类型: 以真人人像作为参考生成视频时,需先由本人完成活体认证,再把本人照片导入认证生成的真人素材组:
  1. 调用 CreateVisualValidateSession,取得 BytedToken 和 H5Link。
  2. 本人在手机浏览器中打开 H5Link 完成刷脸。
  3. 调用 GetVisualValidateResult 轮询,成功后取得 GroupId。
  4. 调用 CreateAsset,GroupId 传上一步的真人素材组 ID,URL 传本人照片。
  5. 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。