From 5e4f7f9a98fc62e6be689c322cdc33cf38ea017d Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Tue, 2 Jun 2026 16:33:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E8=99=9A=E6=8B=9F?=
 =?UTF-8?q?=E4=BA=BAAPI=E6=96=87=E6=A1=A3=20-=20=E8=A1=A5=E5=85=85sections?=
 =?UTF-8?q?=206/8/9=E7=9A=84curl=E7=A4=BA=E4=BE=8B=E5=92=8C=E8=AF=B7?=
 =?UTF-8?q?=E6=B1=82=E7=A4=BA=E4=BE=8B=20-=20=E6=96=B0=E5=A2=9Esection=201?=
 =?UTF-8?q?0/11:=20=E5=90=8C=E6=AD=A5=E8=99=9A=E6=8B=9F=E4=BA=BA=E7=B4=A0?=
 =?UTF-8?q?=E6=9D=90=E7=BB=84=E5=90=88=E5=92=8C=E7=B4=A0=E6=9D=90=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=20-=20=E6=9B=B4=E6=96=B0=E4=B8=9A=E5=8A=A1=E6=B5=81?=
 =?UTF-8?q?=E7=A8=8B=E8=AF=B4=E6=98=8E=E5=A2=9E=E5=8A=A0=E5=90=8C=E6=AD=A5?=
 =?UTF-8?q?=E6=AD=A5=E9=AA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api_downapp.md | 149 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 147 insertions(+), 2 deletions(-)

diff --git a/docs/api_downapp.md b/docs/api_downapp.md
index 3dadfa0..6134264 100644
--- a/docs/api_downapp.md
+++ b/docs/api_downapp.md
@@ -313,6 +313,7 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_assets.dspy'
 3. **上传素材**：调用 `rl_virtual_upload.dspy` 上传虚拟人素材到指定组合。
 4. **查询素材列表**：调用 `rl_virtual_assets.dspy` 获取组合下的素材。
 5. **状态同步**：调用 `rl_virtual_status.dspy` 查询素材处理状态。
+6. **从供应商同步**：调用 `sync_from_vendor.dspy` 同步组合、`sync_assets.dspy` 同步素材（当供应商端有新增数据但本地未记录时使用）。
 
 ---
 
@@ -366,6 +367,9 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_creat
 
 自动从 Bearer Token 获取 `org_id`，返回当前机构下所有虚拟人素材组合。
 
+### 请求参数
+无需参数，系统自动从 Bearer Token 获取 `org_id`。
+
 ### 请求示例
 ```http
 POST /reallife_asset/api/rl_virtual_groups.dspy
@@ -390,6 +394,12 @@ Authorization: Bearer ***
 }
 ```
 
+### curl 示例
+```bash
+curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_groups.dspy' \
+  -H 'Authorization: Bearer ***
+```
+
 ---
 
 ## 7. 上传虚拟人素材
@@ -447,6 +457,19 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_uploa
 |------|------|------|
 | `vendor_group_id` | 是 | 素材组合 ID |
 
+> `org_id` 由 Bearer Token 自动获取，无需传递。
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_virtual_assets.dspy
+Authorization: Bearer ***
+Content-Type: application/json
+
+{
+  "vendor_group_id": "volc-group-xxx"
+}
+```
+
 ### 返回示例
 ```json
 {
@@ -468,15 +491,38 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_uploa
 }
 ```
 
+### curl 示例
+```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-group-xxx"}'
+```
+
 ---
 
 ## 9. 查询虚拟人素材处理状态
 **Endpoint**: `/reallife_asset/api/rl_virtual_status.dspy`
 
+查询虚拟人素材的处理状态（Processing / Active / Failed）。
+
 ### 请求参数
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `asset_id` | 是 | 素材 ID |
+| `asset_id` | 是 | 上传素材时返回的本地记录 ID |
+
+> `org_id` 由 Bearer Token 自动获取，无需传递。
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_virtual_status.dspy
+Authorization: Bearer ***
+Content-Type: application/json
+
+{
+  "asset_id": "asset-local-xxx"
+}
+```
 
 ### 返回示例
 ```json
@@ -489,10 +535,109 @@ curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_virtual_uploa
 }
 ```
 
+> **说明**：虚拟人素材的处理状态与真人素材相同（Processing / Active / Failed）。`url` 为临时签名下载链接，过期后可再次调用本接口获取新链接。
+
+### curl 示例
+```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-local-xxx"}'
+```
+
+---
+
+## 10. 同步虚拟人素材组合
+**Endpoint**: `/reallife_asset/api/sync_from_vendor.dspy`
+
+从供应商同步素材组合到本地数据库。当供应商端有新增组合但本地未记录时使用。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `vendor` | 是 | 供应商标识，如 `volcengine` |
+| `project_name` | 否 | 项目名称，默认 `default` |
+
+> `org_id` 由 Bearer Token 自动获取，无需传递。
+
+### 请求示例
+```http
+POST /reallife_asset/api/sync_from_vendor.dspy
+Authorization: Bearer ***
+Content-Type: application/json
+
+{
+  "vendor": "volcengine",
+  "project_name": "default"
+}
+```
+
+### 返回示例
+```json
+{
+  "widgettype": "Message",
+  "options": {
+    "message": "同步完成，共 3 条记录",
+    "type": "success"
+  }
+}
+```
+
+### curl 示例
+```bash
+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 自动获取，无需传递。
+
+### 请求示例
+```http
+POST /reallife_asset/api/sync_assets.dspy
+Authorization: Bearer ***
+Content-Type: application/json
+
+{
+  "group_id": "local-group-id-xxx"
+}
+```
+
+### 返回示例
+```json
+{
+  "widgettype": "Message",
+  "options": {
+    "message": "素材同步完成，共 5 条记录",
+    "type": "success"
+  }
+}
+```
+
+### curl 示例
+```bash
+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` |