真人人像素材库

约 1799 字大约 6 分钟

真人人像素材库用于经过本人授权的真人形象素材。它与虚拟人像素材库的主要区别是：创建素材前必须完成真人认证流程，并取得认证结果返回的 GroupId。

完整流程

创建认证会话
  -> 取得 session_id 和 H5Link
  -> 将本人引导到 H5Link 完成认证
  -> 查询认证结果
  -> 认证成功并取得 GroupId
  -> 创建真人素材
  -> 查询素材状态
  -> 在支持的模型中引用素材

授权要求：认证页面必须由素材对应的本人操作。不要代替他人完成认证，也不要提交未获得合法授权的照片、视频或身份信息。

创建真人认证会话

POST https://mivsub.com/api/v3/ark/real-person/validate/sessions
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`CallbackURL`	string	否	认证完成后的服务端回调地址，以渠道支持范围为准
`ProjectName`	string	否	项目名称，以渠道支持范围为准

没有回调地址时也应发送 JSON 对象：

{}

带回调地址的示例：

{
  "CallbackURL": "https://api.example.com/real-person/callback",
  "ProjectName": "default"
}

响应示例：

{
  "session_id": "rpv_1GTcAKZeayoIjWXIimSIyEqa",
  "BytedToken": "byted-token-example",
  "H5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=example&uid=example",
  "CallbackURL": "https://api.example.com/real-person/callback",
  "status": "pending",
  "ProjectName": "default"
}

字段	类型	说明
`session_id`	string	后续查询认证结果使用的会话 ID
`BytedToken`	string	上游认证令牌；仅在渠道要求时使用
`H5Link`	string	需要交给本人打开的认证页面
`CallbackURL`	string	上游确认的回调地址
`status`	string	当前认证状态，初始状态通常为 `pending`
`ProjectName`	string	会话所属项目
`ExpireTime`	string / integer	认证链接过期时间，仅在上游返回时存在

认证链接通常具有时效性。业务侧应尽快引导用户打开，并避免把 BytedToken 写入前端日志或公开页面。

查询真人认证结果

GET https://mivsub.com/api/v3/ark/real-person/validate/sessions/rpv_1GTcAKZeayoIjWXIimSIyEqa
Authorization: Bearer sk-frameai-xxxxxxxx

将路径最后一段替换为创建会话返回的 session_id。需要指定项目时，可以追加 ?ProjectName=default。请求字段：

字段	位置	类型	必填	说明
`session_id`	path	string	是	创建认证会话时返回的会话 ID
`ProjectName`	query	string	否	项目名称

处理中响应示例：

{
  "session_id": "rpv_1GTcAKZeayoIjWXIimSIyEqa",
  "status": "pending",
  "ProjectName": "default"
}

成功响应示例：

{
  "session_id": "rpv_1GTcAKZeayoIjWXIimSIyEqa",
  "GroupId": "group-xxxxxxxx",
  "status": "succeeded",
  "resultCode": "10000",
  "algorithmBaseRespCode": "0",
  "reqMeasureInfoValue": "1",
  "verify_type": "real_time",
  "ProjectName": "default"
}

响应字段：

字段	类型	说明
`session_id`	string	当前认证会话 ID
`GroupId`	string	认证成功后分配的真人素材组 ID；创建真人素材时使用
`status`	string	认证状态，例如 `pending`、`succeeded`、`failed` 或 `expired`
`resultCode`	string / integer	上游认证业务结果码
`algorithmBaseRespCode`	string / integer	上游算法基础响应码
`reqMeasureInfoValue`	string	上游认证测量结果字段，仅在渠道返回时存在
`verify_type`	string	认证方式，例如 `real_time`
`ProjectName`	string	会话所属项目
`message`	string	认证失败或状态异常时的说明，仅在上游返回时存在

只有认证状态成功且 GroupId 非空时，才能进入创建真人素材步骤。

认证成功后保存 GroupId，创建真人素材时必须使用它。若渠道返回的状态名不同，应以该渠道的成功状态和结果字段为准。

建议每 3 至 10 秒查询一次，不要高频并发轮询同一会话。会话过期或认证失败时，重新创建认证会话，不要继续复用旧链接。

创建真人素材

POST https://mivsub.com/api/v3/ark/real-person/assets
Authorization: Bearer sk-frameai-xxxxxxxx
Content-Type: application/json

请求体：

字段	类型	必填	说明
`GroupId`	string	是	真人认证成功后返回的素材组 ID
`URL`	string	是	本人已授权且服务端可直接下载的公网素材 URL
`Name`	string	否	素材名称
`AssetType`	string	否	素材类型，常见为 `Image`
`ProjectName`	string	否	项目名称

{
  "GroupId": "group-xxxxxxxx",
  "URL": "https://cdn.example.com/authorized/portrait.png",
  "Name": "已授权真人形象素材",
  "AssetType": "Image",
  "ProjectName": "default"
}

成功响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260809102000A1B2C3",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-real-xxxxxxxx"
  }
}

响应字段：

字段	类型	说明
`ResponseMetadata.RequestId`	string	上游请求唯一 ID
`ResponseMetadata.Action`	string	本接口通常为 `CreateAsset`
`Result.Id`	string	新创建的真人素材 ID
`Result.Status`	string	初始素材状态，仅在上游创建响应中返回时存在

Result.Id 是真人素材 ID。创建成功后仍需查询详情，等待素材审核和处理完成。

查询真人素材

GET https://mivsub.com/api/v3/ark/real-person/assets/asset-real-xxxxxxxx
Authorization: Bearer sk-frameai-xxxxxxxx

需要指定项目时，可以追加 ?ProjectName=default。请求字段：

字段	位置	类型	必填	说明
`asset_id`	path	string	是	创建真人素材时返回的素材 ID
`ProjectName`	query	string	否	项目名称

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260809102100D4E5F6",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-real-xxxxxxxx",
    "Name": "已授权真人形象素材",
    "URL": "https://cdn.example.com/authorized/portrait.png",
    "AssetType": "Image",
    "GroupId": "group-xxxxxxxx",
    "Status": "Active",
    "Moderation": {
      "Strategy": "default"
    },
    "ProjectName": "default"
  }
}

响应字段：

字段	类型	说明
`ResponseMetadata.RequestId`	string	上游请求唯一 ID
`ResponseMetadata.Action`	string	本接口通常为 `GetAsset`
`Result.Id`	string	真人素材 ID
`Result.Name`	string	素材名称
`Result.URL`	string	渠道返回的素材访问地址
`Result.AssetType`	string	素材类型，常见为 `Image`
`Result.GroupId`	string	真人认证成功后取得的素材组 ID
`Result.Status`	string	素材处理状态
`Result.Moderation`	object	内容审核或策略信息
`Result.Moderation.Strategy`	string	审核策略名称
`Result.ProjectName`	string	所属项目
`Result.CreateTime`	string / integer	创建时间，存在时由上游返回
`Result.UpdateTime`	string / integer	最后更新时间，存在时由上游返回
`Result.Error`	object	素材处理失败信息，仅失败状态可能返回
`Result.Error.Code`	string	失败错误码
`Result.Error.Message`	string	失败错误详情

状态	处理方式
`Processing` / `pending`	继续低频轮询
`Active` / `succeeded`	素材已可用，以模型实际支持为准
`Failed` / `failed`	读取上游错误，检查授权、素材内容、格式和 URL
`Expired`	重新发起认证或重新创建素材

在视频请求中引用

渠道和模型支持素材协议时，可以把真人素材 ID 作为参考素材 URL：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "保持已授权人物的外观一致，生成自然转身并微笑的视频"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "asset://asset-real-xxxxxxxx"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}