150 lines
4.1 KiB
Markdown
150 lines
4.1 KiB
Markdown
# Downapp API 接口文档
|
||
|
||
## 概述
|
||
本文档说明下游应用（Downapp）如何调用 `reallife_asset` 模块接口，完成真人人像素材的申请、认证、上传及状态查询。
|
||
|
||
**核心机制**：
|
||
- 所有接口均通过 `downapp_id` 标识调用方。
|
||
- 模块内部会自动检查调用方是否已开通服务（状态为 `active`）。
|
||
- 密钥（AK/SK）由营运人员在后台维护，调用方无需在请求中传递。
|
||
|
||
## 业务流程
|
||
|
||
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. 获取真人认证链接 (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": "供应商配置不存在"
|
||
}
|
||
```
|
||
|
||
**注意**：终端用户在 H5 页面完成认证后，系统将自动在 `rl_org_group` 表中登记该机构与组合 ID 的映射关系。
|
||
|
||
---
|
||
|
||
## 2. 上传素材
|
||
**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 个接口轮询状态。
|
||
|
||
---
|
||
|
||
## 3. 查询素材状态
|
||
**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小时有效)"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误代码说明
|
||
|
||
| 错误信息 | 原因 | 解决方案 |
|
||
|----------|------|----------|
|
||
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` |
|
||
| `无效的素材组合ID或无权访问` | `group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
|
||
| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 |
|
||
| `参数缺失` | 缺少必填参数 | 检查请求 Body |
|