docs: add Downapp API documentation

2026-05-28 16:29:13 +08:00 · 2026-05-28 16:29:13 +08:00 · 4280ad6894
commit 4280ad6894
parent 530f337704
1 changed files with 192 additions and 0 deletions
--- a/docs/api_downapp.md
+++ b/docs/api_downapp.md
@ -0,0 +1,192 @@
+# Downapp API 接口文档
+
+## 概述
+本文档说明下游应用（Downapp）如何调用 `reallife_asset` 模块接口，完成真人人像素材的申请、认证、上传及状态查询。
+
+**核心机制**：
+- 所有接口均通过 `downapp_id` 标识调用方。
+- 模块内部会自动检查调用方是否已开通服务（状态为 `active`）。
+- 密钥（AK/SK）由营运人员在后台维护，调用方无需在请求中传递。
+
+## 业务流程
+
+1. **申请开通**：调用方提交申请 (`rl_apply`)。
+2. **人工审批**：营运人员审核申请，回填火山引擎 AK/SK，并激活账户 (`active`)。
+3. **真人认证**：调用方发起认证请求，获取 H5 链接供终端用户完成人脸识别 (`rl_verify`)。
+4. **上传素材**：认证成功后，使用获取到的 `Group ID` 上传图片/视频 (`rl_upload`)。
+5. **状态同步**：轮询检查素材处理状态，直到变为 `Active` 可用 (`rl_status`)。
+
+---
+
+## 1. 申请开通服务
+**Endpoint**: `/reallife_asset/api/rl_apply.dspy`
+
+登记调用方信息，申请开通真人素材上传权限。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `vendor` | 是 | 供应商名称，如 `volcengine` |
+| `callback_url` | 是 | 真人认证完成后的回调地址 |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_apply.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "vendor": "volcengine",
+  "callback_url": "https://example.com/callback"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "app_id": "record_id_xxx",
+  "status": "pending"
+}
+```
+**失败**（已存在记录）：
+```json
+{
+  "success": false,
+  "message": "已提交申请，请等待审批"
+}
+```
+
+---
+
+## 2. 获取真人认证链接 (H5)
+**Endpoint**: `/reallife_asset/api/rl_verify.dspy`
+
+检查审批状态通过后，调用供应商接口创建认证会话。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `project_name` | 否 | 项目名称，默认 `default` |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_verify.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "project_name": "default"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "id": "local_group_id_xxx",
+  "h5_link": "https://... (H5页面链接，120秒有效)",
+  "byted_token": "..."
+}
+```
+**失败**（未开通）：
+```json
+{
+  "success": false,
+  "message": "申请状态: pending，未通过审批"
+}
+```
+
+**注意**：终端用户在 H5 页面完成认证后，供应商将回调 `rl_apply` 中设置的 `callback_url`。
+
+---
+
+## 3. 上传素材
+**Endpoint**: `/reallife_asset/api/rl_upload.dspy`
+
+向已认证的素材组合上传图片或视频素材。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `group_id` | 是 | 真人认证成功后获取的本地组合 ID |
+| `source_url` | 是 | 素材的公网可访问 URL |
+| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
+| `name` | 否 | 素材名称 |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_upload.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "group_id": "local_group_id_xxx",
+  "source_url": "https://bucket.oss.com/photo.jpg",
+  "asset_type": "Image",
+  "name": "模特A"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "id": "asset_record_id_xxx",
+  "vendor_asset_id": "asset-2026...",
+  "status": "Processing"
+}
+```
+
+**注意**：上传是异步操作，初始状态为 `Processing`，需调用第 4 个接口轮询状态。
+
+---
+
+## 4. 查询素材状态
+**Endpoint**: `/reallife_asset/api/rl_status.dspy`
+
+查询素材的处理状态（Processing / Active / Failed）。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `asset_id` | 是 | 上传素材时返回的本地记录 ID |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_status.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "asset_id": "asset_record_id_xxx"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "status": "Active",
+  "url": "https://... (素材下载链接，12小时有效)"
+}
+```
+
+---
+
+## 错误代码说明
+
+| 错误信息 | 原因 | 解决方案 |
+|----------|------|----------|
+| `未申请或供应商不支持` | `downapp_id` 不存在 | 确认是否已调用申请接口 |
+| `申请状态: xxx，未通过审批` | 状态非 `active` | 联系营运人员审核 |
+| `素材组合不存在` | `group_id` 无效 | 确认是否已通过认证获取有效 ID |
+| `参数缺失` | 缺少必填参数 | 检查请求 Body |