docs: add virtual human asset API documentation
- Add 5 virtual human API endpoints (rl_virtual_create_group, rl_virtual_groups, rl_virtual_upload, rl_virtual_status, rl_virtual_assets) - Include complete request/response examples with curl test cases - Add virtual human error documentation - Restore real person asset error documentation
This commit is contained in:
parent
8b05c8628f
commit
4dc0603d5f
@ -1225,3 +1225,238 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_assets.dspy'
|
||||
| `无效的素材组合ID或无权访问` | ID 不属于当前机构 | 检查认证和 ID |
|
||||
| `素材不存在或无权访问` | ID 无效 | 检查 ID |
|
||||
| `尚未完成认证或认证失败` | 认证未完成 | 等待 H5 认证完成 |
|
||||
|
||||
---
|
||||
|
||||
## 虚拟人素材 API
|
||||
|
||||
私域虚拟人素材管理 API，用于创建虚拟人素材组合、上传素材、查询状态等。与真人素材 API 使用相同的认证方式，但素材存储在私域空间，仅当前机构可访问。
|
||||
|
||||
**Base URL**: `https://token.opencomputing.cn`
|
||||
|
||||
**认证**: Bearer Token（与大模型 API 相同）
|
||||
|
||||
### 业务流程
|
||||
|
||||
1. **创建素材组合**：为虚拟人创建一个素材组合
|
||||
2. **查询素材组合**：查看当前机构下所有虚拟人素材组合
|
||||
3. **上传素材**：向素材组合上传图片/视频/音频素材
|
||||
4. **状态同步**：轮询检查素材处理状态
|
||||
5. **查询素材列表**：查看组合下所有素材
|
||||
|
||||
---
|
||||
|
||||
## POST /reallife_asset/api/rl_virtual_create_group.dspy
|
||||
|
||||
创建私域虚拟人素材组合。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `vendor` | 是 | 供应商标识 |
|
||||
| `name` | 是 | 组合名称 |
|
||||
| `description` | 否 | 组合描述 |
|
||||
| `project_name` | 否 | 项目名称，默认 `default` |
|
||||
|
||||
> `user_id` 和 `org_id` 由 Bearer Token 自动获取
|
||||
|
||||
### 请求示例
|
||||
|
||||
```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": "测试组合"
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"id": "local_group_id_xxx",
|
||||
"vendor_group_id": "volc-virtual-group-xxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /reallife_asset/api/rl_virtual_groups.dspy
|
||||
|
||||
查询当前机构的私域虚拟人素材组合列表。
|
||||
|
||||
### 请求参数
|
||||
|
||||
无需参数，系统自动从 Bearer Token 获取 `org_id`。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_groups.dspy' \
|
||||
-H 'Authorization: Bearer ***
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"groups": [
|
||||
{
|
||||
"vendor_group_id": "volc-virtual-group-xxx",
|
||||
"vendor": "volcengine",
|
||||
"name": "虚拟角色A",
|
||||
"status": "active",
|
||||
"create_time": "2026-06-01 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /reallife_asset/api/rl_virtual_upload.dspy
|
||||
|
||||
上传虚拟人素材到私域素材组合。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `vendor_group_id` | 是 | 已创建的虚拟人素材组合 ID |
|
||||
| `source_url` | 是 | 素材 URL 或 `data:` base64 编码 |
|
||||
| `asset_type` | 否 | `Image`（默认）、`Video`、`Audio` |
|
||||
| `name` | 否 | 素材名称 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```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-virtual-group-xxx",
|
||||
"source_url": "https://bucket.oss.com/virtual_avatar.jpg",
|
||||
"asset_type": "Image",
|
||||
"name": "虚拟人正面"
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"id": "asset_record_id_xxx",
|
||||
"vendor_asset_id": "virtual-asset-2026...",
|
||||
"status": "Processing"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 上传是异步操作，需调用 `rl_virtual_status` 轮询状态。
|
||||
|
||||
---
|
||||
|
||||
## POST /reallife_asset/api/rl_virtual_status.dspy
|
||||
|
||||
查询虚拟人素材处理状态。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `asset_id` | 是 | 上传时返回的记录 ID |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```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_record_id_xxx"
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"status": "Active",
|
||||
"url": "https://... (临时下载链接，12小时有效)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 素材永久存储。`url` 过期后可再次调用获取新链接。
|
||||
|
||||
---
|
||||
|
||||
## POST /reallife_asset/api/rl_virtual_assets.dspy
|
||||
|
||||
查询指定虚拟人素材组合下的素材列表。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `vendor_group_id` | 是 | 虚拟人素材组合 ID |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```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-virtual-group-xxx"
|
||||
}'
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"assets": [
|
||||
{
|
||||
"id": "asset_record_id_xxx",
|
||||
"vendor_asset_id": "virtual-asset-2026...",
|
||||
"name": "虚拟人正面",
|
||||
"asset_type": "Image",
|
||||
"status": "Active",
|
||||
"url": "https://...",
|
||||
"create_time": "2026-06-01 10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 虚拟人素材错误说明
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|----------|------|----------|
|
||||
| `vendor和name为必填参数` | 创建组合时缺少必填字段 | 提供 vendor 和 name |
|
||||
| `vendor_group_id和source_url为必填参数` | 上传素材时缺少必填字段 | 提供组合 ID 和素材 URL |
|
||||
| `asset_id为必填参数` | 查询状态时缺少 asset_id | 提供素材记录 ID |
|
||||
| `创建失败` | 组合创建失败 | 检查参数和供应商配置 |
|
||||
| `上传失败` | 素材上传失败 | 检查 URL 是否可访问 |
|
||||
| `查询失败` | 查询操作失败 | 检查 ID 是否属于当前机构 |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user