740 lines
24 KiB
Markdown
740 lines
24 KiB
Markdown
# 元境平台API
|
||
元境平台为下游系统提供兼容openai接口协议的API和真人素材管理API。使用平台API需要做以下步骤：
|
||
* 注册一个账号
|
||
* 登录
|
||
* 申请APIKEY
|
||
* 充值
|
||
|
||
完成上述步骤后，可以按照下面的接口文档实现各类服务。
|
||
|
||
元境平台支持的模型，请参看模型广场。
|
||
|
||
## 申请APIKEY
|
||
|
||
用户需要在元境平台（https://ai.opencomputing.cn）上用手机登录，登录"创建APIKEY"
|
||
|
||
输入信息后点击提交，APIKEY创建完成
|
||
|
||
点击"复制apikey"，在弹出窗口看到apikey，复制它
|
||
|
||
## 充值
|
||
用户需要在元境平台上充值，目前支持alipay（支付宝）充值
|
||
|
||
## 查看当前余额
|
||
|
||
* 用户登录
|
||
* 呼出用户菜单
|
||
* 点击财务
|
||
|
||
---
|
||
|
||
# 一、大模型API（兼容OpenAI）
|
||
|
||
## API对接的base url
|
||
https://opencomputing.ai
|
||
|
||
## 查询可用模型列表
|
||
* path /llmage/v1/models
|
||
* method GET
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* params (可选)
|
||
```
|
||
{
|
||
"catelogid": "t2v" # 按分类筛选，如 t2t/t2i/t2v/i2v/ref2v 等
|
||
}
|
||
```
|
||
|
||
## 文本生成
|
||
* path /llmage/v1/chat/completions
|
||
* method 'POST'
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* data
|
||
```
|
||
{
|
||
"model": "<模型名>", # 模型识别码，如 qwen3-max
|
||
"catelogid": "t2t", # 可选，默认 t2t
|
||
"prompt": "你的问题", # 提示词，必须输入
|
||
"sys_prompt": "", # 系统提示词，可选
|
||
"stream": true # 流式输出开关
|
||
}
|
||
```
|
||
|
||
* 返回
|
||
符合openai协议的流式或非流式结果
|
||
* 流式：
|
||
```
|
||
data: {"id": "chatcmpl-xxx", "object": "chat.completion.chunk", "created": 1775019761, "choices": [{"logprobs": null, "index": 0, "delta": {"content": "", "role": "assistant"}}], "model": "qwen3-max", "reasoning_content": null, "content": "", "finish": "0"}
|
||
...
|
||
data: [DONE]
|
||
```
|
||
* 非流式
|
||
```
|
||
{"id": "chatcmpl-xxx", "object": "chat.completion", "created": 1775011902, "choices": [{"finish_reason": "stop", "index": 0, "message": {"content": "我是通义千问...", "role": "assistant"}}], "model": "qwen3-max", "content": "我是通义千问...", "finish": "1", "usage": {...}}
|
||
```
|
||
|
||
## 文生图
|
||
| 模型名 | 供应商 | 说明 |
|
||
|--------|--------|------|
|
||
| wan2.2-t2i-plus | 阿里百炼 | 万相2.2专业版，创意性、稳定性、写实质感全面升级 |
|
||
| wan2.5-t2i-preview | 阿里百炼 | 万相2.5 preview版 |
|
||
| wan2.2-t2i-flash | 阿里百炼 | 万相2.2极速版，速度快，性价比高 |
|
||
| cogview-3-flash | 智谱AI | CogView-3-Flash 免费图像生成 |
|
||
|
||
### 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。如 wan2.2-t2i-plus |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2i` |
|
||
| prompt | string | 是 | - | 提示词。用于描述你希望生成的图片内容。 |
|
||
| negative_prompt | string | 否 | (empty) | 负面提示词。用于描述你希望避免出现的内容。 |
|
||
|
||
### 任务提交
|
||
* path /llmage/v1/image/generations
|
||
* method POST
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* data
|
||
```
|
||
{
|
||
"model": "wan2.2-t2i-plus",
|
||
"catelogid": "t2i",
|
||
"prompt": "一只猫坐在月亮上",
|
||
"negative_prompt": "模糊,低质量"
|
||
}
|
||
```
|
||
* 返回
|
||
```
|
||
{
|
||
"taskid": "xxx",
|
||
"status": "CREATED"
|
||
}
|
||
```
|
||
|
||
### 例子
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/image/generations \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer *** \
|
||
-d '{
|
||
"model": "wan2.2-t2i-plus",
|
||
"catelogid": "t2i",
|
||
"prompt": "一只猫坐在月亮上，水彩画风格"
|
||
}'
|
||
```
|
||
|
||
## 文生视频
|
||
| 模型名 | 供应商 | 说明 |
|
||
|--------|--------|------|
|
||
| happyhorse-1.0-t2v | 阿里云 | 快乐马文生视频 |
|
||
| doubao-seedance-2-0-260128 | 豆包 | seedance 2.0 |
|
||
| dreamina-seedance-2-0-260128 | We Token AI | 豆包海外版 |
|
||
| doubao-seedance-1-5-pro-251215 | 豆包 | seedance 1.5 |
|
||
| wan2.6-t2v | 通义万象 | 万象2.6文生视频 |
|
||
| viduq3-pro | vidu | vidu文生视频 |
|
||
|
||
### happyhorse-1.0-t2v 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`happyhorse-1.0-t2v` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| resolution | string | 否 | `720P` | 分辨率。可选：`720P`, `1080P` |
|
||
| ratio | string | 否 | adaptive | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
|
||
| duration | integer | 否 | `5` | 视频时长（秒）。 |
|
||
|
||
### seedance 2.0 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`doubao-seedance-2-0-260128` 或 `doubao-seedance-2-0-fast-260128` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| resolution | string | 否 | `720p` | 分辨率。可选：`480p`, `720p`, `1080p` |
|
||
| ratio | string | 否 | adaptive | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
|
||
| duration | integer | 否 | `5` | 视频时长（秒）。 |
|
||
|
||
### 万象 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`wan2.6-t2v` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| negative_prompt | string | 否 | (empty) | 负面提示词。 |
|
||
| size | string | 否 | `1920*1080` | 视频尺寸。可选：`832*480`, `480*832`, `624*624`, `1280*720`, `720*1280`, `960*960`, `1920*1080`, `1080*1920`, `1440*1440` |
|
||
| duration | integer | 否 | `15` | 视频时长（秒）。可选：`5`, `10`, `15` |
|
||
|
||
### vidu 上传参数
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`viduq3-pro` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| off_peak | string | 否 | `N` | 错峰执行。可选：`Y` (是), `N` (否) |
|
||
| duration | integer | 否 | `10` | 视频长度（秒）。范围：1-16 秒 |
|
||
| ratio | string | 否 | `16:9` | 宽高比。可选：`16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
|
||
| resolution | string | 否 | `1080p` | 分辨率。可选：`540p`, `720p`, `1080p` |
|
||
|
||
### seedance 1.5 上传数据要求
|
||
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`doubao-seedance-1-5-pro-251215` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `t2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| ratio | string | 否 | - | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive` |
|
||
| resolution | string | 否 | `1080p` | 分辨率。可选：`480p`, `720p`, `1080p` |
|
||
| duration | integer | 否 | `12` | 视频时长（秒）。 |
|
||
|
||
### 任务提交
|
||
* path /llmage/v1/video/generations
|
||
* method POST
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* data
|
||
不同的模型需要的数据不同，请看上方各模型的上传数据说明。必须包含 model 和 catelogid。
|
||
|
||
* 返回
|
||
```
|
||
{
|
||
"taskid": "xxx",
|
||
"status": "CREATED"
|
||
}
|
||
```
|
||
|
||
### 例子
|
||
快乐马文生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer *** \
|
||
-d '{
|
||
"model": "happyhorse-1.0-t2v",
|
||
"catelogid": "t2v",
|
||
"prompt": "天上飞过各式各样的万圣节南瓜",
|
||
"ratio": "4:3",
|
||
"resolution": "720P",
|
||
"duration": 4
|
||
}'
|
||
```
|
||
seedance 1.5 文生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer *** \
|
||
-d '{
|
||
"model": "doubao-seedance-1-5-pro-251215",
|
||
"catelogid": "t2v",
|
||
"prompt": "小猫在抓老鼠",
|
||
"duration": 5,
|
||
"ratio": "16:9",
|
||
"resolution": "480p"
|
||
}'
|
||
```
|
||
|
||
## 图生视频
|
||
| 模型名 | 供应商 | 说明 |
|
||
|--------|--------|------|
|
||
| happyhorse-1.0-i2v | 阿里云 | 快乐马图生视频（首帧） |
|
||
| doubao-seedance-2-0-260128 | 豆包 | seedance 2.0 图生视频 |
|
||
| dreamina-seedance-2-0-260128 | We Token AI | 豆包海外版图生视频 |
|
||
| doubao-seedance-1-5-pro-251215 | 豆包 | seedance 1.5 图生视频 |
|
||
| viduq3-pro | vidu | vidu首尾帧图生视频 |
|
||
| wan2.6-r2v | 通义万象 | 万象2.6预置角色生视频 |
|
||
|
||
### 快乐马上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`happyhorse-1.0-i2v` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `i2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| image_file | file | 是 | - | 首帧图片。 |
|
||
| resolution | string | 否 | `720P` | 分辨率。可选：`720P`, `1080P` |
|
||
| duration | integer | 否 | `5` | 视频时长（秒）。 |
|
||
|
||
### seedance 2.0 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`doubao-seedance-2-0-260128` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `i2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| image1_file | file | 是 | - | 首帧图片。 |
|
||
| image2_file | file | 是 | - | 尾帧图片。 |
|
||
| resolution | string | 否 | `720p` | 分辨率。可选：`480p`, `720p`, `1080p` |
|
||
| ratio | string | 否 | adaptive | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
|
||
| duration | integer | 否 | `5` | 视频时长（秒）。 |
|
||
|
||
### 通义万象上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`wan2.6-r2v` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `i2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| negative_prompt | string | 否 | (empty) | 负面提示词。 |
|
||
| size | string | 否 | `1920*1080` | 视频尺寸。 |
|
||
| duration | integer | 否 | `15` | 视频时长（秒）。可选：`5`, `10`, `15` |
|
||
| image_file1 | file | 是 | - | 首帧图片。 |
|
||
| image_file2 | file | 是 | - | 尾帧图片。 |
|
||
|
||
### vidu 上传数据要求
|
||
| 字段名 (Name) | 类型 (Type) | 必填 (Required) | 默认值 (Default) | 说明 (Description) |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`viduq3-pro` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `i2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| off_peak | string | 否 | `N` | 错峰执行。可选：`Y` (是), `N` (否) |
|
||
| image_file1 | file | 是 | - | 首帧图片。 |
|
||
| image_file2 | file | 是 | - | 尾帧图片。 |
|
||
| duration | integer | 否 | `10` | 视频长度（秒）。范围：1-16 秒 |
|
||
| ratio | string | 否 | `16:9` | 宽高比。可选：`16:9`, `9:16`, `4:3`, `3:4`, `1:1` |
|
||
| resolution | string | 否 | `1080p` | 分辨率。可选：`540p`, `720p`, `1080p` |
|
||
|
||
### seedance 1.5 上传数据要求
|
||
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`doubao-seedance-1-5-pro-251215` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `i2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| ratio | string | 否 | - | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive` |
|
||
| resolution | string | 否 | `1080p` | 分辨率。可选：`480p`, `720p`, `1080p` |
|
||
| duration | integer | 否 | `12` | 视频时长（秒）。 |
|
||
| image_file1 | file | 否 | - | 首帧图片。 |
|
||
| image_file2 | file | 否 | - | 尾帧图片。 |
|
||
|
||
### 任务提交
|
||
* path /llmage/v1/video/generations
|
||
* method POST
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* data
|
||
不同的模型需要的数据不同，请看上方各模型的上传数据说明。必须包含 model 和 catelogid。
|
||
|
||
* 返回
|
||
```
|
||
{
|
||
"taskid": "xxx",
|
||
"status": "CREATED"
|
||
}
|
||
```
|
||
|
||
### 例子
|
||
快乐马图生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Authorization: Bearer *** \
|
||
-F "model=happyhorse-1.0-i2v" \
|
||
-F "catelogid=i2v" \
|
||
-F "prompt=图片变换为万圣节各种南瓜飞上天" \
|
||
-F "duration=15" \
|
||
-F "resolution=720P" \
|
||
-F "image_file=@./02.jpg"
|
||
```
|
||
seedance 2.0 图生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Authorization: Bearer *** \
|
||
-F "model=doubao-seedance-2-0-260128" \
|
||
-F "catelogid=i2v" \
|
||
-F "prompt=从图片1到图片2丝滑转换" \
|
||
-F "duration=5" \
|
||
-F "ratio=16:9" \
|
||
-F "resolution=480p" \
|
||
-F "image1_file=@./myimg1.jpg" \
|
||
-F "image2_file=@./myimg2.jpg"
|
||
```
|
||
|
||
## 参考生视频
|
||
| 模型名 | 供应商 | 说明 |
|
||
|--------|--------|------|
|
||
| happyhorse-1.0-r2v | 阿里云 | 快乐马参考生视频 |
|
||
| doubao-seedance-2-0-260128 | 豆包 | seedance 2.0 参考生视频 |
|
||
| dreamina-seedance-2-0-260128 | We Token AI | 豆包海外版参考生视频 |
|
||
|
||
### 快乐马 上传数据要求
|
||
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`happyhorse-1.0-r2v` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `ref2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| ratio | string | 否 | - | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
|
||
| resolution | string | 否 | `1080P` | 分辨率。可选：`720P`, `1080P` |
|
||
| duration | integer | 否 | `15` | 视频时长（秒）。 |
|
||
| image_files | 数组 | 是 | [] | 参考图片数组。最多9个图片文件 |
|
||
|
||
### seedance 2.0 上传数据要求
|
||
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| model | string | 是 | - | 模型名。`doubao-seedance-2-0-260128` |
|
||
| catelogid | string | 是 | - | 分类标识。固定为 `ref2v` |
|
||
| prompt | string | 是 | - | 提示词。 |
|
||
| ratio | string | 否 | - | 宽高比。可选：`16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
|
||
| resolution | string | 否 | `1080p` | 分辨率。可选：`480p`, `720p`, `1080p` |
|
||
| duration | integer | 否 | `12` | 视频时长（秒）。 |
|
||
| image_files | 数组 | 是 | [] | 参考图片数组。 |
|
||
| video_files | 数组 | 否 | [] | 参考视频数组。 |
|
||
| audio_files | 数组 | 否 | [] | 参考音频数组。 |
|
||
|
||
### 任务提交
|
||
* path /llmage/v1/video/generations
|
||
* method POST
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* data
|
||
不同的模型需要的数据不同，请看上方各模型的上传数据说明。必须包含 model 和 catelogid。
|
||
|
||
* 返回
|
||
```
|
||
{
|
||
"taskid": "xxx",
|
||
"status": "CREATED"
|
||
}
|
||
```
|
||
|
||
### 例子
|
||
seedance 2.0 参考生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Authorization: Bearer *** \
|
||
-F "model=doubao-seedance-2-0-260128" \
|
||
-F "catelogid=ref2v" \
|
||
-F "image_files=@./1.jpg" \
|
||
-F "image_files=@./2.jpg" \
|
||
-F "prompt=平滑过渡从第一张图片到第二张图片" \
|
||
-F "ratio=4:3" \
|
||
-F "resolution=720p" \
|
||
-F "duration=4"
|
||
```
|
||
快乐马参考生视频
|
||
```bash
|
||
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
|
||
-H "Authorization: Bearer *** \
|
||
-F "model=happyhorse-1.0-r2v" \
|
||
-F "catelogid=ref2v" \
|
||
-F "image_files=@./1.jpg" \
|
||
-F "image_files=@./2.jpg" \
|
||
-F "prompt=平滑过渡从第一张图片到第二张图片" \
|
||
-F "ratio=4:3" \
|
||
-F "resolution=720P" \
|
||
-F "duration=4"
|
||
```
|
||
|
||
## 查询任务状态
|
||
* path /llmage/v1/tasks
|
||
* method GET
|
||
* headers
|
||
```
|
||
{
|
||
"Content-Type": "application/json",
|
||
"Authorization": "Bearer <your-apikey>"
|
||
}
|
||
```
|
||
* params
|
||
```
|
||
{
|
||
"taskid": "xxx"
|
||
}
|
||
```
|
||
* 返回
|
||
```
|
||
{
|
||
"status": "SUCCEEDED", # SUCCEEDED/FAILED/CREATED/PENDING/RUNNING
|
||
"taskid": "xxx", # 供应商任务号
|
||
"usage": {...}, # SUCCEEDED时有效，计费信息
|
||
"image": "https://...", # 图片/视频封面url
|
||
"video": "https://..." # 视频url
|
||
}
|
||
```
|
||
返回例子：
|
||
```
|
||
{
|
||
"usage": {
|
||
"action": "t2v",
|
||
"credits": 10,
|
||
"type": "text2video",
|
||
"model": "viduq3-pro",
|
||
"resolution": "540p",
|
||
"off_peak": false,
|
||
"duration": 1
|
||
},
|
||
"image": "https://opencomputing.ai/idfile?path=/tmp/19/43/137/39/cover.jpeg",
|
||
"video": "https://opencomputing.ai/idfile?path=/tmp/137/173/31/47/video.mp4",
|
||
"status": "SUCCEEDED"
|
||
}
|
||
```
|
||
|
||
### 例子
|
||
```bash
|
||
curl -X GET "https://opencomputing.ai/llmage/v1/tasks?taskid=xxx" \
|
||
-H "Authorization: Bearer ***
|
||
```
|
||
|
||
---
|
||
|
||
# 二、真人素材API
|
||
|
||
真人素材API提供真人人像认证、素材上传和素材管理功能。所有接口通过 **Bearer Token** 认证，与大模型API使用相同的APIKEY。
|
||
|
||
## API对接的base url
|
||
https://token.opencomputing.cn
|
||
|
||
## 业务流程
|
||
|
||
1. **真人认证**：调用方发起认证请求，获取 H5 链接供终端用户完成人脸识别。
|
||
2. **查询已认证组合**：查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 group_id。
|
||
3. **上传素材**：使用已认证的组合 ID 上传图片/视频，系统验证组合归属关系。
|
||
4. **状态同步**：轮询检查素材处理状态。
|
||
|
||
## 1. 获取真人认证链接 (H5)
|
||
**Endpoint**: `POST /reallife_asset/api/rl_verify.dspy`
|
||
|
||
检查供应商配置通过后，调用供应商接口创建认证会话。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `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": "..."
|
||
}
|
||
}
|
||
```
|
||
**失败**（未配置）：
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"data": {"message": "供应商配置不存在"}
|
||
}
|
||
```
|
||
|
||
**注意**：终端用户在 H5 页面完成认证后，系统将自动登记该机构与组合 ID 的映射关系。
|
||
|
||
## 2. 查询已认证的组合列表
|
||
**Endpoint**: `POST /reallife_asset/api/rl_query_groups.dspy`
|
||
|
||
查询当前机构下所有已认证的组合 ID，用于上传素材时选择有效的 `group_id`。
|
||
|
||
### 请求参数
|
||
无需参数，系统自动从 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"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 上传素材
|
||
**Endpoint**: `POST /reallife_asset/api/rl_upload.dspy`
|
||
|
||
向已认证的素材组合上传图片或视频素材。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `vendor_group_id` | 是 | 认证成功后获得的供应商组合 ID（通过 `rl_query_groups` 查询） |
|
||
| `source_url` | 是 | 素材的公网 URL 或 `data:` 格式的 base64 编码（系统自动转为公网地址） |
|
||
| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
|
||
| `name` | 否 | 素材名称 |
|
||
|
||
### 请求示例（公网 URL）
|
||
```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"
|
||
}'
|
||
```
|
||
|
||
### 请求示例（base64 直接上传）
|
||
```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": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
|
||
"asset_type": "Image",
|
||
"name": "模特B"
|
||
}'
|
||
```
|
||
|
||
### 返回示例
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"data": {
|
||
"id": "asset_record_id_xxx",
|
||
"vendor_asset_id": "asset-2026...",
|
||
"status": "Processing"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**：上传是异步操作，初始状态为 `Processing`，需调用查询素材状态接口轮询。
|
||
|
||
## 4. 查询素材状态
|
||
**Endpoint**: `POST /reallife_asset/api/rl_status.dspy`
|
||
|
||
查询素材的处理状态（Processing / Active / Failed）。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `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` 是临时签名下载链接，过期后可通过再次调用 `rl_status` 获取新链接。素材的永久引用为上传时返回的 `vendor_asset_id`。
|
||
|
||
## 5. 查询组合下所有素材
|
||
**Endpoint**: `POST /reallife_asset/api/rl_assets.dspy`
|
||
|
||
查询指定 `vendor_group_id` 下的所有素材列表。
|
||
|
||
### 请求参数
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `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
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误信息
|
||
|
||
### 大模型API错误
|
||
* 401: `{"error": "Invalid API Key"}`
|
||
* 400: `{"error": "Missing required parameter: prompt"}`
|
||
* 429: `{"error": "Insufficient balance"}` (余额不足)
|
||
|
||
### 真人素材API错误
|
||
| 错误信息 | 原因 | 解决方案 |
|
||
|----------|------|----------|
|
||
| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 |
|
||
| `供应商服务已停用` | 供应商配置状态非 active | 联系管理员激活配置 |
|
||
| `无效的素材组合ID或无权访问` | vendor_group_id 不属于当前机构 | 确认是否已完成认证并使用正确的 ID |
|
||
| `素材不存在或无权访问` | asset_id 无效或归属错误 | 检查 ID 是否正确 |
|
||
| `尚未完成认证或认证失败` | 认证未完成 | 等待用户完成 H5 认证 |
|