dashboard_for_sage/wwwroot/api_doc.md

# 元境API 文档

---

# 大模型 API

Base url: `https://token.opencomputing.cn/llmage/v1`

所有 API 端点需要 Bearer Token 认证

---

## POST /v1/chat/completions

文本生成接口，兼容 OpenAI 格式。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"qwen3-max"` |
| `messages` 或 `prompt` | array / string | 对话消息数组或文本提示 |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `catelogid` | string | 目录类型ID，默认 `"t2t"`，也支持中文名（向后兼容） |
| `stream` | boolean | 是否启用流式输出 |
| `off_peak` | boolean | 是否使用非高峰时段 |
| `transno` | string | 交易流水号（不传则自动生成） |

### 请求示例

```json
{
    "model": "qwen3-max",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
    "stream": false
}
```

```bash
# 非流式
curl -X POST 'https://token.opencomputing.cn/llmage/v1/chat/completions' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-max",
    "messages": [{"role": "user", "content": "你好，请介绍你自己"}],
    "stream": false
  }'

# 流式
curl -X POST 'https://token.opencomputing.cn/llmage/v1/chat/completions' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-max",
    "messages": [{"role": "user", "content": "写一首关于春天的诗"}],
    "stream": true
  }'
```

### 响应格式

**非流式响应:**

```json
{
    "id": "luid_xxx",
    "object": "chat.completion",
    "model": "qwen3-max",
    "choices": [{
        "index": 0,
        "message": {"role": "assistant", "content": "Hi there!"},
        "finish_reason": "stop"
    }],
    "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
}
```

**流式响应 (SSE):**

```
data: {"choices": [{"delta": {"content": "Hi"}, "index": 0}]}
data: {"choices": [{"delta": {"content": " there!"}, "index": 0}]}
data: [DONE]
```

### 错误响应

| 状态码 | 说明 |
|--------|------|
| 400 | 缺少必填参数或模型不存在 |
| 403 | 未登录 |
| 429 | 账户余额不足 |

---

## POST /v1/video/generations

视频生成接口。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"keling-2.1"` |
| `catelogid` | string | 目录类型ID，如 `"t2v"` / `"i2v"` / `"r2v"` |
| `prompt` | string | 生成提示词 |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `image_url` | string | 图生视频时提供参考图 URL |
| `duration` | string | 视频时长，如 `"5s"` |
| `resolution` | string | 分辨率，如 `"1080p"` |
| `n` | integer | 生成数量 |
| `transno` | string | 交易流水号 |

### 请求示例

```json
{
    "model": "keling-2.1",
    "catelogid": "t2v",
    "prompt": "A beautiful sunset over the ocean",
    "duration": "5s",
    "resolution": "1080p"
}
```

### 响应格式

视频生成通常为异步任务，提交后返回任务信息：

```json
{
    "id": "luid_xxx",
    "object": "video.generation",
    "model": "keling-2.1",
    "status": "submitted",
    "taskid": "task_xxx",
    "created": 1716912000
}
```

通过 `/v1/tasks?taskid=xxx` 查询任务状态。

### curl 测试用例

```bash
# ---- Vidu T2V 文生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-pro",
    "catelogid": "t2v",
    "prompt": "一只猫在草地上奔跑",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

# ---- Vidu I2V 图生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-pro",
    "catelogid": "i2v",
    "prompt": "画面中的人物微笑挥手",
    "image_file": "https://example.com/first_frame.jpg",
    "duration": 5,
    "ratio": "16:9"
  }'

# ---- Vidu Ref2V 参考生视频（主体模式） ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-pro",
    "catelogid": "r2v",
    "prompt": "一个女孩在海边跳舞",
    "subjects": [
      {"images": ["https://example.com/character.jpg"]}
    ],
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

# ---- Seedance T2V 文生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "catelogid": "t2v",
    "prompt": "一杯咖啡冒着热气，阳光从窗外洒入",
    "resolution": "720p",
    "duration": 8,
    "ratio": "16:9"
  }'

# ---- Seedance TI2V 文图生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "catelogid": "i2v",
    "prompt": "画面中的汽车缓缓启动驶向远方",
    "image1_file": "https://example.com/car.jpg",
    "resolution": "720p",
    "duration": 8
  }'

# ---- Seedance R2V 多模态参考生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H "Authorization: Bearer *** \
  -F "model=doubao-seedance-2-0-260128" \
  -F "catelogid=r2v" \
  -F "prompt=第一优先级：人物主体形象严格参考@图1。第二优先级：学习机产品外观严格参考@图2。第三优先级：门店背景空间严格参考@图3。视频主角只有一人，为@图1中的女性人物。人物外貌、脸型、五官、发型、气质、服装必须与@图1保持一致。保持知性温婉、干净利落的女性形象。服装为浅蓝色短袖针织上衣、米白色半身长裙、白色浅口单鞋。人物始终位于画面中心，主体占画面面积60%以上，面部清晰锐利。人物手持学习机，外观严格参考@图2。必须保持白色边框机身、橙色支架、底部笔槽结构、屏幕正面朝向镜头。不允许替换成其他电子设备。不允许产品变形、悬空、缺角、穿模。背景场景严格参考@图3，保持作业帮门店的橙红色主背景墙、100标识、暖白灯光和真实展示空间氛围。背景只作为场景识别与空间陪衬，不允许喧宾夺主，不要求生成清晰可读文字，不允许复杂宣传文案抢镜。镜头为竖屏中近景，人物自然站立面对镜头，轻微微笑，稳定展示学习机。双手或单手自然托持学习机，动作轻柔克制。整体为写实高清商业宣传短视频风格，画面明亮，人物皮肤自然通透，产品结构准确。禁止字幕、文字叠加、花字、水印。禁止出现第二个主要人物。禁止人物换脸、换装、肢体错误。禁止学习机外观错误、产品漂浮、手穿模。" \
  -F "ratio=9:16" \
  -F "resolution=1080p" \
  -F "duration=5" \
  -F "image_files=asset://asset-20260617135652-dczbp" \
  -F "image_files=asset://asset-20260617135840-ljmv9" \
  -F "image_files=asset://asset-20260617135924-s69z8"

# ---- 通义万象 T2V 文生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan2.6-t2v",
    "catelogid": "t2v",
    "prompt": "一条金鱼在清澈的水中游动",
    "size": "1920*1080",
    "duration": "5"
  }'

# ---- 通义万象 I2V 图生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan2.6-i2v",
    "catelogid": "i2v",
    "prompt": "画面中的花朵慢慢绽放",
    "image_file": "https://example.com/flower.jpg",
    "size": "1920*1080"
  }'

# ---- 通义万象 Ref2V 角色参考生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan2.6-r2v",
    "catelogid": "r2v",
    "prompt": "角色在公园中散步",
    "video1_file": "https://example.com/character_video.mp4",
    "size": "1920*1080",
    "duration": "10"
  }'

# ---- 可灵 T2V 文生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-v2-1-master",
    "catelogid": "t2v",
    "prompt": "夕阳下的海滩，海浪拍打礁石"
  }'

# ---- 海螺 TI2V 图生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "hailuo",
    "catelogid": "i2v",
    "prompt": "画面中的孩子开心地跑向镜头",
    "image_file": "https://example.com/child.jpg",
    "resolution": "768P",
    "duration": 6
  }'

# ---- 快乐马 T2V 文生视频 ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/video/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "catelogid": "t2v",
    "prompt": "一匹骏马在草原上奔驰",
    "size": "1920*1080",
    "duration": "5"
  }'
```

### 各模型输入参数明细

> 以下为各平台/模型的具体输入参数。调用时通过 `model` + `catelogid` 自动路由到对应供应商。

---

#### Vidu 平台

##### T2V - 文生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | `viduq3-pro` | 模型名称 | `viduq3-turbo`, `viduq3-pro` |
| `prompt` | string | 是 | - | 提示词 | - |
| `off_peak` | string | 否 | `N` | 错峰执行 | `Y`, `N` |
| `duration` | integer | 否 | `10` | 视频长度（1-16秒） | 1-16 |
| `ratio` | string | 否 | `16:9` | 长宽比 | `16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
| `resolution` | string | 否 | `1080p` | 分辨率 | `540p`, `720p`, `1080p` |

##### I2V - 图生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | `viduq3-pro` | 模型名称 | `viduq3-pro`, `viduq3-turbo` |
| `prompt` | string | 是 | - | 提示词 | - |
| `image_file` | image | 是 | - | 首帧图片 | - |
| `off_peak` | string | 否 | `N` | 错峰执行 | `Y`, `N` |
| `duration` | integer | 否 | `10` | 视频长度（1-16秒） | 1-16 |
| `ratio` | string | 否 | `16:9` | 长宽比 | `16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
| `resolution` | string | 否 | `1080p` | 分辨率 | `540p`, `720p`, `1080p` |

##### 2I2V - 首尾帧生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model` | string | 否 | `viduq2` | 模型名称 |
| `payload` | string | 是 | `2i2v` | 固定值 |
| `off_peak` | boolean | 否 | `false` | 错峰模式 |
| `images` | array | 是 | - | 两张图片URL `[首帧, 尾帧]` |
| `duration` | integer | 否 | `10` | 视频时长 |
| `prompt` | string | 是 | - | 提示词 |
| `audio` | boolean | 否 | `true` | 音频直出 |
| `seed` | integer | 否 | `12345` | 随机种子 |
| `aspect_ratio` | string | 否 | `16:9` | 画面比例 |
| `resolution` | string | 否 | `1080p` | 分辨率 |

##### Ref2V - 参考生视频 v2（主体模式）

> 使用主体（图片/视频/文字）生成视频，支持 viduq3-turbo/q3/q2-pro/q2/q1/2.0

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `model` | string | 是 | 模型名称 |
| `subjects` | array | 是 | 主体列表（最多7个图片/文字主体，每个主体最多3张图） |
| `prompt` | string | 是 | 提示词 |
| `audio` | boolean | 否 | 音视频直出 |
| `audio_type` | string | 否 | 音频类型 |
| `duration` | integer | 否 | 视频时长 |
| `seed` | integer | 否 | 随机种子 |
| `aspect_ratio` | string | 否 | 画面比例 |
| `resolution` | string | 否 | 分辨率 |
| `movement_amplitude` | string | 否 | 运动幅度 |
| `off_peak` | boolean | 否 | 错峰模式 |
| `auto_subjects` | boolean | 否 | 智能主体 |

##### Ref2V - 参考生视频 v2（非主体模式）

> 直接上传图片参考生成视频，支持 viduq3-mix/q3-turbo/q3/q2-pro/q2/q1/2.0

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `model` | string | 是 | 模型名称 |
| `images` | array | 是 | 参考图片URL列表（1-7张） |
| `videos` | array | 否 | 参考视频URL列表（仅viduq2-pro） |
| `prompt` | string | 是 | 提示词 |
| `audio` | boolean | 否 | 音视频直出 |
| `bgm` | boolean | 否 | 背景音乐 |
| `duration` | integer | 否 | 视频时长 |
| `seed` | integer | 否 | 随机种子 |
| `aspect_ratio` | string | 否 | 画面比例 |
| `resolution` | string | 否 | 分辨率 |
| `off_peak` | boolean | 否 | 错峰模式 |

##### Ref2V - 参考生视频 v1

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | `viduq2-pro` | 模型名称 | `viduq2`, `viduq1`, `vidu2.0` |
| `prompt` | string | 是 | - | 提示词 | - |
| `off_peak` | string | 否 | `N` | 错峰执行 | `Y`, `N` |
| `duration` | integer | 否 | `10` | 视频长度 | - |
| `ratio` | string | 否 | `16:9` | 长宽比 | `16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
| `resolution` | string | 否 | `1080p` | 分辨率 | `540p`, `720p`, `1080p` |

---

#### Seedance 平台（火山方舟）— Seedance 2.0

> 上游 API: `POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks`
> SDK: `pip install 'volcengine-python-sdk[ark]'`
> 开通条件: 账户余额 >= 200元 或已购资源包
> 任务ID仅保存7天，视频URL 24小时有效

##### 模型列表

| 模型 | Model ID | 1080p | 有声视频 | 联网搜索 |
|------|----------|-------|----------|----------|
| Seedance 2.0 | `doubao-seedance-2-0-260128` | ✅ | ✅ | ✅ |
| Seedance 2.0 Fast | `doubao-seedance-2-0-fast-260128` | ❌ | ✅ | ✅ |

##### T2V - 文生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | `doubao-seedance-2-0-260128` | 模型名称 | `doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128` |
| `prompt` | string | 是 | - | 提示词(中文<=500字,英文<=1000词) | - |
| `resolution` | string | 否 | `720p` | 分辨率 | `480p`, `720p`, `1080p`(Fast不支持) |
| `duration` | integer | 否 | `5` | 视频长度[4,15]秒, 或-1自动选择 | 4-15, -1 |
| `ratio` | string | 否 | `adaptive` | 宽高比 | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive` |
| `generate_audio` | boolean | 否 | `true` | 是否生成同步音效(人声+音效+BGM) | `true`, `false` |
| `watermark` | boolean | 否 | `false` | 是否含AI生成水印 | `true`, `false` |
| `return_last_frame` | boolean | 否 | `false` | 返回尾帧图片(用于连续视频拼接) | `true`, `false` |
| `priority` | integer | 否 | `0` | 执行优先级(0-9,越大越优先) | 0-9 |
| `tools` | array | 否 | - | 联网搜索 `[{"type":"web_search"}]` | `web_search` |

##### TI2V - 首帧/首尾帧生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | `doubao-seedance-2-0-260128` | 模型名称 | 同上 |
| `prompt` | string | 是 | - | 提示词 | - |
| `image1_file` | image | 是 | - | 首帧图片(role=first_frame) | - |
| `image2_file` | image | 否 | - | 尾帧图片(role=last_frame) | - |
| `resolution` | string | 否 | `720p` | 分辨率 | `480p`, `720p`, `1080p` |
| `duration` | integer | 否 | `5` | 视频长度[4,15]秒 | 4-15, -1 |
| `ratio` | string | 否 | `adaptive` | 宽高比(adaptive时以首帧为准) | 同上 |

> 首尾帧图片宽高比不一致时，以首帧为准，尾帧自动裁剪适配。

##### Ref2V - 多模态参考生视频（Seedance 2.0 核心能力）

传入参考图片(1-9张) + 参考视频(1-3个) + 参考音频，基于素材+提示词生成视频。

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model` | string | 是 | `doubao-seedance-2-0-260128` | 模型名称 |
| `prompt` | string | 是 | - | 提示词，用"图片1""视频1""音频1"指代素材 |
| `image_files` | array | 否 | - | 参考图片URL列表(1-9张), role=reference_image |
| `video_files` | array | 否 | - | 参考视频URL列表(1-3个,总时长<=15s), role=reference_video |
| `audio_files` | array | 否 | - | 参考音频URL列表, role=reference_audio(须搭配图/视频) |
| `resolution` | string | 否 | `720p` | 分辨率 |
| `duration` | integer | 否 | `5` | 视频长度[4,15]秒 | 4-15, -1 |
| `ratio` | string | 否 | `adaptive` | 宽高比 |
| `generate_audio` | boolean | 否 | `true` | 是否生成同步音效 |

> **三种图片场景互斥不可混用**: 首帧(first_frame) / 首尾帧(first_frame+last_frame) / 参考图(reference_image)
> **音频不可单独传入**: 须至少包含1个参考视频或图片。
> **人脸限制**: 不支持直接上传含真人人脸的参考图/视频。可用模型生成的含人脸产物、预置虚拟人像(asset://ID)、或已授权真人素材。

##### 输入素材规格

| 类型 | 格式 | 限制 |
|------|------|------|
| 图片 | jpeg/png/webp/bmp/tiff/gif/heic/heif | 宽高比(0.4,2.5), 宽高300-6000px, <30MB |
| 视频 | mp4/mov (H.264/H.265+AAC/MP3) | 480p/720p/1080p, 时长2-15s, <50MB, FPS 24-60 |
| 音频 | mp3/wav/aac | 不可单独传入,须搭配图/视频 |

> 图片URL支持三种格式: 公网URL / Base64(`data:image/png;base64,...`) / 素材ID(`asset://ASSET_ID`)

##### 输出视频像素表 (Seedance 2.0)

| 分辨率 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 | 21:9 |
|--------|------|-----|-----|-----|------|------|
| 480p | 864×496 | 752×560 | 640×640 | 560×752 | 496×864 | 992×432 |
| 720p | 1280×720 | 1112×834 | 960×960 | 834×1112 | 720×1280 | 1470×630 |
| 1080p | 1920×1080 | 1664×1248 | 1440×1440 | 1248×1664 | 1080×1920 | 2206×946 |

##### Ref2V 提示词写法

用"图片1/2""视频1""音频1"指代素材，按时间轴描述场景：

```
全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。
第一人称视角果茶宣传广告；首帧为图片1，你的手摘下一颗带晨露的苹果，
轻脆的碰撞声；2-4秒：快速切镜，将苹果块投入雪克杯，加入冰块与茶底，
用力摇晃；4-6秒：成品特写，分层果茶倒入透明杯；
6-8秒：手持举杯，将图片2中的果茶举到镜头前，尾帧定格为图片2。
背景声音统一为女生音色。
```

> 对话内容用双引号包裹可优化音频生成效果。

---

#### 通义万象（DashScope）

##### T2V - 文生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model` | string | 是 | - | 模型名称（如 `wan2.6-t2v`） |
| `prompt` | string | 是 | - | 提示词 |
| `negative_prompt` | string | 否 | - | 反向提示词 |
| `audio_file` | audio | 否 | - | 配音文件 |
| `size` | string | 否 | `1920*1080` | 视频尺寸 |
| `duration` | string | 否 | `15` | 视频时长 |

**size 可选值：** `832*480`, `480*832`, `624*624`, `1280*720`, `720*1280`, `960*960`, `1088*832`, `832*1088`, `1920*1080`, `1080*1920`, `1440*1440`, `1632*1248`, `1248*1632`

**duration 可选值：** `5`, `10`, `15`

##### I2V - 图生视频

可用模型：`wan2.6-i2v`, `wan2.6-i2v-flash`

> 输入参数与 T2V 类似，额外需要首帧图片。

##### 2I2V - 首尾帧生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model` | string | 是 | - | 模型名称 |
| `prompt` | string | 是 | - | 提示词 |
| `negative_prompt` | string | 否 | - | 反向提示词 |
| `image1_file` | image | 是 | - | 首帧图片 |
| `image2_file` | image | 是 | - | 尾帧图片 |
| `resolution` | string | 否 | `1080P` | 分辨率 |
| `duration` | integer | - | `5` | 固定5秒 |

##### Ref2V - 角色参考生视频

> 参考输入视频中的角色形象和音色，搭配提示词生成保持角色一致性的视频。可以输入1-3个人物视频，每个视频一个角色。

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model` | string | 是 | - | 模型名称（如 `wan2.6-r2v`） |
| `prompt` | string | 是 | - | 提示词 |
| `video1_file` | video | 是 | - | 角色一视频 |
| `video2_file` | video | 否 | - | 角色二视频 |
| `video3_file` | video | 否 | - | 角色三视频 |
| `size` | string | 否 | `1920*1080` | 视频尺寸 |
| `duration` | string | 否 | `10` | 视频时长 |

**size 可选值：** 同 T2V

**duration 可选值：** `10`, `15`

##### IA2V - 图像音频生视频

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `image_file` | image | 是 | 图像 |
| `audio_file` | audio | 是 | 音频 |

---

#### 可灵（Kling）

##### T2V - 文生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | - | 模型名称 | `kling-v2-1-master`, `kling-v2-master`, `kling-v1-6`, `kling-v1` |
| `prompt` | string | 是 | - | 提示词 | - |
| `negative_prompt` | string | 否 | - | 反向提示词 | - |

---

#### 海螺（Hailuo/MiniMax）

##### TI2V - 图生视频

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `prompt` | string | 是 | - | 提示词 | - |
| `image_file` | image | 否 | - | 首帧图片 | - |
| `image_file1` | image | 否 | - | 尾帧图片 | - |
| `resolution` | string | 否 | `768P` | 尺寸 | `768P`, `1080P` |
| `duration` | integer | 否 | `6` | 视频长度 | `6`（6秒）, `10`（10秒） |

---

#### 快乐马（HappyHorse）

> 基于通义万象平台（tongyi-wan），输入参数与通义万象对应类型一致。

##### T2V - 文生视频

输入参数同通义万象 T2V。可用模型：`happyhorse-1.0-t2v`

##### I2V - 图生视频

输入参数同通义万象 I2V。可用模型：`happyhorse-1.0-i2v`

> **注意：** 图片参数名为 `image_file`（非 `image_url`），传入图片 URL。

##### Ref2V - 参考生视频

输入参数同通义万象 Ref2V，额外支持：

| 参数名 | 说明 |
|--------|------|
| `resolution` | 可选 `1080P`（默认）, `720P` |
| `ratio` | 可选 `16:9`（默认）, `9:16`, `3:4`, `4:3` |

可用模型：`happyhorse-1.0-r2v`（参考图像数量1-9张，支持多角色参考）

---

## POST /v1/image/generations

图像生成接口。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"qwen-image-2.0-pro"` |
| `catelogid` | string | 目录类型ID，文生图固定为 `"t2i"` |
| `prompt` | string | 生成提示词 |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `image_url` | string | 图生图时提供参考图 URL |
| `size` | string | 尺寸，如 `"1024*1024"` |
| `n` | integer | 生成数量 |
| `style` | string | 风格参数 |
| `quality` | string | 质量参数 |
| `transno` | string | 交易流水号 |

### 请求示例

```json
{
    "model": "qwen-image-2.0-pro",
    "catelogid": "t2i",
    "prompt": "A beautiful sunset over the ocean",
    "size": "1024*1024",
    "n": 1
}
```

### 响应格式

直接返回图像数据。

**成功响应：**

```json
{
    "status": "SUCCEEDED",
    "usage": {
        "image_count": 1,
        "input_tokens": 22,
        "output_tokens": 2,
        "size": "1024*1024",
        "total_tokens": 24
    },
    "image_count": 1,
    "image": ["https://token.opencomputing.cn/idfile?path=/tmp/...png"]
}
```

> `usage` 字段因模型不同可能返回不同内容：万象系列返回 `input_tokens`/`output_tokens`/`size`/`total_tokens`；千问系列返回 `height`/`width`/`image_count`。

**失败响应：**

参数缺失：

```json
{
    "status": "error",
    "data": {
        "message": "Missing required parameter: prompt"
    }
}
```

模型不存在或参数无效：

```json
{
    "error": {
        "message": "Parameters error.",
        "type": "invalidparameters",
        "param": null,
        "code": "invalidparameters"
    }
}
```

### curl 测试用例

```bash
# ---- 万象 wan2.7-image-pro（同步） ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/image/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan2.7-image-pro",
    "catelogid": "t2i",
    "prompt": "一只可爱的橘猫趴在窗台上晒太阳",
    "size": "1024*1024",
    "n": 1
  }'

# ---- 万象 wan2.7-image-plus（同步） ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/image/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan2.7-image-plus",
    "catelogid": "t2i",
    "prompt": "一幅水墨山水画",
    "size": "2048*2048",
    "n": 1
  }'

# ---- 千问图像 qwen-image-2.0-pro（同步，图生图） ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/image/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-image-2.0-pro",
    "catelogid": "t2i",
    "prompt": "将这张图片转换为油画风格",
    "image_file": "https://example.com/photo.jpg",
    "size": "2048*2048",
    "n": 1,
    "watermark": false,
    "prompt_extend": true
  }'

# ---- 千问图像 qwen-image-plus（同步） ----
curl -X POST 'https://token.opencomputing.cn/llmage/v1/image/generations' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen-image-plus",
    "catelogid": "t2i",
    "prompt": "赛博朋克风格的城市夜景",
    "size": "1024*1024",
    "n": 1
  }'
```

### 各模型输入参数明细

> 以下为各平台/模型的具体输入参数。调用时通过 `model` + `catelogid` 自动路由到对应供应商。

---

#### 万象图像（Wan-Image）

##### T2I - 文生图

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | - | 模型名称 | 见下方模型列表 |
| `catelogid` | string | 是 | `t2i` | 目录类型ID，文生图固定为 `t2i` | `t2i` |
| `prompt` | string | 是 | - | 提示词 | - |
| `size` | string | 否 | `1024*1024` | 图像尺寸 | `512*512`, `1024*1024`, `2048*2048` 等 |
| `n` | integer | 否 | `1` | 生成数量 | 1-4 |

**可用模型：**

| 模型名称 | 说明 | 价格 |
|----------|------|------|
| `wan2.7-image-pro` | 万象专业版，创意性、稳定性、写实质感全面升级 | 0.5元/张 |
| `wan2.7-image-plus` | 万象Plus版，高分辨率图像生成，性价比高 | 0.2元/张 |

---

#### 千问图像（Qwen-Image）

##### qwen-image-2.0 系列 - 文生图

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | - | 模型名称 | `qwen-image-2.0-pro`, `qwen-image-2.0-2026-03-03` |
| `catelogid` | string | 是 | `t2i` | 目录类型ID，文生图固定为 `t2i` | `t2i` |
| `prompt` | string | 是 | - | 提示词 | - |
| `image_file` | image | 否 | - | 参考图 URL（图生图） | - |
| `size` | string | 否 | `2048*2048` | 图像尺寸 | `512*512`, `1024*1024`, `2048*2048` 等 |
| `n` | integer | 否 | `1` | 生成数量 | 1-4 |
| `watermark` | boolean | 否 | `false` | 是否添加水印 | `true`, `false` |
| `prompt_extend` | boolean | 否 | `true` | 是否扩展提示词 | `true`, `false` |

**可用模型：**

| 模型名称 | 说明 | 价格 |
|----------|------|------|
| `qwen-image-2.0-pro` | 千问图像生成Pro系列，文字渲染、真实质感、语义遵循能力更强 | 0.5元/张 |
| `qwen-image-2.0-2026-03-03` | 千问图像生成2.0快照版（2026-03-03），兼顾效果与响应速度 | 0.5元/张 |

---

##### qwen-image-plus 系列 - 文生图

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|--------|------|------|--------|------|--------|
| `model` | string | 是 | - | 模型名称 | `qwen-image-plus`, `qwen-image-plus-2026-01-09` |
| `catelogid` | string | 是 | `t2i` | 目录类型ID，文生图固定为 `t2i` | `t2i` |
| `prompt` | string | 是 | - | 提示词 | - |
| `size` | string | 否 | `1024*1024` | 图像尺寸 | `512*512`, `1024*1024`, `2048*2048` 等 |
| `n` | integer | 否 | `1` | 生成数量 | 1-4 |

**可用模型：**

| 模型名称 | 说明 | 价格 |
|----------|------|------|
| `qwen-image-plus` | 千问图像Plus系列，擅长多样化艺术风格与文字渲染 | 0.2元/张 |
| `qwen-image-plus-2026-01-09` | 千问图像Plus快照版（2026-01-09），为qwen-image-max的蒸馏加速版 | 0.2元/张 |

---

## POST /v1/music/generations

音乐生成接口。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"music-2.6"`, `"music-2.5"` |
| `catelogid` | string | 目录类型ID，固定为 `"music_gen"` |
| `prompt` | string | 音乐风格描述（风格、情绪、场景），如 `"流行音乐, 开心, 适合阳光明媚的下午"` |
| `lyrics` | string | 歌词内容，使用 `\n` 分隔每行，可包含结构标签 |

### 歌词结构标签

歌词中可包含以下结构标签来优化生成的音乐结构：
- `[Intro]` - 前奏
- `[Verse]` - 主歌
- `[Pre Chorus]` - 预副歌
- `[Chorus]` - 副歌
- `[Bridge]` - 桥段
- `[Outro]` - 尾声
- `[Interlude]` - 间奏
- `[Hook]` - 记忆点
- `[Build Up]` - 情绪铺垫
- `[Solo]` - 独奏

### 请求示例

```json
{
    "model": "music-2.6",
    "catelogid": "music_gen",
    "prompt": "Pop music, happy, suitable for a sunny day",
    "lyrics": "[Intro]\n\n[Verse]\nWalking down the street\nFeeling the beat\n\n[Chorus]\nDancing in the sun\nHaving so much fun"
}
```

```bash
curl -X POST 'https://token.opencomputing.cn/llmage/v1/music/generations' \
  -H 'Authorization: Bearer ***
  -H 'Content-Type: application/json' \
  -d '{
    "model": "music-2.6",
    "catelogid": "music_gen",
    "prompt": "流行音乐, 欢快, 适合阳光明媚的下午",
    "lyrics": "[Intro]\n\n[Verse]\n走在阳光下\n感受每一刻\n\n[Chorus]\n在阳光下跳舞\n享受美好时光"
  }'
```

### 响应格式

MiniMax 音乐生成为同步接口，直接返回音频URL：

```json
{
    "id": "luid_xxx",
    "object": "music.generation",
    "model": "music-2.6",
    "status": "SUCCEEDED",
    "audio": "https://...",
    "created": 1716912000
}
```

### 可用模型

| 模型名称 | model 参数 | 说明 |
|---------|-----------|------|
| MiniMax Music 2.6 | `music-2.6` | 最新版本，音质最佳 |
| MiniMax Music 2.5 | `music-2.5` | 支持14种段落级结构标签，物理级高保真 |

### MiniMax Music 2.5 特性

Music 2.5 在「段落级强控制」与「物理级高保真」两大技术难题上实现突破：
- 开放全段落标签控制，精准支持14种结构变体
- 长度限制：歌词内容 [1, 3500] 个字符
- prompt 长度限制：[10, 300] 个字符

### 错误响应

| 状态码 | 说明 |
|--------|------|
| 400 | 缺少必填参数或模型不存在 |
| 403 | 未登录 |
| 429 | 账户余额不足 |

---

## POST /v1/audio/speech

文本转语音（TTS）接口。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"speech-2.6-turbo"`, `"speech-2.6-hd"` |
| `catelogid` | string | 目录类型ID，固定为 `"tts"` |
| `prompt` | string | 需要合成的文本内容，最长 10,000 字符 |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `speaker` | string | 说话人/音色ID，如 `"female-tianmei"` |
| `speed` | float | 语速，默认 `1.0` |
| `emotion` | string | 情感，如 `"happy"`, `"sad"` |
| `transno` | string | 交易流水号 |

### 请求示例

```json
{
    "model": "speech-2.6-turbo",
    "catelogid": "tts",
    "prompt": "你好，欢迎使用语音合成服务",
    "speaker": "female-tianmei",
    "speed": 1.0,
    "emotion": "happy"
}
```

```bash
curl -X POST 'https://token.opencomputing.cn/llmage/v1/audio/speech' \
  -H 'Authorization: Bearer ***
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.6-turbo",
    "catelogid": "tts",
    "prompt": "你好，欢迎使用语音合成服务",
    "speaker": "female-tianmei",
    "speed": 1.0,
    "emotion": "happy"
  }'
```

### 响应格式

MiniMax TTS 为流式接口，逐块返回音频数据（hex编码自动转base64）：

```json
{
    "status": "SUCCEEDED",
    "audio": "base64_encoded_audio_data"
}
```

### 可用模型

| 模型名称 | model 参数 | 说明 |
|---------|-----------|------|
| MiniMax Speech 2.6 Turbo | `speech-2.6-turbo` | 极速版，更快更优惠，适用于语音聊天和数字人 |
| MiniMax Speech 2.6 HD | `speech-2.6-hd` | 高清版，超低延时，更高自然度 |
| MiniMax Speech 2.5 HD | `speech-2.5-hd-preview` | Preview版本 |
| F5-TTS 本地 | `f5tts` | 本地部署，零样本声音克隆，多语言支持 |

### 错误响应

| 状态码 | 说明 |
|--------|------|
| 400 | 缺少必填参数或模型不存在 |
| 403 | 未登录 |
| 429 | 账户余额不足 |

---

## POST /v1/audio/transcriptions

语音识别（ASR）接口，将音频转为文本。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"qwen3-asr-flash"`, `"parakeet-tdt-0.6b-v2"` |
| `catelogid` | string | 目录类型ID，固定为 `"asr"` |
| `audio_file` | string | 音频文件URL |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `language` | string | 语言代码（部分模型支持） |
| `transno` | string | 交易流水号 |

### 请求示例

```json
{
    "model": "qwen3-asr-flash",
    "catelogid": "asr",
    "audio_file": "https://example.com/audio.wav"
}
```

```bash
curl -X POST 'https://token.opencomputing.cn/llmage/v1/audio/transcriptions' \
  -H 'Authorization: Bearer ***
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-asr-flash",
    "catelogid": "asr",
    "audio_file": "https://example.com/audio.wav"
  }'
```

### 响应格式

```json
{
    "text": "识别出的文本内容",
    "usage": {
        "duration_seconds": 5.2
    }
}
```

### 可用模型

| 模型名称 | model 参数 | 说明 |
|---------|-----------|------|
| 通义千问 ASR | `qwen3-asr-flash` | 多语种识别、歌唱识别、情感识别、噪声拒识，0.00026元/秒 |
| Nvidia ASR | `parakeet-tdt-0.6b-v2` | 仅支持英文，6亿参数，支持标点/大小写/时间戳 |

### 通义千问 ASR 核心功能

- 多语种识别：涵盖普通话及多种方言（粤语、四川话等）
- 复杂环境适应：自动语种检测与智能非人声过滤
- 歌唱识别：伴随BGM下也能实现整首歌曲转写
- 上下文增强：通过配置上下文提高识别准确率
- 情感识别：支持惊讶、平静、愉快、悲伤、厌恶、愤怒、恐惧

### 错误响应

| 状态码 | 说明 |
|--------|------|
| 400 | 缺少必填参数或模型不存在 |
| 403 | 未登录 |
| 429 | 账户余额不足 |

---

## GET /v1/tasks

查询异步任务状态（仅用于视频生成等异步任务）。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `taskid` | string | 任务 ID |

### 请求示例

```
GET /llmage/v1/tasks?taskid=task_xxx
```

### 响应格式

```json
{
    "status": "ok",
    "data": {
        "status": "SUCCEEDED",
        "output": [...]
    }
}
```

任务状态值: `UNKNOWN` / `SUCCEEDED` / `FAILED`

```bash
curl 'https://token.opencomputing.cn/llmage/v1/tasks?taskid=task_xxx' \
  -H 'Authorization: Bearer ***'
```

---

## GET /v1/models

列出可用模型列表。

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `catelogid` | string | 按目录类型过滤 |
| `orderby` | string | 排序字段 |

### 请求示例

```
GET /llmage/v1/models
```

### 响应格式

```json
{
    "object": "list",
    "data": [
        {
            "id": "qwen3-max",
            "object": "model",
            "created": 1748044800,
            "owned_by": "opencomputing.ai"
        }
    ]
}
```

```bash
# 获取全部模型
curl 'https://token.opencomputing.cn/llmage/v1/models' \
  -H 'Authorization: Bearer ***'

# 按目录过滤（如只获取文生视频模型）
curl 'https://token.opencomputing.cn/llmage/v1/models?catelogid=t2v' \
  -H 'Authorization: Bearer ***'
```

---

## GET /v1/models/catelog

按分类目录获取可用模型列表，可排除指定模型。仅返回已上架（published）状态的模型。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `catelogid` | string | 目录类型ID，如 `"t2t"`, `"t2v"`, `"t2i"` 等 |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `exclude_id` | string | 排除指定模型ID（常用于"相关推荐"场景） |

### 请求示例

```
GET /llmage/v1/models/catelog?catelogid=t2t
GET /llmage/v1/models/catelog?catelogid=t2v&exclude_id=abc123
```

### 响应格式

```json
{
    "total": 5,
    "rows": [
        {
            "id": "xxx",
            "name": "qwen3-max",
            "model": "qwen3-max",
            "description": "{...}",
            "providerid": "...",
            "upappid": "...",
            "status": "published",
            ...
        }
    ]
}
```

> 与 `/v1/models` 的区别：此接口返回模型的完整信息（含供应商、上位应用等），`/v1/models` 返回 OpenAI 兼容的精简格式。

### 错误响应

| 状态码 | 说明 |
|--------|------|
| 400 | 缺少 catelogid 参数 |

```bash
# 获取文生文模型列表
curl 'https://token.opencomputing.cn/llmage/v1/models/catelog?catelogid=t2t' \
  -H 'Authorization: Bearer ***'

# 获取文生视频模型列表（排除某模型）
curl 'https://token.opencomputing.cn/llmage/v1/models/catelog?catelogid=t2v&exclude_id=abc123' \
  -H 'Authorization: Bearer ***'

# 获取文生图模型列表
curl 'https://token.opencomputing.cn/llmage/v1/models/catelog?catelogid=t2i' \
  -H 'Authorization: Bearer ***'
```

---

## GET /v1/pricing

获取模型定价展示信息，根据模型名称查询其关联的定价程序并返回可读的定价文本。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称，如 `"qwen3.7-max"` |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `catelogid` | string | 目录类型ID，默认 `"t2t"` |

### 请求示例

```
GET /llmage/v1/pricing?model=qwen3.7-max
```

```bash
curl 'https://token.opencomputing.cn/llmage/v1/pricing?model=qwen3.7-max' \
  -H 'Authorization: Bearer ***
```

### 响应格式

```json
{
    "status": "ok",
    "data": {
        "ppid": "pp_xxx",
        "name": "qwen3.7-max",
        "pricing_type": "per_use",
        "display_text": "【通义千问 qwen3.7-max】定价:\n  - 输入Token: 12 元/百万 [模型=qwen3.7-max]\n  - 输出Token: 48 元/百万 [模型=qwen3.7-max]",
        "items": [
            {
                "factor": "输入Token",
                "price": 12,
                "unit": "百万",
                "filters": "模型=qwen3.7-max"
            }
        ]
    }
}
```

### 错误响应

```json
{"status": "error", "message": "model parameter required"}
```

```json
{"status": "error", "message": "model 'xxx' not found or has no pricing"}
```

---

## 通用说明

### catelogid 目录类型ID对照表

| ID | 中文名 | 说明 |
|----|--------|------|
| `t2t` | 文生文 | 文本生成（默认） |
| `t2i` | 文生图 | 图像生成 |
| `t2v` | 文生视频 | 文本生成视频 |
| `i2v` | 图生视频 | 图像生成视频 |
| `r2v` | 参考生视频 | 参考图像生成视频 |
| `tts` | 语音合成 | 文本转语音 |
| `asr` | 语音识别 | 语音转文本 |
| `vision` | 图理解 | 图像理解 |
| `ai_search` | AI搜索 | AI搜索 |
| `digital_human` | 数字人 | 数字人 |
| `music_gen` | 音乐生成 | 音乐生成 |
| `text_cls` | 文本分类 | 文本分类 |
| `3d_gen` | 3D生成 | 3D模型生成 |
| `video_tool` | 视频工具 | 视频处理工具 |
| `translate` | 翻译 | 文本翻译 |

> 向后兼容：catelogid 参数同时支持新ID（如 `"t2v"`）和旧中文名（如 `"文生视频"`），推荐使用新ID。

### 参数统一

所有 v1 接口统一使用 `catelogid` 参数标识目录类型，替代原有的 `lctype` / `llmcatelogid`。

### 认证

所有接口需要 Bearer Token 认证，请求头中携带:

```
Authorization: Bearer ***
```

---

# 真人素材 API

真人素材 API 提供真人人像认证、素材上传和素材管理功能。使用与大模型 API 相同的 APIKEY 认证。

**Base URL**: `https://token.opencomputing.cn`

**认证**: Bearer Token（与大模型 API 相同）

## 业务流程

1. **真人认证**：发起认证请求，获取 H5 链接供终端用户完成人脸识别
2. **查询已认证组合**：查询当前机构下所有已认证的组合 ID
3. **上传素材**：使用已认证的组合 ID 上传图片/视频
4. **状态同步**：轮询检查素材处理状态

---

## POST /reallife_asset/api/rl_verify.dspy

获取真人认证链接（H5）。

### 请求参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `vendor` | 是 | 供应商标识 |
| `project_name` | 否 | 项目名称，默认 `default` |
| `name` | 否 | 认证名称，方便识别 |

> `user_id` 和 `org_id` 由 Bearer Token 自动获取

### 请求示例

```bash
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_verify.dspy' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "vendor": "volcengine",
    "project_name": "default",
    "name": "张三"
  }'
```

### 响应示例

```json
{
  "status": "ok",
  "data": {
    "id": "local_group_id_xxx",
    "h5_link": "https://... (H5页面链接，120秒有效)",
    "byted_token": "..."
  }
}
```

---

## POST /reallife_asset/api/rl_query_groups.dspy

查询已认证的组合列表。

### 请求参数

无需参数，系统自动从 Bearer Token 获取 `org_id`。

### 请求示例

```bash
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_query_groups.dspy' \
  -H 'Authorization: Bearer ***'
```

### 响应示例

```json
{
  "status": "ok",
  "data": {
    "groups": [
      {
        "vendor_group_id": "volc-asset-group-xxx",
        "vendor": "volcengine",
        "name": "模特张三",
        "status": "active",
        "create_time": "2026-05-28 15:30:00"
      }
    ]
  }
}
```

---

## POST /reallife_asset/api/rl_upload.dspy

上传素材到已认证的组合。

### 请求参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `vendor_group_id` | 是 | 已认证的组合 ID |
| `source_url` | 是 | 素材 URL 或 `data:` base64 编码 |
| `asset_type` | 否 | `Image`（默认）或 `Video` |
| `name` | 否 | 素材名称 |

### 请求示例

```bash
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_upload.dspy' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "vendor_group_id": "volc-asset-group-xxx",
    "source_url": "https://bucket.oss.com/photo.jpg",
    "asset_type": "Image",
    "name": "模特A"
  }'
```

### 响应示例

```json
{
  "status": "ok",
  "data": {
    "id": "asset_record_id_xxx",
    "vendor_asset_id": "asset-2026...",
    "status": "Processing"
  }
}
```

> 上传是异步操作，需调用 `rl_status` 轮询状态。

---

## POST /reallife_asset/api/rl_status.dspy

查询素材处理状态。

### 请求参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `asset_id` | 是 | 上传时返回的记录 ID |

### 请求示例

```bash
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_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_assets.dspy

查询组合下所有素材。

### 请求参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `vendor_group_id` | 是 | 已认证的组合 ID |

### 请求示例

```bash
curl -X POST 'https://token.opencomputing.cn/reallife_asset/api/rl_assets.dspy' \
  -H 'Authorization: Bearer *** \
  -H 'Content-Type: application/json' \
  -d '{
    "vendor_group_id": "volc-asset-group-xxx"
  }'
```

### 响应示例

```json
{
  "status": "ok",
  "data": {
    "assets": [
      {
        "id": "asset_record_id_xxx",
        "vendor_asset_id": "asset-2026...",
        "name": "模特A",
        "asset_type": "Image",
        "status": "Active",
        "url": "https://...",
        "create_time": "2026-05-28 15:30:00"
      }
    ],
    "total": 3
  }
}
```

---

## 真人素材错误说明

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `供应商配置不存在` | 未配置 AK/SK | 联系管理员 |
| `供应商服务已停用` | 配置非 active | 联系管理员激活 |
| `无效的素材组合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 是否属于当前机构 |