yumoqing/reallife_asset
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
yumoqing 2026-05-28 16:45:31 +08:00
parent 2cd0974909
commit 3ad9b2bb46
1 changed files with 16 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/api_downapp.md
View File

@ -10,66 +10,23 @@
## 业务流程
1. **申请开通**：调用方提交申请 (`rl_apply`)。
2. **人工审批**：营运人员审核申请，回填火山引擎 AK/SK，并激活账户 (`active`)。
3. **真人认证**：调用方发起认证请求，获取 H5 链接供终端用户完成人脸识别 (`rl_verify`)。
4. **上传素材**：认证成功后，使用获取到的 `Group ID` 上传图片/视频 (`rl_upload`)。
5. **状态同步**：轮询检查素材处理状态，直到变为 `Active` 可用 (`rl_status`)。
1. **人工配置**：营运人员在 `rl_vendor_config` 表中登记供应商的全局 AK/SK 并激活状态。
2. **真人认证**：调用方发起认证请求 (`rl_verify`)，获取 H5 链接供终端用户完成人脸识别。
3. **自动映射**：认证成功后，系统自动登记该机构 (`org_id`) 与供应商组合 ID (`vendor_group_id`) 的映射关系到 `rl_org_group` 表。
4. **上传素材**：使用已认证的组合 ID 上传图片/视频，系统验证组合归属关系 (`rl_upload`)。
5. **状态同步**：轮询检查素材处理状态 (`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)
## 1. 获取真人认证链接 (H5)
**Endpoint**: `/reallife_asset/api/rl_verify.dspy`
检查审批状态通过后，调用供应商接口创建认证会话。
检查供应商配置通过后，调用供应商接口创建认证会话。
### 请求参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `downapp_id` | 是 | 下游应用唯一标识 |
| `downapp_id` | 是 | 下游应用唯一标识 (用于追踪记录) |
| `project_name` | 否 | 项目名称，默认 `default` |
### 请求示例
@ -93,19 +50,19 @@ Content-Type: application/json
"byted_token": "..."
}
```
**失败**（未开通）：
**失败**（未配置）：
```json
{
"success": false,
"message": "申请状态: pending，未通过审批"
"message": "供应商配置不存在"
}
```
**注意**：终端用户在 H5 页面完成认证后，供应商将回调 `rl_apply` 中设置的 `callback_url`。
**注意**：终端用户在 H5 页面完成认证后，系统将自动在 `rl_org_group` 表中登记该机构与组合 ID 的映射关系。
---
## 3. 上传素材
## 2. 上传素材
**Endpoint**: `/reallife_asset/api/rl_upload.dspy`
向已认证的素材组合上传图片或视频素材。
@ -148,7 +105,7 @@ Content-Type: application/json
---
## 4. 查询素材状态
## 3. 查询素材状态
**Endpoint**: `/reallife_asset/api/rl_status.dspy`
查询素材的处理状态（Processing / Active / Failed）。
@ -186,7 +143,7 @@ Content-Type: application/json
| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `未申请或供应商不支持` | `downapp_id` 不存在 | 确认是否已调用申请接口 |
| `申请状态: xxx，未通过审批` | 状态非 `active` | 联系营运人员审核 |
| `素材组合不存在` | `group_id` 无效 | 确认是否已通过认证获取有效 ID |
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` |
| `无效的素材组合ID或无权访问` | `group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 |
| `参数缺失` | 缺少必填参数 | 检查请求 Body |