reallife_asset/docs/api_downapp.md

reallife_asset API 接口文档

概述

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

认证机制：

• 所有接口通过 dapi Bearer Token 认证：客户端在请求头中携带 Authorization: Bearer <apikey>
• dapi 中间件自动识别调用方身份，设置 get_user()（用户ID）和 get_userorgid()（机构ID）
• 调用方无需传递身份参数，系统自动从认证上下文中获取

素材上传：

• source_url 支持两种格式：公网 URL 或 data: base64 编码
• base64 格式由系统通过 b64media2url 自动转为公网地址，无需客户自行托管文件

供应商密钥管理：

• 供应商密钥（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 自动获取，无需传递。

请求示例

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

{
  "project_name": "default"
}

返回示例

成功：

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

失败（未配置）：

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

返回示例

成功：

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

请求示例

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

{
  "asset_id": "asset_record_id_xxx"
}

返回示例

成功：

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

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

---

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

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>

返回示例

成功：

{
  "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 认证