真人素材授权

真人素材必须由本人完成手机端采集和授权，不能用普通图片上传代替。

创建真人扫码会话

POST/api/v1/materials/portrait/sessions

认证方式

Authorization: Bearer <API_KEY>。

请求体 · application/json

参数	类型	必填	说明
`continuous_create`	boolean	否	为 `true` 时，解析完成后继续创建下一个授权会话

请求示例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/portrait/sessions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"continuous_create":false}'

响应参数

参数	类型	说明
`code`	integer	成功时为 `0`
`msg`	string	成功时为 `真人授权会话已创建`
`data.session.authorization_url`	string	授权页面地址，转成二维码交给真人本人
`data.session.session_token`	string	会话令牌，只保存在服务端
`data.session.expires_in`	integer	会话有效期（秒）
`data.session.expire_time`	string	会话到期时间（ISO 时间字符串）

响应体

{
  "code": 0,
  "data": {
    "session": {
      "authorization_url": "https://授权页面地址",
      "session_token": "session-token",
      "expires_in": 600,
      "expire_time": "2026-09-09T08:10:00.000Z"
    }
  },
  "msg": "真人授权会话已创建"
}

session_token 不要写入日志、发送给其他账户或长期留存；会话过期后重新创建。

错误响应

HTTP	msg	说明
`400`	`请求体必须是 JSON 对象`	请求体不是合法 JSON
`401`	`Invalid token`	API Key 缺失、错误或已失效
`503`	`素材服务暂不可用`	真人采集通道未就绪，保留请求时间后联系平台支持

确认真人扫码完成

POST/api/v1/materials/portrait/resolve

认证方式

Authorization: Bearer <API_KEY>。

请求体 · application/json

参数	类型	必填	说明
`session_token`	string	是	创建扫码会话返回的 `data.session.session_token`

请求示例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/portrait/resolve" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_token":"session-token"}'

响应参数

参数	类型	说明
`code`	integer	成功时为 `0`
`msg`	string	成功时为 `真人授权已完成`
`data.group.id`	string	采集生成的真人素材分组 ID
`data.group.name`	string	分组名称
`data.group.type`	string	固定为 `real`
`data.group.description`	string / null	分组说明

响应体

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-20260911034940-lrtht",
      "name": "真人素材库",
      "type": "real",
      "description": null
    }
  },
  "msg": "真人授权已完成"
}

解析成功后调用同步素材状态并查询素材列表，读取真人素材的 asset_id 与 status。

错误响应

HTTP	msg	说明
`400`	`请求体必须是 JSON 对象`	请求体不是合法 JSON
`401`	`Invalid token`	API Key 缺失、错误或已失效
`503`	`素材服务暂不可用`	会话不存在、尚未完成采集，或真人采集通道未就绪

本页目录