reallife_asset/docs/api_downapp.md

Downapp API 接口文档

概述

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

核心机制：

• 所有接口均通过 downapp_id 标识调用方。
• 模块内部会自动检查调用方是否已开通服务（状态为 active）。
• 密钥（AK/SK）由营运人员在后台维护，调用方无需在请求中传递。

业务流程

1. 申请开通：调用方提交申请 (rl_apply)。
2. 人工审批：营运人员审核申请，回填火山引擎 AK/SK，并激活账户 (active)。
3. 真人认证：调用方发起认证请求，获取 H5 链接供终端用户完成人脸识别 (rl_verify)。
4. 上传素材：认证成功后，使用获取到的 Group ID 上传图片/视频 (rl_upload)。
5. 状态同步：轮询检查素材处理状态，直到变为 Active 可用 (rl_status)。

---

1. 申请开通服务

Endpoint: /reallife_asset/api/rl_apply.dspy

登记调用方信息，申请开通真人素材上传权限。

请求参数

参数	必填	说明
downapp_id	是	下游应用唯一标识
vendor	是	供应商名称，如 volcengine
callback_url	是	真人认证完成后的回调地址

请求示例

POST /reallife_asset/api/rl_apply.dspy
Content-Type: application/json

{
  "downapp_id": "app_123",
  "vendor": "volcengine",
  "callback_url": "https://example.com/callback"
}

返回示例

成功：

{
  "success": true,
  "app_id": "record_id_xxx",
  "status": "pending"
}

失败（已存在记录）：

{
  "success": false,
  "message": "已提交申请，请等待审批"
}

---

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

Endpoint: /reallife_asset/api/rl_verify.dspy

检查审批状态通过后，调用供应商接口创建认证会话。

请求参数

参数	必填	说明
downapp_id	是	下游应用唯一标识
project_name	否	项目名称，默认 default

请求示例

POST /reallife_asset/api/rl_verify.dspy
Content-Type: application/json

{
  "downapp_id": "app_123",
  "project_name": "default"
}

返回示例

成功：

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

失败（未开通）：

{
  "success": false,
  "message": "申请状态: pending，未通过审批"
}

注意：终端用户在 H5 页面完成认证后，供应商将回调 rl_apply 中设置的 callback_url。

---

3. 上传素材

Endpoint: /reallife_asset/api/rl_upload.dspy

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

请求参数

参数	必填	说明
downapp_id	是	下游应用唯一标识
group_id	是	真人认证成功后获取的本地组合 ID
source_url	是	素材的公网可访问 URL
asset_type	否	素材类型：Image (默认) 或 Video
name	否	素材名称

请求示例

POST /reallife_asset/api/rl_upload.dspy
Content-Type: application/json

{
  "downapp_id": "app_123",
  "group_id": "local_group_id_xxx",
  "source_url": "https://bucket.oss.com/photo.jpg",
  "asset_type": "Image",
  "name": "模特A"
}

返回示例

成功：

{
  "success": true,
  "id": "asset_record_id_xxx",
  "vendor_asset_id": "asset-2026...",
  "status": "Processing"
}

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

---

4. 查询素材状态

Endpoint: /reallife_asset/api/rl_status.dspy

查询素材的处理状态（Processing / Active / Failed）。

请求参数

参数	必填	说明
downapp_id	是	下游应用唯一标识
asset_id	是	上传素材时返回的本地记录 ID

请求示例

POST /reallife_asset/api/rl_status.dspy
Content-Type: application/json

{
  "downapp_id": "app_123",
  "asset_id": "asset_record_id_xxx"
}

返回示例

成功：

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

---

错误代码说明

错误信息	原因	解决方案
未申请或供应商不支持	downapp_id 不存在	确认是否已调用申请接口
申请状态: xxx，未通过审批	状态非 active	联系营运人员审核
素材组合不存在	group_id 无效	确认是否已通过认证获取有效 ID
参数缺失	缺少必填参数	检查请求 Body