# 真人素材授权 (/docs/user/materials/api/portrait)



# 真人素材授权 [#真人素材授权]

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

## 创建真人扫码会话 [#创建真人扫码会话]

<Endpoint method="POST" path="/api/v1/materials/portrait/sessions" />

### 认证方式 [#认证方式]

`Authorization: Bearer <API_KEY>`。

### 请求体 · application/json [#请求体--applicationjson]

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

### 请求示例 [#请求示例]

```bash
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 时间字符串）  |

### 响应体 [#响应体]

```json
{
  "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` | `素材服务暂不可用`       | 真人采集通道未就绪，保留请求时间后联系平台支持 |

## 确认真人扫码完成 [#确认真人扫码完成]

<Endpoint method="POST" path="/api/v1/materials/portrait/resolve" />

### 认证方式 [#认证方式-1]

`Authorization: Bearer <API_KEY>`。

### 请求体 · application/json [#请求体--applicationjson-1]

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

### 请求示例 [#请求示例-1]

```bash
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"}'
```

### 响应参数 [#响应参数-1]

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

### 响应体 [#响应体-1]

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

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

### 错误响应 [#错误响应-1]

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