docs: add reallife_asset API section to unified api_doc.md

wwwroot/api_doc.md

@@ -634,3 +634,236 @@ Authorization: Bearer ***
 ### 计费
 
 请求成功后自动创建 `llmusage` 记录，状态为 `created`。后台定时任务会定期执行计费流程。
+
+---
+
+# 真人素材 API
+
+真人素材 API 提供真人人像认证、素材上传和素材管理功能。使用与大模型 API 相同的 APIKEY 认证。
+
+**Base URL**: `https://token.opencomputing.cn`
+
+**认证**: Bearer Token（与大模型 API 相同）
+
+## 业务流程
+
+1. **真人认证**：发起认证请求，获取 H5 链接供终端用户完成人脸识别
+2. **查询已认证组合**：查询当前机构下所有已认证的组合 ID
+3. **上传素材**：使用已认证的组合 ID 上传图片/视频
+4. **状态同步**：轮询检查素材处理状态
+
+---
+
+## POST /reallife_asset/api/rl_verify.dspy
+
+获取真人认证链接（H5）。
+
+### 请求参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `vendor` | 是 | 供应商标识 |
+| `project_name` | 否 | 项目名称，默认 `default` |
+| `name` | 否 | 认证名称，方便识别 |
+
+> `user_id` 和 `org_id` 由 Bearer Token 自动获取
+
+### 请求示例
+
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_verify.dspy' \
+  -H 'Authorization: Bearer *** \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "vendor": "volcengine",
+    "project_name": "default",
+    "name": "张三"
+  }'
+```
+
+### 响应示例
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "id": "local_group_id_xxx",
+    "h5_link": "https://... (H5页面链接，120秒有效)",
+    "byted_token": "..."
+  }
+}
+```
+
+---
+
+## POST /reallife_asset/api/rl_query_groups.dspy
+
+查询已认证的组合列表。
+
+### 请求参数
+
+无需参数，系统自动从 Bearer Token 获取 `org_id`。
+
+### 请求示例
+
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_query_groups.dspy' \
+  -H 'Authorization: Bearer ***
+```
+
+### 响应示例
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "groups": [
+      {
+        "vendor_group_id": "volc-asset-group-xxx",
+        "vendor": "volcengine",
+        "name": "模特张三",
+        "status": "active",
+        "create_time": "2026-05-28 15:30:00"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## POST /reallife_asset/api/rl_upload.dspy
+
+上传素材到已认证的组合。
+
+### 请求参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `vendor_group_id` | 是 | 已认证的组合 ID |
+| `source_url` | 是 | 素材 URL 或 `data:` base64 编码 |
+| `asset_type` | 否 | `Image`（默认）或 `Video` |
+| `name` | 否 | 素材名称 |
+
+### 请求示例
+
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_upload.dspy' \
+  -H 'Authorization: Bearer *** \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "vendor_group_id": "volc-asset-group-xxx",
+    "source_url": "https://bucket.oss.com/photo.jpg",
+    "asset_type": "Image",
+    "name": "模特A"
+  }'
+```
+
+### 响应示例
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "id": "asset_record_id_xxx",
+    "vendor_asset_id": "asset-2026...",
+    "status": "Processing"
+  }
+}
+```
+
+> 上传是异步操作，需调用 `rl_status` 轮询状态。
+
+---
+
+## POST /reallife_asset/api/rl_status.dspy
+
+查询素材处理状态。
+
+### 请求参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `asset_id` | 是 | 上传时返回的记录 ID |
+
+### 请求示例
+
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_status.dspy' \
+  -H 'Authorization: Bearer *** \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "asset_id": "asset_record_id_xxx"
+  }'
+```
+
+### 响应示例
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "status": "Active",
+    "url": "https://... (临时下载链接，12小时有效)"
+  }
+}
+```
+
+> 素材永久存储。`url` 过期后可再次调用获取新链接。
+
+---
+
+## POST /reallife_asset/api/rl_assets.dspy
+
+查询组合下所有素材。
+
+### 请求参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `vendor_group_id` | 是 | 已认证的组合 ID |
+
+### 请求示例
+
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_assets.dspy' \
+  -H 'Authorization: Bearer *** \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "vendor_group_id": "volc-asset-group-xxx"
+  }'
+```
+
+### 响应示例
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "assets": [
+      {
+        "id": "asset_record_id_xxx",
+        "vendor_asset_id": "asset-2026...",
+        "name": "模特A",
+        "asset_type": "Image",
+        "status": "Active",
+        "url": "https://...",
+        "create_time": "2026-05-28 15:30:00"
+      }
+    ],
+    "total": 3
+  }
+}
+```
+
+---
+
+## 真人素材错误说明
+
+| 错误信息 | 原因 | 解决方案 |
+|----------|------|----------|
+| `供应商配置不存在` | 未配置 AK/SK | 联系管理员 |
+| `供应商服务已停用` | 配置非 active | 联系管理员激活 |
+| `无效的素材组合ID或无权访问` | ID 不属于当前机构 | 检查认证和 ID |
+| `素材不存在或无权访问` | ID 无效 | 检查 ID |
+| `尚未完成认证或认证失败` | 认证未完成 | 等待 H5 认证完成 |