Xiaomi MiMo 对话 Messages - 数字先锋API文档

# MiMo API 文档（Anthropic 兼容）

> 基础地址：`https://api.cxsee.com`
> 协议风格：Anthropic Messages API 兼容

---

## 1. 快速开始

### 1.1 鉴权
在请求头中传入 API Key：

- Header 名称：`api-key`
- 示例：`api-key: sk-xxxxxxxxxxxxxxxx`

### 1.2 内容类型
- `Content-Type: application/json`

### 1.3 基础 URL
- `https://api.cxsee.com`

---

## 2. 创建对话（Messages）

### 2.1 接口地址
`POST /v1/messages`

### 2.2 请求体参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型名称，如 `mimo-v2-pro` |
| `messages` | array | 是 | 对话消息数组 |
| `max_tokens` | integer | 是 | 最大输出 token 数 |
| `system` | string | 否 | 系统提示词 |
| `temperature` | number | 否 | 采样温度，常用 0~2 |
| `top_p` | number | 否 | nucleus sampling 参数 |
| `stream` | boolean | 否 | 是否流式返回，默认 `false` |
| `stop_sequences` | array/null | 否 | 停止序列 |
| `thinking` | object | 否 | 思考配置（如不支持可忽略） |

### 2.3 `messages` 格式
每条消息结构如下：

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "你好，请介绍一下你自己" }
  ]
}
```

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

---

## 3. 请求示例（非流式）

### cURL

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

### 成功响应示例

```json
{
  "id": "628760015c714430bc842a661ee6d7cb",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! I'm MiMo..."
    }
  ],
  "stop_reason": "end_turn",
  "model": "mimo-v2-pro",
  "usage": {
    "input_tokens": 55,
    "output_tokens": 266
  }
}
```

---

## 4. 流式输出（stream=true）

将请求体中的 `stream` 设置为 `true`，服务端将返回流式事件数据（SSE/分块传输，具体以网关实现为准）。

### cURL 示例（流式）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/messages' \
--header 'api-key: sk-xxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "mimo-v2-pro",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "写一段 100 字的自我介绍" }
      ]
    }
  ],
  "stream": true
}'
```

---

## 5. 错误码说明

| HTTP 状态码 | 含义 | 说明 |
|---|---|---|
| 400 | Bad Request | 请求参数错误、JSON 格式错误 |
| 401 | Unauthorized | API Key 缺失或无效 |
| 403 | Forbidden | 无权限访问该模型/接口 |
| 404 | Not Found | 路径不存在 |
| 429 | Too Many Requests | 触发限流 |
| 500 | Internal Server Error | 服务内部错误 |
| 503 | Service Unavailable | 服务暂不可用 |

### 错误响应示例

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}
```

---

## 6. 最佳实践

1. **设置合理 `max_tokens`**：避免不必要的输出成本。
2. **生产环境开启重试**：对 429/503 使用指数退避。
3. **记录请求 ID**：便于问题排查（响应中的 `id`）。
4. **做好超时控制**：建议客户端超时 30~120 秒。
5. **保护 API Key**：不要在前端明文暴露密钥。

---

## 7. 兼容性说明

本接口兼容 Anthropic Messages 调用风格。
若你同时使用 OpenAI 风格接口，可使用对应路由（如 `/v1/chat/completions`），两者可并行接入。

---

上一篇：Xiaomi MiMo 对话（OpenAI 兼容）下一篇：Xiaomi MiMo 函数调用 Messages