---
name: mms-ai-open-platform
description: >-
  MMS AI 开放平台快速对接技能。覆盖 Base URL、API Key、OpenAI 兼容交流接口、
  浏览器本机授权（Browser Auth）、模型列表与常见排障。
  触发词：MMS AI、mmsai.cn、/v1/chat/completions、OpenAI 兼容、Browser Auth、
  开发平台对接、API Key、UOpenClaw、智能体接入。
---

# MMS AI 开放平台对接

把本文件放入 Cursor / Claude Code / 其它 AI 编程工具的 skills 目录后，智能体即可按本文协助完成平台接入。

## 平台要点

| 项 | 值 |
|---|---|
| 文档 | https://mmsai.cn/developers |
| Base URL | `https://mmsai.cn/v1` |
| 鉴权 | `Authorization: Bearer <API_KEY>` |
| 密钥管理 | https://mmsai.cn/console?menu=apiKeys |
| 充值 | https://mmsai.cn/console?menu=balance&focus=recharge |

**已开放（Beta）**：`GET /v1/models`、`POST /v1/chat/completions`（含 SSE 流式）。  
**规划中**：图片 / 视频 / 数字人 / 音频 / 任务 / 余额与价格等媒体与账单接口，调用前以文档与实际 404/501 为准。

## 快速验证

```bash
curl https://mmsai.cn/v1/models \
  -H "Authorization: Bearer $MMS_API_KEY"
```

```bash
curl https://mmsai.cn/v1/chat/completions \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<从 /v1/models 取得的 id>","messages":[{"role":"user","content":"你好"}]}'
```

OpenAI SDK（把 `baseURL` 指到 MMS）：

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MMS_API_KEY,
  baseURL: "https://mmsai.cn/v1",
});

const response = await client.chat.completions.create({
  model: "<model_id>",
  messages: [{ role: "user", content: "你好" }],
});
```

流式：请求体加 `"stream": true`，按 SSE 解析 `data:` 行，直至 `[DONE]`。

## 获取 API Key

1. 用户注册并登录 https://mmsai.cn  
2. 打开控制台 → **API 密钥**，创建密钥（明文仅显示一次）  
3. 环境变量建议：`MMS_API_KEY`  
4. **禁止**把密钥写入前端包、公开仓库或日志

## 浏览器本机授权（终端 / 桌面应用）

任意合法 `client` 均可走本机回跳，无需用户手工复制密钥。

1. 本机监听 `http://127.0.0.1:<port>/callback`（仅 loopback）  
2. 浏览器打开：

```text
https://mmsai.cn/connect/browser-auth?client=<client_id>&response_type=api_key&redirect_uri=http%3A%2F%2F127.0.0.1%3A<port>%2Fcallback&state=<random>
```

3. 用户登录并同意后，本机收到 `api_key` + `state`（或 `error=access_denied`）  
4. 校验 `state` 后保存密钥，再调 `GET /v1/models` 验证  

约束：`redirect_uri` 仅允许 `127.0.0.1` / `localhost` + `/callback`；每个 `client` 对应密钥名 `BA:<client>`，再次授权会轮换旧 Key。

## 请求约定

- JSON：`Content-Type: application/json`，UTF-8  
- 媒体类建议带稳定 `Idempotency-Key`，超时用原键重试防重复扣费  
- 响应头 `x-request-id`：排障时请保留  
- 模型 `id` 以 `GET /v1/models` 为准，不要硬编码服务商私有名  

## 常见错误

| HTTP | 含义 | 处理 |
|---|---|---|
| 401 | 密钥无效或缺失 | 检查 Bearer、是否已重置 |
| 402 | 余额不足 | 引导充值：`https://mmsai.cn/console?menu=balance&focus=recharge` |
| 429 | 限流 | 按 `Retry-After` 退避 |
| 5xx | 服务异常 | 带 `x-request-id` 重试或报障 |

## 智能体协助清单

接入任务时按序：

1. 确认 Base URL = `https://mmsai.cn/v1`  
2. 确认密钥来源（控制台创建或 Browser Auth）  
3. 先 `GET /v1/models`，再用返回的 `id` 调 chat  
4. 流式 / 非流式按产品需求选择  
5. 余额不足时给出官网充值链接，勿编造其它支付入口  
6. 未开放的媒体接口：说明仍为预览，引导查阅 https://mmsai.cn/developers  

## 参考

- 开发文档：https://mmsai.cn/developers  
- 控制台：https://mmsai.cn/console