# 元境平台API
元境平台为下游系统提供兼容openai接口协议的API，下游系统需要开通元境平台的API，要做以下步骤
* 注册一个账号
* 登录
* 申请APIKEY
* 充值

完成上述步骤后， 可以按照下面的例子实现文生文，文生图，文生视频，图生视频，参考生视频的模型推理服务

元境平台支持的模型，请参看模型广场

## 申请APIKEY

用户需要在元境平台（https://ai.opencomputing.cn）上用手机登录， 登录"创建APIKEY"

输入信息后点击提交，APIKEY创建完成

点击"复制apikey"， 在弹出窗口看到apikey， 复制他

## 充值
用户需要在元境平台上充值，目前支持alipay（支付宝）充值

## 查看当前余额

* 用户登录
* 呼出用户菜单
* 点击财务

## 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 等
}
```

## openai 兼容接口
我们提供一套兼容openai的API
### 文本生成
* path			/llmage/v1/chat/completions
* method		'POST'
* headers
```
{
	"Content-Type": "application/json", 
	"Authorization": "Bearer <your-apikey>"			# 客户从元境平台申请到的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",			# 任务id，后续查询结果
	"status": "CREATED"			# SUCCEEDED/FAILED/CREATED/PENDING/RUNNING
}
```

### 例子
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/image/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-apikey>" \
  -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",			# 任务id，后续查询结果
	"status": "CREATED"			# SUCCEEDED/FAILED/CREATED/PENDING/RUNNING
}
```

### 例子
快乐马文生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-apikey>" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "catelogid": "t2v",
    "prompt": "天上飞过各式各样的万圣节南瓜",
    "ratio": "4:3",
    "resolution": "720P",
    "duration": 4
  }'
```
seedance 1.5 文生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-apikey>" \
  -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"
}
```

### 例子
快乐马图生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Authorization: Bearer <your-apikey>" \
  -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 图生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Authorization: Bearer <your-apikey>" \
  -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 参考生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Authorization: Bearer <your-apikey>" \
  -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"
```
快乐马参考生视频
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/v1/video/generations \
  -H "Authorization: Bearer <your-apikey>" \
  -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"
}
```

### 例子
```
#!/usr/bin/env bash
curl -X GET "https://opencomputing.ai/llmage/v1/tasks?taskid=xxx" \
  -H "Authorization: Bearer <your-apikey>"
```

## 错误信息

* 401: {"error": "Invalid API Key"}
* 400: {"error": "Missing required parameter: prompt"}
* 429: {"error": "Insufficient balance"} (余额不足)