虚拟人像素材 API 文档
本文介绍访问令牌、素材组和素材接口的参数与返回结果。按下方步骤完成认证后，即可查询和管理已授权的素材。
01 / QUICK START
三步开始调用
01
领取合作方凭证
由网关运营方提供 client_id 和 client_secret，每个合作方单独分配。
02
换取访问令牌
调用 POST /v1/token，得到默认有效 24 小时的 access_token。
03
调用素材接口
在请求头附上 Bearer Token，查询或管理获授权的素材组和素材。
在在线调试页，先调用「换取访问令牌」，再点右上角 Authorize（授权），粘贴 access_token。令牌默认有效 24 小时，实际以返回的 expires_in（秒）为准；过期后重新换取。
02 / AUTHENTICATION
获取访问令牌
合作方凭证只用于换取访问令牌。令牌默认有效 24 小时，实际以返回的 expires_in（秒）为准；过期后可再次换取。后续调用使用令牌，服务端会根据合作方的素材组授权范围返回数据。
POST/v1/token
填写合作方凭证
client_id 和 client_secret 由运营方单独发放。
{"client_id":"你的 client_id",
"client_secret":"你的 client_secret"}
HEADERAuthorization
携带访问令牌
从换取令牌接口复制 access_token，后续请求均带上此请求头。
Authorization: Bearer 你的 access_token
03 / API REFERENCE
在线调试 ↗接口参考
下面的接口说明和参数会从网关当前的 OpenAPI 文档读取，页面与实际接口保持同步。点击任一接口查看填写要求。
正在加载接口说明…
04 / RESPONSES
状态码与常见问题
| HTTP 状态码 | 含义 | 建议处理 |
|---|---|---|
| 200 / 201 | 查询、修改或创建成功 | 读取返回的 JSON；创建后保存 id。 |
| 204 | 删除成功 | 没有响应正文。 |
| 400 / 422 | 参数格式或取值有误 | 核对字段名、必填项、素材类型和 URL。 |
| 401 | 凭证或令牌无效 | 重新换取访问令牌；仍失败时核对合作方凭证。 |
| 404 | 资源不存在或无权访问 | 核对素材组 ID、素材 ID 和授权范围。 |
| 429 | 请求过于频繁 | 稍后重试。 |
| 502 / 503 | 上游或网关暂时不可用 | 稍后重试；持续出现时联系运营方。 |
创建素材后查询不到可用状态？ 创建素材是异步处理。请用返回的 asset ID 查询详情：Processing 表示处理中，Active 表示可用，Failed 表示失败。