Xiaomi MiMo 对话（OpenAI 兼容）

# Xiaomi MiMo 模型OpenAI 兼容 API 文档

## 1. 概述

本平台提供与 OpenAI 风格兼容的对话接口，开发者可使用标准 `Chat Completions` 调用方式接入 Xiaomi MiMo 模型（如 `mimo-v2-pro`）。

- **协议风格**：OpenAI-Compatible
- **基础地址**：`https://api.cxsee.com`
- **当前接口**：`POST /v1/chat/completions`
- **认证方式**：HTTP Header `api-key`

---

## 2. 认证与鉴权

在请求头中传入 API Key：

```http
api-key: sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
```

> 请妥善保管 API Key，勿在前端明文暴露。建议仅在服务端调用。

---

## 3. 接口说明

## `POST /v1/chat/completions`

创建一次对话补全（非流式或流式）。

### 3.1 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名称，例如：`mimo-v2-pro` |
| `messages` | array | 是 | 对话消息数组（OpenAI 标准格式） |
| `max_completion_tokens` | integer | 否 | 最大生成 token 数（推荐按业务设置） |
| `temperature` | number | 否 | 采样温度，范围建议 `0~2` |
| `top_p` | number | 否 | nucleus sampling 参数，范围 `0~1` |
| `stream` | boolean | 否 | 是否流式返回，默认 `false` |
| `stop` | string/array/null | 否 | 停止词 |
| `frequency_penalty` | number | 否 | 频率惩罚 |
| `presence_penalty` | number | 否 | 存在惩罚 |

### 3.2 `messages` 格式

```json
[
  { "role": "system", "content": "系统提示词" },
  { "role": "user", "content": "用户问题" }
]
```

支持角色：
- `system`
- `user`
- `assistant`

---

## 4. 调用示例

### 4.1 cURL（非流式）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/chat/completions' \
--header 'api-key: sk-xxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "mimo-v2-pro",
  "messages": [
    {
      "role": "system",
      "content": "You are MiMo, an AI assistant developed by Xiaomi."
    },
    {
      "role": "user",
      "content": "please introduce yourself"
    }
  ],
  "max_completion_tokens": 1024,
  "temperature": 1.0,
  "top_p": 0.95,
  "stream": false,
  "stop": null,
  "frequency_penalty": 0,
  "presence_penalty": 0
}'
```

---

## 5. 响应示例

```json
{
  "id": "e17ddea19086423696a8452044d50e24",
  "object": "chat.completion",
  "created": 1775433870,
  "model": "mimo-v2-pro",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "# Hello! I'm MiMo ...",
        "tool_calls": null,
        "reasoning_content": "The user is asking me to introduce myself..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 55,
    "completion_tokens": 251,
    "total_tokens": 306,
    "completion_tokens_details": {
      "reasoning_tokens": 28
    },
    "prompt_tokens_details": null
  }
}
```

### 字段说明（关键）

- `choices[].message.content`：模型最终回复内容
- `choices[].finish_reason`：结束原因（如 `stop`）
- `usage`：token 使用统计
- `reasoning_content`：推理内容（如平台开启该能力时返回，前端通常可选展示/隐藏）

---

## 6. OpenAI SDK 兼容调用示例

> 由于协议兼容，可复用 OpenAI SDK，只需替换 `baseURL` 与 `apiKey`。

### Node.js (openai sdk)

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CXSEE_API_KEY,
  baseURL: "https://api.cxsee.com/v1"
});

const resp = await client.chat.completions.create({
  model: "mimo-v2-pro",
  messages: [
    { role: "system", content: "You are MiMo, an AI assistant developed by Xiaomi." },
    { role: "user", content: "请介绍一下你自己" }
  ],
  temperature: 1.0,
  top_p: 0.95,
  max_completion_tokens: 1024,
  stream: false
});

console.log(resp.choices?.[0]?.message?.content);
```

---

## 7. 错误码与排障建议

常见问题：

1. **401/403 鉴权失败**
   - 检查 `api-key` 是否正确、是否过期、是否有调用权限。

2. **400 参数错误**
   - 检查 `model` 是否存在（如 `mimo-v2-pro`）。
   - 检查 `messages` 是否为合法数组，`role/content` 是否齐全。

3. **429 限流**
   - 降低并发，增加重试退避（exponential backoff）。

4. **5xx 服务异常**
   - 建议重试；若持续失败，请联系平台支持并附上 `request-id`/`id`。

---

## 8. 最佳实践

- 服务端托管 API Key，不要在浏览器端直连。
- 设置合理的 `max_completion_tokens` 控制成本。
- 根据场景调参：
  - 稳定回答：`temperature` 0.2~0.7
  - 创意生成：`temperature` 0.8~1.2
- 记录 `usage` 用于计费与监控。
- 对输出做内容安全与业务规则过滤。

---

## 9. 当前已验证模型

- `mimo-v2-pro` ✅（OpenAI 兼容 Chat Completions 调用成功）

---
## 10. 兼容性说明
本接口兼容 Anthropic Messages 调用风格。
若你同时使用 Anthropic 风格接口，可使用对应路由（如 /v1/messages），两者可并行接入。

上一篇：千问Qwen 对话（OpenAI 兼容）下一篇：Xiaomi MiMo 对话 Messages