1463 lines
38 KiB
Markdown
1463 lines
38 KiB
Markdown
# 元境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
|
||
}'
|
||
|
||
# ---- 通义万象 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 平台（火山方舟）
|
||
|
||
##### T2V - 文生视频
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|
||
|--------|------|------|--------|------|--------|
|
||
| `model` | string | 是 | `doubao-seedance-2-0-260128` | 模型名称 | `doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128` |
|
||
| `prompt` | string | 是 | - | 提示词 | - |
|
||
| `resolution` | string | 否 | `720p` | 尺寸 | `480p`, `720p`, `1080p` |
|
||
| `duration` | integer | 否 | `8` | 视频长度 | - |
|
||
| `ratio` | string | 否 | `1:1` | 宽高比 | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `9:21` |
|
||
|
||
##### TI2V - 文图生视频
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|
||
|--------|------|------|--------|------|--------|
|
||
| `model` | string | 是 | `doubao-seedance-2-0-260128` | 模型名称 | `doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128` |
|
||
| `prompt` | string | 是 | - | 提示词 | - |
|
||
| `image1_file` | image | 是 | - | 首帧图片 | - |
|
||
| `image2_file` | image | 否 | - | 尾帧图片 | - |
|
||
| `resolution` | string | 否 | `720p` | 尺寸 | `480p`, `720p`, `1080p` |
|
||
| `duration` | integer | 否 | `8` | 视频长度 | - |
|
||
| `ratio` | string | 否 | `1:1` | 宽高比 | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9`, `9:21` |
|
||
|
||
##### Ref2V - 参考生视频
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| `model` | string | 是 | - | 模型名称 |
|
||
| `prompt` | string | 是 | - | 提示词 |
|
||
| `image_file` | image | 否 | - | 参考图片（支持数组，多张参考图） |
|
||
| `video_file` | video | 否 | - | 参考视频（支持数组） |
|
||
| `audio_file` | audio | 否 | - | 参考音频（支持数组） |
|
||
| `duration` | integer | 否 | `12` | 视频长度 |
|
||
| `resolution` | string | 否 | `720p` | 尺寸 |
|
||
| `ratio` | string | 否 | - | 宽高比 |
|
||
|
||
---
|
||
|
||
#### 通义万象（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 | 尺寸，如 `"1024x1024"` |
|
||
| `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": "1024x1024",
|
||
"n": 1
|
||
}
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
同步模型直接返回图像数据，异步模型返回任务信息。
|
||
|
||
**成功响应（以 wan2.7-image-pro 为例）：**
|
||
|
||
```json
|
||
{
|
||
"status": "SUCCEEDED",
|
||
"usage": {"image_count": 1},
|
||
"image_count": 1,
|
||
"image": ["https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/1d/...png"]
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
|
||
```json
|
||
{
|
||
"status": "FAILED",
|
||
"error": "InvalidParameter.InvalidParameter"
|
||
}
|
||
```
|
||
|
||
**异步模型提交响应：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"taskid": "task_xxx",
|
||
"status": "PENDING"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 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元/张 |
|
||
|
||
**成功响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "SUCCEEDED",
|
||
"usage": {"image_count": 1},
|
||
"image_count": 1,
|
||
"image": ["https://..."]
|
||
}
|
||
```
|
||
|
||
**失败响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "FAILED",
|
||
"error": "InvalidParameter.InvalidParameter"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 千问图像（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元/张 |
|
||
|
||
**成功响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "SUCCEEDED",
|
||
"usage": {"image_count": 1},
|
||
"image_count": 1,
|
||
"image": ["https://..."]
|
||
}
|
||
```
|
||
|
||
**失败响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "FAILED",
|
||
"error": "InvalidParameter.InvalidParameter"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
##### qwen-image-plus 系列 - 文生图
|
||
|
||
**异步模型**（需通过 `/v1/tasks?taskid=xxx` 查询状态）：
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 可选值 |
|
||
|--------|------|------|--------|------|--------|
|
||
| `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元/张 |
|
||
|
||
**响应示例（异步提交）：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"taskid": "task_xxx",
|
||
"status": "PENDING"
|
||
}
|
||
}
|
||
```
|
||
|
||
**查询任务状态（`/v1/tasks?taskid=task_xxx`）：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"status": "SUCCEEDED",
|
||
"usage": {"image_count": 1},
|
||
"image_count": 1,
|
||
"image": ["https://..."]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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 ***'
|
||
```
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 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 是否属于当前机构 |
|