651 lines
16 KiB
Markdown
651 lines
16 KiB
Markdown
# reallife_asset API 接口文档
|
||
|
||
## 概述
|
||
本文档说明下游应用如何调用 `reallife_asset` 模块接口，完成真人人像素材的认证、上传及状态查询。
|
||
|
||
**baseurl**:
|
||
https://token.opencomputing.cn
|
||
|
||
**认证机制**：
|
||
- 所有接口通过 **Bearer Token** 认证：客户端在请求头中携带 `Authorization: Bearer <apikey>`
|
||
|
||
**素材上传**：
|
||
- `source_url` 支持两种格式：公网 URL 或 `data:` base64 编码, 或用formdata上传文件
|
||
|
||
## 业务流程
|
||
|
||
1. **真人认证**：调用方发起认证请求 (`rl_verify`)，获取 H5 链接供终端用户完成人脸识别。
|
||
2. **查询已认证group_id**:查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 group_id
|
||
3. **上传素材**：使用已认证的组合 ID 上传图片/视频，系统验证组合归属关系 (`rl_upload`)。
|
||
4. **状态同步**：轮询检查素材处理状态 (`rl_status`)。
|
||
|
||
---
|
||
|
||
## 1. 获取真人认证链接 (H5)
|
||
**Endpoint**: `/reallife_asset/api/rl_verify.dspy`
|
||
|
||
检查供应商配置通过后，调用供应商接口创建认证会话。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor` | 是 | 供应商标识 |
|
||
| `project_name` | 否 | 项目名称，默认 `default` |
|
||
| `name` | 否 | 认证名称，方便识别的名称，查询组合列表时显示 |
|
||
|
||
> `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
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"id": "local_group_id_xxx",
|
||
"h5_link": "https://... (H5页面链接，120秒有效)",
|
||
"byted_token": "..."
|
||
}
|
||
}
|
||
```
|
||
**失败**（未配置）：
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"data": {"message": "供应商配置不存在"}
|
||
}
|
||
```
|
||
|
||
**注意**：终端用户在 H5 页面完成认证后，系统将自动在 `rl_org_group` 表中登记该机构与组合 ID 的映射关系。
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_verify.dspy' \
|
||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"vendor": "volcengine",
|
||
"project_name": "default",
|
||
"name": "张三"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 查询已认证的组合列表
|
||
**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
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"groups": [
|
||
{
|
||
"vendor_group_id": "volc-asset-group-xxx",
|
||
"vendor": "volcengine",
|
||
"name": "模特张三",
|
||
"status": "active",
|
||
"create_time": "2026-05-28 15:30:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_query_groups.dspy' \
|
||
-H 'Authorization: Bearer YOUR_TOKEN'
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 上传素材
|
||
**Endpoint**: `/reallife_asset/api/rl_upload.dspy`
|
||
|
||
向已认证的素材组合上传图片或视频素材。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor_group_id` | 是 | 认证成功后获得的供应商组合 ID（通过 `rl_query_groups` 查询） |
|
||
| `source_url` | 是 | 素材的公网 URL **或** `data:` 格式的 base64 编码（系统自动转为公网地址） |
|
||
| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
|
||
| `name` | 否 | 素材名称 |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例（公网 URL）
|
||
```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"
|
||
}
|
||
```
|
||
|
||
### 请求示例（base64 直接上传）
|
||
```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": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
|
||
"asset_type": "Image",
|
||
"name": "模特B"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
**成功**：
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"id": "asset_record_id_xxx",
|
||
"vendor_asset_id": "asset-2026...",
|
||
"status": "Processing"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**：上传是异步操作，初始状态为 `Processing`，需调用第 4 个接口轮询状态。
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_upload.dspy' \
|
||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||
-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"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 查询素材状态
|
||
**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
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"status": "Active",
|
||
"url": "https://... (临时下载链接，12小时有效)"
|
||
}
|
||
}
|
||
```
|
||
|
||
> **说明**：火山引擎的素材**永久存储**在其服务器上。`url` 是临时签名下载链接，过期后可通过再次调用 `rl_status` 获取新链接。素材的永久引用为上传时返回的 `vendor_asset_id`。
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_status.dspy' \
|
||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"asset_id": "asset_record_id_xxx"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 查询组合下所有素材
|
||
**Endpoint**: `/reallife_asset/api/rl_assets.dspy`
|
||
|
||
查询指定 `vendor_group_id` 下的所有素材列表。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor_group_id` | 是 | 认证成功后获得的供应商组合 ID |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_assets.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_assets.dspy' \
|
||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"vendor_group_id": "volc-asset-group-xxx"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 私域虚拟人素材 API
|
||
|
||
> 虚拟人素材（AIGC）与真人认证素材使用独立的接口。虚拟人素材无需真人认证流程，直接创建素材组合后上传即可。
|
||
|
||
### 业务流程
|
||
|
||
1. **创建素材组合**：调用 `rl_virtual_create_group.dspy` 创建 AIGC 类型的素材组合。
|
||
2. **查询素材组合**：调用 `rl_virtual_groups.dspy` 获取当前机构下所有虚拟人素材组合。
|
||
3. **上传素材**：调用 `rl_virtual_upload.dspy` 上传虚拟人素材到指定组合。
|
||
4. **查询素材列表**：调用 `rl_virtual_assets.dspy` 获取组合下的素材。
|
||
5. **状态同步**：调用 `rl_virtual_status.dspy` 查询素材处理状态。
|
||
6. **从供应商同步**：调用 `sync_from_vendor.dspy` 同步组合、`sync_assets.dspy` 同步素材（当供应商端有新增数据但本地未记录时使用）。
|
||
|
||
---
|
||
|
||
## 5. 创建虚拟人素材组合
|
||
**Endpoint**: `/reallife_asset/api/rl_virtual_create_group.dspy`
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor` | 是 | 供应商标识，如 `volcengine` |
|
||
| `name` | 是 | 素材组合名称 |
|
||
| `description` | 否 | 组合描述 |
|
||
| `project_name` | 否 | 项目名称，默认 `default` |
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_virtual_create_group.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"vendor": "volcengine",
|
||
"name": "虚拟角色A",
|
||
"description": "用于Seedance 2.0视频生成"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"id": "local-id-xxx",
|
||
"vendor_group_id": "volc-group-xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_create_group.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"vendor":"volcengine","name":"虚拟角色A","description":"测试组合"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 查询虚拟人素材组合列表
|
||
**Endpoint**: `/reallife_asset/api/rl_virtual_groups.dspy`
|
||
|
||
自动从 Bearer Token 获取 `org_id`，返回当前机构下所有虚拟人素材组合。
|
||
|
||
### 请求参数
|
||
无需参数，系统自动从 Bearer Token 获取 `org_id`。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_virtual_groups.dspy
|
||
Authorization: Bearer ***
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"groups": [
|
||
{
|
||
"vendor_group_id": "volc-group-xxx",
|
||
"vendor": "volcengine",
|
||
"name": "虚拟角色A",
|
||
"status": "active",
|
||
"create_time": "2026-06-02 12:00:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_groups.dspy' \
|
||
-H 'Authorization: Bearer ***
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 上传虚拟人素材
|
||
**Endpoint**: `/reallife_asset/api/rl_virtual_upload.dspy`
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor_group_id` | 是 | 素材组合 ID |
|
||
| `source_url` | 是 | 素材 URL 或 base64 data URI |
|
||
| `asset_type` | 否 | Image/Video/Audio，自动检测 |
|
||
| `name` | 否 | 素材名称 |
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_virtual_upload.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"vendor_group_id": "volc-group-xxx",
|
||
"source_url": "https://example.com/avatar.jpg",
|
||
"asset_type": "Image",
|
||
"name": "虚拟人正面照"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"id": "asset-local-xxx",
|
||
"vendor_asset_id": "volc-asset-xxx",
|
||
"status": "Processing"
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_upload.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"vendor_group_id":"volc-group-xxx","source_url":"https://example.com/avatar.jpg","asset_type":"Image","name":"虚拟人正面照"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 查询虚拟人素材列表
|
||
**Endpoint**: `/reallife_asset/api/rl_virtual_assets.dspy`
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor_group_id` | 是 | 素材组合 ID |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_virtual_assets.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"vendor_group_id": "volc-group-xxx"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"assets": [
|
||
{
|
||
"id": "asset-local-xxx",
|
||
"vendor_asset_id": "volc-asset-xxx",
|
||
"name": "虚拟人正面照",
|
||
"asset_type": "Image",
|
||
"status": "Active",
|
||
"url": "https://... (临时下载链接)",
|
||
"create_time": "2026-06-02 12:30:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_assets.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"vendor_group_id":"volc-group-xxx"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 查询虚拟人素材处理状态
|
||
**Endpoint**: `/reallife_asset/api/rl_virtual_status.dspy`
|
||
|
||
查询虚拟人素材的处理状态（Processing / Active / Failed）。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `asset_id` | 是 | 上传素材时返回的本地记录 ID |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/rl_virtual_status.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"asset_id": "asset-local-xxx"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"status": "Active",
|
||
"url": "https://... (临时下载链接)"
|
||
}
|
||
}
|
||
```
|
||
|
||
> **说明**：虚拟人素材的处理状态与真人素材相同（Processing / Active / Failed）。`url` 为临时签名下载链接，过期后可再次调用本接口获取新链接。
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_status.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"asset_id":"asset-local-xxx"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 同步虚拟人素材组合
|
||
**Endpoint**: `/reallife_asset/api/sync_from_vendor.dspy`
|
||
|
||
从供应商同步素材组合到本地数据库。当供应商端有新增组合但本地未记录时使用。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor` | 是 | 供应商标识，如 `volcengine` |
|
||
| `project_name` | 否 | 项目名称，默认 `default` |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/sync_from_vendor.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"vendor": "volcengine",
|
||
"project_name": "default"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"widgettype": "Message",
|
||
"options": {
|
||
"message": "同步完成，共 3 条记录",
|
||
"type": "success"
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/sync_from_vendor.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"vendor":"volcengine","project_name":"default"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 同步虚拟人素材
|
||
**Endpoint**: `/reallife_asset/api/sync_assets.dspy`
|
||
|
||
从供应商同步指定素材组合下的素材到本地数据库。当供应商端有新增素材但本地未记录时使用。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `group_id` | 是 | 本地素材组合 ID（`rl_asset_group.id`，通过查询组合列表获取） |
|
||
|
||
> `org_id` 由 Bearer Token 自动获取，无需传递。
|
||
|
||
### 请求示例
|
||
```http
|
||
POST /reallife_asset/api/sync_assets.dspy
|
||
Authorization: Bearer ***
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"group_id": "local-group-id-xxx"
|
||
}
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"widgettype": "Message",
|
||
"options": {
|
||
"message": "素材同步完成，共 5 条记录",
|
||
"type": "success"
|
||
}
|
||
}
|
||
```
|
||
|
||
### curl 示例
|
||
```bash
|
||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/sync_assets.dspy' \
|
||
-H 'Authorization: Bearer *** \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"group_id":"local-group-id-xxx"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 错误代码说明
|
||
| 错误信息 | 原因 | 解决方案 |
|
||
|----------|------|----------|
|
||
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` |
|
||
| `供应商服务已停用` | 供应商配置状态非 active | 联系管理员激活配置 |
|
||
| `无效的素材组合ID或无权访问` | `vendor_group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
|
||
| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 |
|
||
| `未找到对应的认证会话` | `BytedToken` 无效 | 检查回调参数 |
|
||
| `尚未完成认证或认证失败` | 认证未完成 | 等待用户完成 H5 认证 |
|
||
| `vendor和name为必填参数` | 创建虚拟人组合缺少参数 | 补充 vendor 和 name |
|
||
| `创建素材组合失败，未返回组合ID` | 供应商 API 未返回有效 ID | 检查供应商配置和网络 |
|