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

16 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上传文件

业务流程

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

请求示例

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

业务流程

  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

请求示例

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

请求参数

无需参数，系统自动从 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"
      }
    ]
  }
}

curl 示例

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

请求示例

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

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

请求示例

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

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

返回示例

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

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

请求示例

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

{
  "asset_id": "asset-local-xxx"
}

返回示例

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

说明：虚拟人素材的处理状态与真人素材相同（Processing / Active / Failed）。url 为临时签名下载链接，过期后可再次调用本接口获取新链接。

curl 示例

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

请求示例

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

{
  "vendor": "volcengine",
  "project_name": "default"
}

返回示例

{
  "widgettype": "Message",
  "options": {
    "message": "同步完成，共 3 条记录",
    "type": "success"
  }
}

curl 示例

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

请求示例

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

{
  "group_id": "local-group-id-xxx"
}

返回示例

{
  "widgettype": "Message",
  "options": {
    "message": "素材同步完成，共 5 条记录",
    "type": "success"
  }
}

curl 示例

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 检查供应商配置和网络