yumoqing 925f58b025 feat: 添加私域虚拟人素材功能

- init.py: 新增6个虚拟人函数(create/list/upload/sync等)，注册到ServerEnv
- api_mapping: 新增create_group→CreateAssetGroup映射
- 外部API: 5个rl_virtual_*.dspy端点(创建组合/列表/上传/素材列表/状态)
- 前端API: 4个submit/get dspy端点(UI表单提交和数据获取)
- UI页面: 3个页面(创建组合/上传素材/查看素材)
- index.ui: 左侧导航新增虚拟人素材分区(3个按钮)
- load_path.py: RBAC新增virtual页面和api/%路径
- docs: api_downapp.md新增虚拟人API文档(5个端点)

2026-06-02 15:25:14 +08:00

12 KiB

Raw Blame History

reallife_asset API 接口文档

概述

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

baseurl: https://token.opencomputing.cn

认证机制：

所有接口通过 Bearer Token 认证：客户端在请求头中携带 Authorization: Bearer <apikey>

素材上传：

source_url 支持两种格式：公网 URL 或 data: base64 编码, 或用formdata上传文件

业务流程

真人认证：调用方发起认证请求 (rl_verify)，获取 H5 链接供终端用户完成人脸识别。
查询已认证group_id:查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 group_id
上传素材：使用已认证的组合 ID 上传图片/视频，系统验证组合归属关系 (rl_upload)。
状态同步：轮询检查素材处理状态 (rl_status)。

1. 获取真人认证链接 (H5)

Endpoint: /reallife_asset/api/rl_verify.dspy

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

请求参数

参数	必填	说明
`vendor`	是	供应商标识
`project_name`	否	项目名称，默认 `default`
`name`	否	认证名称，方便识别的名称，查询组合列表时显示

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

请求示例

POST /reallife_asset/api/rl_verify.dspy
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "project_name": "default"
}

返回示例

成功：

{
  "status": "ok",
  "data": {
    "id": "local_group_id_xxx",
    "h5_link": "https://... (H5页面链接，120秒有效)",
    "byted_token": "..."
  }
}

失败（未配置）：

{
  "status": "error",
  "data": {"message": "供应商配置不存在"}
}

注意：终端用户在 H5 页面完成认证后，系统将自动在 rl_org_group 表中登记该机构与组合 ID 的映射关系。

curl 示例

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。

请求示例

POST /reallife_asset/api/rl_query_groups.dspy
Authorization: Bearer <your_api_key>

返回示例

成功：

{
  "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 示例

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）

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 直接上传）

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"
}

返回示例

成功：

{
  "status": "ok",
  "data": {
    "id": "asset_record_id_xxx",
    "vendor_asset_id": "asset-2026...",
    "status": "Processing"
  }
}

注意：上传是异步操作，初始状态为 Processing，需调用第 4 个接口轮询状态。

curl 示例

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 自动获取，无需传递。

请求示例

POST /reallife_asset/api/rl_status.dspy
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "asset_id": "asset_record_id_xxx"
}

返回示例

成功：

{
  "status": "ok",
  "data": {
    "status": "Active",
    "url": "https://... (临时下载链接，12小时有效)"
  }
}

说明：火山引擎的素材永久存储在其服务器上。url 是临时签名下载链接，过期后可通过再次调用 rl_status 获取新链接。素材的永久引用为上传时返回的 vendor_asset_id。

curl 示例

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 自动获取，无需传递。

请求示例

POST /reallife_asset/api/rl_assets.dspy
Authorization: Bearer ***
Content-Type: application/json

{
  "vendor_group_id": "volc-asset-group-xxx"
}

返回示例

成功：

{
  "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 示例

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）与真人认证素材使用独立的接口。虚拟人素材无需真人认证流程，直接创建素材组合后上传即可。

业务流程

创建素材组合：调用 rl_virtual_create_group.dspy 创建 AIGC 类型的素材组合。
查询素材组合：调用 rl_virtual_groups.dspy 获取当前机构下所有虚拟人素材组合。
上传素材：调用 rl_virtual_upload.dspy 上传虚拟人素材到指定组合。
查询素材列表：调用 rl_virtual_assets.dspy 获取组合下的素材。
状态同步：调用 rl_virtual_status.dspy 查询素材处理状态。

5. 创建虚拟人素材组合

Endpoint: /reallife_asset/api/rl_virtual_create_group.dspy

请求参数

参数	必填	说明
`vendor`	是	供应商标识，如 `volcengine`
`name`	是	素材组合名称
`description`	否	组合描述
`project_name`	否	项目名称，默认 `default`

请求示例

POST /reallife_asset/api/rl_virtual_create_group.dspy
Authorization: Bearer ***
Content-Type: application/json

{
  "vendor": "volcengine",
  "name": "虚拟角色A",
  "description": "用于Seedance 2.0视频生成"
}

返回示例

{
  "status": "ok",
  "data": {
    "id": "local-id-xxx",
    "vendor_group_id": "volc-group-xxx"
  }
}

curl 示例

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，返回当前机构下所有虚拟人素材组合。

请求示例

POST /reallife_asset/api/rl_virtual_groups.dspy
Authorization: Bearer ***

返回示例

{
  "status": "ok",
  "data": {
    "groups": [
      {
        "vendor_group_id": "volc-group-xxx",
        "vendor": "volcengine",
        "name": "虚拟角色A",
        "status": "active",
        "create_time": "2026-06-02 12:00:00"
      }
    ]
  }
}

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`	否	素材名称

请求示例

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": "虚拟人正面照"
}

返回示例

{
  "status": "ok",
  "data": {
    "id": "asset-local-xxx",
    "vendor_asset_id": "volc-asset-xxx",
    "status": "Processing"
  }
}

curl 示例

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

返回示例

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

9. 查询虚拟人素材处理状态

Endpoint: /reallife_asset/api/rl_virtual_status.dspy

请求参数

参数	必填	说明
`asset_id`	是	素材 ID

返回示例

{
  "status": "ok",
  "data": {
    "status": "Active",
    "url": "https://... (临时下载链接)"
  }
}

错误代码说明

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

12 KiB Raw Blame History Unescape Escape

reallife_asset API 接口文档

概述

业务流程

1. 获取真人认证链接 (H5)

请求参数

请求示例

返回示例

curl 示例

2. 查询已认证的组合列表

请求参数

请求示例

返回示例

curl 示例

3. 上传素材

请求参数

请求示例（公网 URL）

请求示例（base64 直接上传）

返回示例

curl 示例

4. 查询素材状态

请求参数

请求示例

返回示例

curl 示例

5. 查询组合下所有素材

请求参数

请求示例

返回示例

curl 示例

私域虚拟人素材 API

业务流程

5. 创建虚拟人素材组合

请求参数

请求示例

返回示例

curl 示例

6. 查询虚拟人素材组合列表

请求示例

返回示例

7. 上传虚拟人素材

请求参数

请求示例

返回示例

curl 示例

8. 查询虚拟人素材列表

请求参数

返回示例

9. 查询虚拟人素材处理状态

请求参数

返回示例

错误代码说明

12 KiB

Raw Blame History