# MiniMax-文本对话

适用于多轮对话、工具调用、Agent 与长上下文等场景。官方以 OpenAI 兼容 **Chat Completions** 为主；站内主入口如下。

<div class="doc-interface">
  <p><strong>URL</strong>：<code>/v1/chat/completions</code></p>
  <p><strong>Method</strong>：<code>POST</code></p>
</div>

> 历史兼容：`POST /v1/text/chatcompletion_v2` 仍可用，行为与本接口一致（网关转发至上游 `/v1/chat/completions`）。  
> 另支持 Anthropic Messages（见平台 Anthropic 兼容路由）。请求体可使用 `max_tokens`，网关会映射为 `max_completion_tokens` 后转发。

<div class="doc-api-spec">

## 授权

### `Authorization`

- **类型** `string` · **位置** `header` · **必填**
- **认证方式** **HTTP: Bearer Auth**（Security Scheme Type: `http`）
- **说明** 请求头格式为 `Authorization: Bearer <API_KEY>`，用于验证账户/调用方身份。请在 [公共参数](api-common.md) 中取得 API Key 并按 `Bearer` 方案传入。

## 请求头

### `Content-Type`

- **类型** 字符串枚举 · **默认值** `application/json` · **必填**
- **说明** 请求体媒介类型须为 `application/json`，确保正文按 JSON 解析。可选值一般为 `application/json`（同 [官方 OpenAPI](https://platform.minimaxi.com/docs/api-reference/text-chat)）。

## 请求体

以下仅描述 **JSON 请求体** 内字段；**Authorization** 与 **Content-Type** 见上文「授权」「请求头」。

### `model`

- **类型** `string` · **必填**
- **说明** 模型 ID，须与当次要调用的模型一致。推荐 `MiniMax-M3`；亦可使用控制台已开通的 `MiniMax-M2.7` 等 M2.x。详见 [官方 Chat Completions](https://platform.minimaxi.com/docs/api-reference/text-chat)。

### `messages`

- **类型** `object[]` · **必填**
- **说明** 包含对话历史的消息列表。`MiniMax-M3` 支持文本，以及 `image_url` / `video_url` 等多模态内容块；M2.x 以文本与工具调用为主。

#### Message 单条

<div class="doc-api-nest doc-api-nest--bordered">

- **`role`**（`enum<string>`，必填）：常用 `system` / `user` / `assistant` / `tool`。
- **`content`**（`string` 或 `object[]`，必填）：文本字符串，或 OpenAI 风格内容块数组（如 `text`、`image_url`、`video_url`）。
- **`name`**（`string`，可选）：发送者名；同一 `role` 下多条时建议填以便区分。

</div>

### `stream`

- **类型** `boolean` · **可选** · **默认** `false`
- **说明** 为 `true` 时以流式返回，响应为 `text/event-stream`（SSE）；为 `false` 时待完整结果一次返回。

### `max_completion_tokens`

- **类型** `integer`（`int64`） · **可选**
- **说明** 生成长度上限（Token 数，最小为 `1`）。`MiniMax-M3` 推荐 `131072`（128K），上限 `524288`（512K）；M2.x 推荐 `65536`，上限约 `204800`。若 `finish_reason` 为 `length` 可适当调大。

### `thinking`

- **类型** `object` · **可选**
- **说明** 控制 `MiniMax-M3` 思考行为：`type` 可为 `adaptive`（开启）或 `disabled`（关闭）。OpenAI 兼容路径下省略时默认 adaptive；M2.x 的 thinking 无法关闭。详见 [官方](https://platform.minimaxi.com/docs/api-reference/text-chat)。

### `temperature`

- **类型** `number` · **可选** · **默认** `1.0`
- **说明** 温度，取值 **[0, 2]**。越高越随机，越低越稳定。

### `top_p`

- **类型** `number` · **可选** · **默认** `0.95`（M3）；M2.x 官方默认常见为 `0.9`
- **说明** 核采样，取值 **[0, 1]**，与 `temperature` 一起调节生成行为。

### `tools` / `tool_choice`

- **类型** 见 OpenAI 工具调用约定 · **可选**
- **说明** function 工具定义与选择策略；透传上游。

## 非流式 · 响应

成功时一般为 `200`，正文 `application/json`。字段与 [官方](https://platform.minimaxi.com/docs/api-reference/text-chat) 一致，节选如下。

### `id`

- **类型** `string`
- **说明** 本次响应唯一 ID。

### `object`

- **类型** `string`
- **说明** 非流式成功时一般为 `chat.completion`。

### `created`

- **类型** `integer`（`int64`）
- **说明** 响应创建时间的 Unix 时间戳，单位为**秒**。

### `model`

- **类型** `string`
- **说明** 实际使用的模型 ID（一般与请求一致，经网关时以返回为准）。

### `choices`

- **类型** `object[]`
- **说明** 候选列表，通常取 `choices[0]`。单条常见子字段：

<div class="doc-api-nest doc-api-nest--subparams">

#### `finish_reason`

- **类型** `string`
- **说明** `stop` 表示自然结束；`length` 表示达到 `max_completion_tokens` 上限而截断；工具场景可能为 `tool_calls`。

#### `index`

- **类型** `integer`
- **说明** 候选项下标，从 `0` 开始。

#### `message`

- **类型** `object`
- **说明** 非流式下为整段回复，至少含 `content`、`role`（常用 `assistant`）；可有 `reasoning_content`、`tool_calls` 等，以实际为准。

</div>

### `usage`

- **类型** `object` · 定义见 [官方 Usage](https://platform.minimaxi.com/docs/api-reference/text-chat)
- **说明** 常见含 `total_tokens`、`prompt_tokens`、`completion_tokens`；推理模型或含 `completion_tokens_details.reasoning_tokens` 等，以实际与计费规则为准。`MiniMax-M3` 按输入长度分档（≤512k / >512k）。

### `base_resp`

- **类型** `object` · 与 [官方 `base_resp`](https://platform.minimaxi.com/docs/api-reference/text-chat) 一致
- **说明** 通常 `status_code` 为 `0` 表示成功；非 0 时结合 `status_msg` 与 [错误码](https://platform.minimaxi.com/docs/api-reference/errorcode) 处理。

</div>

## 流式 · 响应

- **Content-Type** `text/event-stream`（`stream: true` 时）

### 传输格式

- **说明** 使用 **Server-Sent Events**，多行 `data:` 后接 JSON。按行解析、拼接；末段可含 `usage`、`base_resp` 等，同 [官方案例](https://platform.minimaxi.com/docs/api-reference/text-chat)。

### 各分片内 `object`

- **说明** 流中多为 `chat.completion.chunk`；收尾可能出现 `chat.completion` 等，**以实际 JSON 为准**。

### `choices[0].delta`

- **说明** 增量多为 `delta.content`；`delta.role` 或见于首包；出现 `finish_reason` 时该候选结束；偶见以 `message` 汇总，按行合并即可。

## cURL 示例（非流式）

```bash
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业、简洁的中文助手。"
      },
      {
        "role": "user",
        "content": "用一句话说明你的用途。"
      }
    ],
    "stream": false,
    "temperature": 1.0,
    "top_p": 0.95,
    "max_completion_tokens": 2048
  }'
```