reallife_asset/docs/api_downapp.md

# reallife_asset API 接口文档

## 概述
本文档说明下游应用如何调用 `reallife_asset` 模块接口，完成真人人像素材的认证、上传及状态查询。

**核心机制**：
- 所有接口均通过 **Bearer Token** 认证，dapi 模块自动识别调用方身份，获取 `user_id` 和 `org_id`。
- **调用方无需传递 `downapp_id`**，系统自动从认证上下文中获取用户和机构信息。
- 供应商密钥（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`

检查供应商配置通过后，调用供应商接口创建认证会话。

### 请求参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `project_name` | 否 | 项目名称，默认 `default` |

> `user_id` 和 `org_id` 由 Bearer Token 自动获取，无需传递。

### 请求示例
```http
POST /reallife_asset/api/rl_verify.dspy
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "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`

向已认证的素材组合上传图片或视频素材。

### 请求参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `vendor_group_id` | 是 | 认证成功后获得的供应商组合 ID（通过 `rl_query_groups` 查询） |
| `source_url` | 是 | 素材的公网可访问 URL |
| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
| `name` | 否 | 素材名称 |

> `org_id` 由 Bearer Token 自动获取，无需传递。

### 请求示例
```http
POST /reallife_asset/api/rl_upload.dspy
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "vendor_group_id": "volc-asset-group-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）。

### 请求参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `asset_id` | 是 | 上传素材时返回的本地记录 ID |

> `org_id` 由 Bearer Token 自动获取，无需传递。

### 请求示例
```http
POST /reallife_asset/api/rl_status.dspy
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "asset_id": "asset_record_id_xxx"
}
```

### 返回示例
**成功**：
```json
{
  "success": true,
  "status": "Active",
  "url": "https://... (素材下载链接，12小时有效)"
}
```

---

## 4. 查询已认证的组合列表
**Endpoint**: `/reallife_asset/api/rl_query_groups.dspy`

查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 `group_id`。

### 请求参数
无需参数，系统自动从 Bearer Token 获取 `org_id`。

### 请求示例
```http
POST /reallife_asset/api/rl_query_groups.dspy
Authorization: Bearer <your_api_key>
```

### 返回示例
**成功**：
```json
{
  "success": true,
  "groups": [
    {
      "vendor_group_id": "volc-asset-group-xxx",
      "vendor": "volcengine",
      "status": "active",
      "create_time": "2026-05-28 15:30:00"
    }
  ]
}
```

---

## 5. 认证回调（供应商调用）
**Endpoint**: `/reallife_asset/api/rl_callback.dspy`

供应商 H5 认证完成后自动回调此接口，**调用方无需调用**。系统自动完成：
- 查询认证结果
- 登记 `rl_org_group` 映射关系
- 更新 `rl_asset_group` 状态为 `active`

### 回调说明
- 此接口为 **any** 权限（无需登录），供供应商 POST 回调使用
- 回调 URL 在创建认证会话时由系统自动配置
- 回调成功后，调用方可通过 `rl_query_groups` 查询到新的组合映射

---

## 错误代码说明

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` |
| `供应商服务已停用` | 供应商配置状态非 active | 联系管理员激活配置 |
| `无效的素材组合ID或无权访问` | `vendor_group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 |
| `未找到对应的认证会话` | `BytedToken` 无效 | 检查回调参数 |
| `尚未完成认证或认证失败` | 认证未完成 | 等待用户完成 H5 认证 |