真人素材授權

真人素材必須由本人完成手機端採集和授權，不能用一般圖片上傳代替。

建立真人掃碼工作階段

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	授權頁面位址，轉成 QR 碼交給真人本人
`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`	`素材服务暂不可用`	工作階段不存在、尚未完成採集，或真人採集通道尚未就緒

本頁目錄