From 86d2c4edc442f715383921f97468bed96c1e49cc Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Sat, 30 May 2026 12:24:35 +0800
Subject: [PATCH] docs: add curl examples to all external APIs

- rl_verify.dspy: vendor param for creating verify session
- rl_upload.dspy: upload asset to vendor_group
- rl_status.dspy: query asset processing status
- rl_assets.dspy: list assets by vendor_group_id
- sync_assets.dspy: sync assets from vendor
- check_validate.dspy: check verify result with apikey/secretkey
---
 wwwroot/api/check_validate.dspy | 10 ++++++++++
 wwwroot/api/rl_assets.dspy      |  7 +++++++
 wwwroot/api/rl_status.dspy      |  7 +++++++
 wwwroot/api/rl_upload.dspy      |  9 +++++++++
 wwwroot/api/rl_verify.dspy      |  8 ++++++++
 wwwroot/api/sync_assets.dspy    |  9 +++++++++
 6 files changed, 50 insertions(+)

diff --git a/wwwroot/api/check_validate.dspy b/wwwroot/api/check_validate.dspy
index 0e2a4c5..211c279 100644
--- a/wwwroot/api/check_validate.dspy
+++ b/wwwroot/api/check_validate.dspy
@@ -1,3 +1,13 @@
+# ============================================================
+# 检查真人认证结果（获取 vendor_group_id）
+# 参数: group_id(必填, 本地 rl_asset_group.id),
+#        apikey(必填), secretkey(必填)
+# 返回: {success, message, vendor_group_id}
+# curl 示例:
+# curl -X POST 'https://ai.atvoe.com/reallife_asset/api/check_validate.dspy' \
+#   -H 'Authorization: Bearer YOUR_TOKEN' \
+#   -d 'group_id=LOCAL_GROUP_ID&apikey=YOUR_AK&secretkey=YOUR_SK'
+# ============================================================
 group_id = params_kw.get('group_id', '')
 apikey = params_kw.get('apikey', '')
 secretkey = params_kw.get('secretkey', '')
diff --git a/wwwroot/api/rl_assets.dspy b/wwwroot/api/rl_assets.dspy
index 183f2ce..9d16f16 100644
--- a/wwwroot/api/rl_assets.dspy
+++ b/wwwroot/api/rl_assets.dspy
@@ -1,3 +1,10 @@
+# ============================================================
+# 查询指定 vendor_group_id 下所有素材
+# 参数: vendor_group_id(必填)
+# curl 示例:
+# curl 'https://ai.atvoe.com/reallife_asset/api/rl_assets.dspy?vendor_group_id=GROUP_ID' \
+#   -H 'Authorization: Bearer YOUR_TOKEN'
+# ============================================================
 
 vendor_group_id = params_kw.get('vendor_group_id', '')
 
diff --git a/wwwroot/api/rl_status.dspy b/wwwroot/api/rl_status.dspy
index d04629e..f3aca33 100644
--- a/wwwroot/api/rl_status.dspy
+++ b/wwwroot/api/rl_status.dspy
@@ -1,3 +1,10 @@
+# ============================================================
+# 查询素材处理状态（同步供应商最新状态）
+# 参数: asset_id(必填)
+# curl 示例:
+# curl 'https://ai.atvoe.com/reallife_asset/api/rl_status.dspy?asset_id=ASSET_ID' \
+#   -H 'Authorization: Bearer YOUR_TOKEN'
+# ============================================================
 
 asset_id = params_kw.get('asset_id', '')
 
diff --git a/wwwroot/api/rl_upload.dspy b/wwwroot/api/rl_upload.dspy
index d3d8d1d..ae038cb 100644
--- a/wwwroot/api/rl_upload.dspy
+++ b/wwwroot/api/rl_upload.dspy
@@ -1,3 +1,12 @@
+# ============================================================
+# 上传素材到指定认证组合
+# 参数: vendor_group_id(必填), source_url(必填, 素材URL),
+#        asset_type(选填, Image/Video/Audio, 自动检测), name(选填)
+# curl 示例:
+# curl -X POST 'https://ai.atvoe.com/reallife_asset/api/rl_upload.dspy' \
+#   -H 'Authorization: Bearer YOUR_TOKEN' \
+#   -d 'vendor_group_id=group-xxx&source_url=https://example.com/photo.jpg&asset_type=Image&name=测试素材'
+# ============================================================
 
 vendor_group_id = params_kw.get('vendor_group_id', '')
 source_url = params_kw.get('source_url', '')
diff --git a/wwwroot/api/rl_verify.dspy b/wwwroot/api/rl_verify.dspy
index 8a7bdb1..b89641e 100644
--- a/wwwroot/api/rl_verify.dspy
+++ b/wwwroot/api/rl_verify.dspy
@@ -1,3 +1,11 @@
+# ============================================================
+# 创建真人认证会话 — 获取 H5 认证链接
+# 参数: vendor(必填), name(选填), project_name(选填, 默认default)
+# curl 示例:
+# curl -X POST 'https://ai.atvoe.com/reallife_asset/api/rl_verify.dspy' \
+#   -H 'Authorization: Bearer YOUR_TOKEN' \
+#   -d 'vendor=volcengine&name=张三'
+# ============================================================
 
 vendor = params_kw.get('vendor', '')
 project_name = params_kw.get('project_name', 'default')
diff --git a/wwwroot/api/sync_assets.dspy b/wwwroot/api/sync_assets.dspy
index c0490ad..d6daddf 100644
--- a/wwwroot/api/sync_assets.dspy
+++ b/wwwroot/api/sync_assets.dspy
@@ -1,3 +1,12 @@
+# ============================================================
+# 从供应商同步素材到本地（按 group_id）
+# 参数: group_id(必填, 本地 rl_asset_group.id)
+# 返回: bricks Message widget (前端专用)
+# curl 示例:
+# curl -X POST 'https://ai.atvoe.com/reallife_asset/api/sync_assets.dspy' \
+#   -H 'Authorization: Bearer YOUR_TOKEN' \
+#   -d 'group_id=LOCAL_GROUP_ID'
+# ============================================================
 org_id = (await get_userorgid()) or '0'
 group_id = params_kw.get('group_id', '')