Xiaomi MiMo 函数调用 Messages - 数字先锋API文档

# Xiaomi MiMo API 文档（函数调用 / Tool Use）
**接口**：`POST /v1/messages`
**Base URL**：`https://api.cxsee.com`
**协议**：Anthropic Messages 兼容

---

## 1. 鉴权

在请求头中传入 API Key：

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

---

## 2. 功能说明

当你在请求中提供 `tools` 后，模型可根据用户问题决定是否调用工具：

- 若需要调用工具：返回 `content.type = "tool_use"`，并且 `stop_reason = "tool_use"`
- 业务服务执行工具后，将结果通过 `tool_result` 回传
- 模型再生成最终答案（通常 `stop_reason = "end_turn"`）

---

## 3. 请求参数

### 3.1 顶层参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型名，例如 `mimo-v2-pro` |
| `messages` | array | 是 | 对话历史 |
| `max_tokens` | integer | 是 | 最大输出 token |
| `system` | string | 否 | 系统提示词 |
| `temperature` | number | 否 | 采样温度 |
| `top_p` | number | 否 | nucleus sampling |
| `stream` | boolean | 否 | 是否流式输出 |
| `tools` | array | 否 | 可用工具列表（函数定义） |
| `tool_choice` | object/string | 否 | 工具调用策略（auto/none/指定工具） |
| `stop_sequences` | array/null | 否 | 停止序列 |

---

## 4. `messages` 格式

### 4.1 普通用户消息（文本）

```json
{
  "role": "user",
  "content": "What is the weather like in Beijing today?"
}
```

或数组写法：

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is the weather like in Beijing today?" }
  ]
}
```

### 4.2 模型发起工具调用（assistant -> tool_use）

```json
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "call_xxx",
      "name": "get_weather",
      "input": {
        "location": "Beijing"
      }
    }
  ]
}
```

### 4.3 工具结果回传（user -> tool_result）

```json
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "call_xxx",
      "content": "{\"location\":\"Beijing\",\"temperature_c\":26,\"condition\":\"Sunny\"}"
    }
  ]
}
```

> `tool_use_id` 必须与上一步 `tool_use.id` 一致。

---

## 5. `tools` 定义格式

```json
"tools": [
  {
    "name": "get_weather",
    "description": "Get the current weather of the specified location",
    "type": "custom",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name, e.g., Beijing"
        }
      },
      "required": ["location"]
    }
  }
]
```

字段说明：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `name` | string | 是 | 工具名（函数名） |
| `description` | string | 建议 | 工具用途说明 |
| `type` | string | 否 | 工具类型，建议 `custom` |
| `input_schema` | object | 是 | JSON Schema 输入参数定义 |

---

## 6. `tool_choice` 用法

### 自动选择（推荐）
```json
"tool_choice": { "type": "auto" }
```

### 禁用工具
```json
"tool_choice": { "type": "none" }
```

### 强制指定某个工具（如网关支持）
```json
"tool_choice": {
  "type": "tool",
  "name": "get_weather"
}
```

---

## 7. 完整调用流程（两轮）

---

### 第 1 轮：提交问题 + 工具定义

#### 请求

```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": "What is the weather like in Beijing today?"
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather of the specified location",
      "type": "custom",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name, e.g., Beijing"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "tool_choice": { "type": "auto" }
}'
```

#### 响应（模型请求调用工具）

```json
{
  "id": "a02cbcf015204b1da41ea9aeaaf1219e",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "call_bc5b2d9877d041689f9d5f2d",
      "name": "get_weather",
      "input": {
        "location": "Beijing"
      }
    }
  ],
  "stop_reason": "tool_use",
  "model": "mimo-v2-pro"
}
```

---

### 第 2 轮：回传工具执行结果

> 你的服务端执行 `get_weather(location=Beijing)` 后，将结果回传给模型。

#### 请求

```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": "What is the weather like in Beijing today?"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "call_bc5b2d9877d041689f9d5f2d",
          "name": "get_weather",
          "input": { "location": "Beijing" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "call_bc5b2d9877d041689f9d5f2d",
          "content": "{\"location\":\"Beijing\",\"temperature_c\":26,\"condition\":\"Sunny\"}"
        }
      ]
    }
  ]
}'
```

#### 响应（模型生成最终回答）

```json
{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The weather in Beijing is sunny, around 26°C."
    }
  ],
  "stop_reason": "end_turn"
}
```

---

## 8. 响应字段说明

| 字段 | 说明 |
|---|---|
| `id` | 本次响应 ID |
| `type` | 固定为 `message` |
| `role` | 固定为 `assistant` |
| `content` | 输出内容（可能是 `text` 或 `tool_use`） |
| `stop_reason` | 结束原因：`end_turn`/`tool_use` 等 |
| `model` | 实际使用模型 |
| `usage` | token 使用量统计 |

---

## 9. 错误码

| HTTP 状态码 | 含义 |
|---|---|
| 400 | 请求参数错误（JSON 格式、字段缺失等） |
| 401 | API Key 无效或缺失 |
| 403 | 无权限使用该模型/工具能力 |
| 404 | 路径不存在 |
| 429 | 请求过快，触发限流 |
| 500 | 服务内部错误 |
| 503 | 服务暂不可用 |

错误格式示例：

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

---

## 10. 接入建议（生产环境）

1. **服务端执行工具**：不要让前端直接执行敏感工具。
2. **参数校验**：严格按 `input_schema` 校验工具输入。
3. **幂等与重试**：429/503 使用指数退避重试。
4. **日志追踪**：记录 `id`、`tool_use.id`、业务 trace_id。
5. **超时控制**：工具执行设置超时，避免会话阻塞。

---

上一篇：Xiaomi MiMo 对话 Messages 下一篇：OCR 识别 API 文档