# 盛航云 · 大模型 API（OpenAI 兼容）

> 本文档是给 AI 助手阅读的接入说明。用户把本文件喂给你后，你可以直接按下面的规则生成可运行的调用代码。

## 基本信息

- base_url：`https://yun.nmgshenghang.cn/v1`
- 鉴权：请求头 `Authorization: Bearer <API_KEY>`
- 协议：OpenAI 兼容（官方 openai SDK 可直接用，只改 base_url 和 api_key）
- 计费：预付费，按量扣余额；余额不足返回 402
- 一个 API Key 可调用本文档里的所有模型，不需要为不同模型分别申请 Key

## 快速开始

1. 注册：https://yun.nmgshenghang.cn/login.html?tab=reg
2. 登录后进控制台 → API Key → 新建，复制 Key（只显示一次）
3. 把代码里的 base_url 换成 `https://yun.nmgshenghang.cn/v1`，api_key 换成你的 Key

## 模型名怎么填

每个模型对应一个上游，`model` 直接填下表第一列的调用名，一字不差：

```
{"model": "glm-5.3", ...}
{"model": "qwen3.5-plus", ...}
{"model": "deepseek-v4-flash-0731", ...}
```

- 一个 Key 调所有模型，Key、地址、鉴权、返回结构都不变
- 价格按「元/百万 tokens」计，输入/输出分别计价
- 换模型只改 `model` 字段

## 可用模型（调用时 `model` 填第一列）

| model | 名称 | 类型 | 输入价 | 输出价 | 单位 | 上下文 | 能力 |
|---|---|---|---|---|---|---|---|
| `deepseek-v4.1-flash-1017` | DeepSeek-V4.1-Flash（1017） |  | 文本 | 2 | 8 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `deepseek-v4-flash-0731` | DeepSeek-V4-Flash（0731） |  | 文本 | 1 | 2 | 元 / 百万 tokens | 128K | 工具调用/视觉/缓存/流式 |
| `deepseek-v4.1-flash` | DeepSeek V4.1 Flash |  | 文本 | 1.33 | 5.33 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `glm-5.1` | GLM-5.1 |  | 文本 | 6 | 20.21 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `doubao-seedream-5.0-pro` | Doubao-Seedream 5.0 Pro |  | 图像 | 0.3 | — | 元 / 张 | — | 视觉 |
| `glm-5.2` | GLM-5.2 |  | 文本 | 5.79 | 20.05 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `glm-5.3-flashx` | GLM-5.3-Flashx |  | 文本 | 2 | — | 元 / 百万 tokens | — | 工具调用/视觉/缓存/流式 |
| `kimi-k2.5` | Kimi K2.5 |  | 文本 | 3.39 | — | 元 / 百万 tokens | — | 工具调用/视觉/缓存/流式 |
| `minimax-m2.7` | MiniMax M2.7 |  | 文本 | 2.1 | — | 元 / 百万 tokens | — | 工具调用/视觉/缓存/流式 |
| `glm-5.3` | GLM-5.3 |  | 文本 | 5.82 | 20.36 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `glm-5.3-flash` | GLM-5.3-Flash |  | 文本 | 0.63 | 2.21 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `kimi-k2.6` | Kimi K2.6 |  | 文本 | 5.52 | 22.91 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `kimi-k2.7-code` | Kimi K2.7 Code |  | 文本 | 5.52 | 22.91 | 元 / 百万 tokens | 128K | 工具调用/缓存/流式 |
| `kimi-k3` | Kimi K3 |  | 文本 | 16.48 | 82.42 | 元 / 百万 tokens | 128K | 工具调用/视觉/缓存/流式 |
| `minimax-m3` | MiniMax M3 |  | 文本 | 1.15 | 4.58 | 元 / 百万 tokens | 128K | 工具调用/视觉/流式 |
| `qwen3.5-plus` | Qwen3.5-Plus |  | 文本 | 0.96 | 1.56 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `qwen3.6-flash` | Qwen3.6-Flash |  | 文本 | 1.16 | 2.93 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `qwen3.6-plus` | Qwen3.6-Plus |  | 文本 | 1.08 | 6.46 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `qwen3.7-max` | Qwen3.7-Max |  | 文本 | 7.31 | 21.14 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `qwen3.7-plus` | Qwen3.7-Plus |  | 文本 | 1.3 | 3.39 | 元 / 百万 tokens | 128K | 工具调用/流式 |
| `qwen-image-3.0` | 万相 Qwen-Image 3.0 |  | 图像 | 0.11 | — | 元 / 张 | — | 视觉 |
| `qwen-image-3.0-pro` | 万相 Qwen-Image 3.0 Pro |  | 图像 | 0.15 | — | 元 / 张 | — | 视觉 |
| `qwen-image-2.0-pro` | 万相 Qwen-Image 2.0 Pro |  | 图像 | 0.3 | — | 元 / 张 | — | 视觉 |
| `minimax-h3` | MiniMax H3 视频 |  | 视频 | 0.61 | — | 元 / 秒 | — |  |
| `minimax-h3-max` | MiniMax H3 Max 视频 |  | 视频 | 0.5 | — | 元 / 秒 | — |  |

## 接口清单

### 1) 对话 / 补全（最常用）

```
POST https://yun.nmgshenghang.cn/v1/chat/completions
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "model": "glm-5.3",
  "messages": [{"role": "user", "content": "你好"}],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}
```

- `stream: true` 时返回 SSE，每行 `data: {...}`，最后一行 `data: [DONE]`
- 支持 OpenAI 的全部常用字段：`temperature` `top_p` `max_tokens` `stop` `tools` `tool_choice` `response_format`
- 多模态：`content` 可传数组 `[{"type":"text","text":"..."},{"type":"image_url","image_url":{"url":"..."}}]`（仅支持视觉的模型）
- 工具调用：与 OpenAI function calling 格式完全一致

### 2) 向量

```
POST https://yun.nmgshenghang.cn/v1/embeddings
{"model": "bge-m3", "input": ["文本1", "文本2"]}
```

### 3) 图像生成（按张计费）

```
POST https://yun.nmgshenghang.cn/v1/images/generations
{"model": "qwen-image-3.0", "prompt": "一只橘猫", "n": 1, "size": "1024x1024"}

返回：{"created":..., "data":[{"url":"https://..."}], "usage":{"images":1,"cost_yuan":0.18}}
```

### 4) 视频生成（按秒计费，异步）

```
POST https://yun.nmgshenghang.cn/v1/videos
{"model": "minimax-h3-max", "prompt": "海边日落", "duration": 6, "ratio": "16:9", "resolution": "768P"}
→ {"id":"<task_id>", "status":"queued", "poll_url":"/v1/videos/<task_id>"}

GET https://yun.nmgshenghang.cn/v1/videos/<task_id>      # 轮询直到 SUCCEEDED，返回 video_url
```

- `duration` 秒数，`ratio` 只能是 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9
- `resolution` 支持 480P / 768P

### 5) 语音合成（按万字符计费）

```
POST https://yun.nmgshenghang.cn/v1/audio/speech
{"model": "cosyvoice-v3.5-flash", "input": "要朗读的文字", "voice": "<音色ID>", "response_format": "mp3"}
```

- `voice` 必填，cosyvoice 系列没有系统音色，需要先在控制台创建音色

### 6) 查模型

```
GET https://yun.nmgshenghang.cn/v1/models              # 当前可调用的模型列表
GET https://yun.nmgshenghang.cn/v1/me                  # 我的额度 / 余额
```

## 错误码

| HTTP | type | 含义 | 怎么办 |
|---|---|---|---|
| 401 | authentication_error | Key 缺失或无效 | 检查 Authorization 头 |
| 402 | insufficient_balance | 余额不足 | 去控制台充值 |
| 404 | model_not_found | 模型名不存在或已下架 | 用 `GET /v1/models` 查可用名 |
| 429 | rate_limit_exceeded | 触发限流（默认 60 次/分钟） | 退避重试 |
| 502 | upstream_error | 上游异常 | 稍后重试，或改用同档位其他模型 |
| 400 | invalid_request_error | 参数不合法 | 看 message 字段 |

## 计费规则

- 文本：`(输入 tokens ÷ 1,000,000 × 输入价) + (输出 tokens ÷ 1,000,000 × 输出价)`，向上取整到分
- 图像：张数 × 单价（元/张）
- 视频：时长秒数 × 单价（元/秒）
- 语音：字符数 ÷ 10,000 × 单价（元/万字符）
- 每次调用后可在控制台「用量统计」查看明细，可按 Key / 模型拆分

## 生成代码时的注意事项

1. 不要假设 model 名可以用别名，必须用上表第一列的精确字符串
2. model 只认下表第一列的精确字符串，没有别名、也没有供应商后缀
3. 只有 `stream: true` 时才用 SSE 解析，其他情况是普通 JSON
4. 图片模型的返回是 URL，不是 base64
5. 视频是异步的：先 POST 拿 task_id，再 GET 轮询
6. 出错时优先看返回体里的 `error.message`，比 HTTP 状态码更具体

## 更多

- 人类可读文档：https://yun.nmgshenghang.cn/docs.html
- OpenAPI 规范：https://yun.nmgshenghang.cn/openapi.json
- Markdown 版：https://yun.nmgshenghang.cn/docs/api.md