MiniMax API 接入教程：Base URL、模型名与第一次调用（2026）

MiniMax 的文本模型提供 OpenAI 兼容接口，现有 OpenAI SDK 通常只需要改三处：Base URL、API Key、模型名。但真正接入时，容易卡在地区域名、模型名大小写、思考内容和 Token 参数上。本文按「地址—模型—调用—排错—迁移」的顺序，带你完成第一次调用。

先给结论：官方 OpenAI 兼容地址以 /v1 结尾，聊天端点是 /v1/chat/completions；模型名要与官方文档完全一致；新代码优先用 max_completion_tokens，并给思考内容留出输出预算。

说明：MiniMax 是其权利人的商标，本文仅作技术说明；模型名、接口、上下文与限额以 MiniMax 官方文档和站内模型价格为准。示例中的模型名请在控制台核对后再用于生产。

一、Base URL：先选对地区和协议

MiniMax 目前有中国站和国际站两套域名，另有 OpenAI 兼容、Anthropic 兼容和原生接口三种入口。最常见的选择是 OpenAI 兼容：国际站 https://api.minimax.io/v1，中国站 https://api.minimax.cn/v1，聊天端点是 POST /v1/chat/completions。

如果你用 Anthropic SDK 或 Claude Code 一类工具，官方推荐 Anthropic 兼容入口：国际站 https://api.minimax.io/anthropic，中国站 https://api.minimax.cn/anthropic，消息端点是 POST /anthropic/v1/messages。旧的原生接口 POST /v1/text/chatcompletion_v2 仍然存在，但新接入优先用兼容接口，参数和生态更统一。

场景	Base URL	典型端点
官方 OpenAI 兼容（国际站）	`https://api.minimax.io/v1`	`POST /v1/chat/completions`
官方 OpenAI 兼容（中国站）	`https://api.minimax.cn/v1`	`POST /v1/chat/completions`
官方 Anthropic 兼容（国际站）	`https://api.minimax.io/anthropic`	`POST /anthropic/v1/messages`
官方 Anthropic 兼容（中国站）	`https://api.minimax.cn/anthropic`	`POST /anthropic/v1/messages`
原生文本接口	`https://api.minimax.io` 或 `https://api.minimax.cn`	`POST /v1/text/chatcompletion_v2`
中商起航网关	`https://ai.zhongshangqihang.com/v1`	`POST /v1/chat/completions`

表格里的地址要和 Key 来自同一个平台。中国站的 Key 配国际站地址，通常直接 401；网关 Key 配官方地址，结果也一样。还有一种常见错误：Base URL 已经带了 /v1，请求路径又重复拼了一次，最终变成 /v1/v1/chat/completions。

二、模型名：大小写和版本都要对上

截至 2026 年 10 月，官方文档列出的当前文本模型是 MiniMax-M3.1-Flash 和 MiniMax-M3，上下文窗口为 1,000,000 tokens。MiniMax-M3.1-Flash 支持调节思考深度；MiniMax-M3 是同一代的多模态编码模型。

上一代模型仍在文档中列出：MiniMax-M2.7、MiniMax-M2.7-highspeed、MiniMax-M2.5、MiniMax-M2.5-highspeed、MiniMax-M2.1、MiniMax-M2.1-highspeed、MiniMax-M2，上下文为 204,800 tokens。另有 MiniMax-M2-her，上下文 64K。模型名区分大小写和连字符，复制时不要手打。

如果你走中商起航网关，模型名以模型价格页为准，可能和官方命名不同。代码里不要把模型名写死，放在环境变量或配置中心，切换时只改配置。

三、curl：先跑通一条非流式请求

准备环境变量 MINIMAX_API_KEY 放 Key。下面以中国站 OpenAI 兼容接口为例；国际站把域名换成 api.minimax.io，走网关则换成网关地址。先不要开流式，确认返回结构后再加。

export MINIMAX_API_KEY="你的密钥"

curl "https://api.minimax.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "用三句话解释什么是 Base URL。"}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

返回的 JSON 里，choices[0].message.content 是最终回答。使用 M3 系列时，思考内容通常在 reasoning_content 字段，content 只放最终答案。不要把两者混在一起展示，除非你的产品就是要展示思考过程。

如果走网关，把地址、Key 和模型名三处一起换掉。只换其中一处，通常会在 401 和 model not found 之间来回跳。

四、Python：用 OpenAI SDK 发起调用

安装 openai 后，用 base_url 指向 MiniMax 的兼容地址。下面示例把地址和模型都放在环境变量里，方便在官方与网关之间切换。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
)

stream = client.chat.completions.create(
    model=os.environ.get("MINIMAX_MODEL", "MiniMax-M3.1-Flash"),
    messages=[
        {"role": "system", "content": "你是一个简洁的中文助手。"},
        {"role": "user", "content": "写一个 Python 读取 CSV 并统计行数的例子。"},
    ],
    max_completion_tokens=1024,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="")
    if delta.content:
        print(delta.content, end="")

流式响应里，思考内容在 delta.reasoning_content，正文在 delta.content；stream_options.include_usage 设为 true 后，最后一个 chunk 会带上用量。不同 SDK 版本对未知字段的存放位置可能不同，读取前先在测试环境打印一次原始响应。

五、Token 与采样参数：别只改 max_tokens

新接入优先用 max_completion_tokens 控制输出长度；max_tokens 在官方文档中已标记为旧参数，仍可能兼容，但不要在新代码里依赖它。M3 系列的思考 token 也计入输出上限，上限设得太小会出现 finish_reason: "length" 且 content 为空。

常用参数：

temperature：控制随机性，可用范围以当前文档为准，超范围会报 400。
top_p：M3 系列默认 0.95，M2.x 默认 0.9；一般只调其中一个。
reasoning_effort：M3 系列支持 low、medium、high、xhigh、max，默认 max；调低可以降延迟和输出 token。
thinking：M3.1-Flash 强制开启思考，传 disabled 会报 400；其他模型的支持情况以文档为准。
n：只支持 1；presence_penalty、frequency_penalty 等参数可能被忽略。
工具调用：用 tools，不要用旧的 function_call；多轮工具调用要把完整的 assistant 消息，包括 tool_calls 和思考内容，带回历史。

如果延迟高，先降 reasoning_effort，再缩短输入和输出上限，不要一上来就换模型。思考型模型的质量和延迟通常是一起变化的，参数调对了，很多场景不需要换更小的模型。

六、常见报错：按状态码定位

401：Key 缺失、格式不对、Key 与站点或网关不匹配。检查 Authorization: Bearer 和 Base URL。
404：路径写错，或 Base URL 多了、少了 /v1。OpenAI 兼容地址以 /v1 结尾，再拼 /chat/completions。
model not found 或 model_not_found：模型名拼错、大小写不对，或账号没有该模型权限。从文档或价格页复制。
400：参数越界，例如 temperature 超范围、给 M3.1-Flash 传 thinking: disabled、reasoning_effort 传了不支持的值。
finish_reason: "length" 且内容为空：输出上限太小，思考 token 把预算用完。提高 max_completion_tokens。
429：触发限流。官方文档给出的参考是 M3 系列 200 RPM、10,000,000 TPM，M2.x 为 500 RPM、20,000,000 TPM；实际以账号和控制台为准。降并发、加退避重试。
5xx 或超时：上游波动或网络问题。设置超时、指数退避和备用模型，不要无限重试。

限流数字只是官方文档在 2026 年 10 月的参考值，不同账号、不同模型、不同接口可能不同。生产环境要以控制台和实际观测为准，不要照着文档数字把并发打满。

七、迁移检查清单

确认目标平台：官方中国站、官方国际站，还是中商起航网关。Key 和 Base URL 必须来自同一平台。
改 base_url：OpenAI 兼容用 /v1，Anthropic 兼容用 /anthropic，不要混用。
改模型名：从官方文档或模型价格复制，注意大小写、连字符和版本号。
改输出参数：优先 max_completion_tokens，给思考 token 留足预算。
检查流式解析：正文读 delta.content，思考读 delta.reasoning_content，不要假设只有一个字段。
检查工具调用：用 tools，并按官方要求回传完整的 assistant 消息和思考内容。
加超时、重试和熔断：对 429 和 5xx 做指数退避，设置单次请求超时。
加日志和用量监控：记录模型名、耗时、输入输出 token、错误码，日志里不要打印 Key。
灰度切换：先切一条低风险业务，对比质量和成本，再扩大流量。
准备回滚：保留旧配置和旧 Key 一段时间，确认稳定后再清理。

这份清单也适用于从 OpenAI 迁到 MiniMax，或从官方直连迁到网关。迁移的核心不是改一行 Base URL，而是把认证、模型、参数、流式解析和监控一起核对。

八、官方直连还是走网关

只接 MiniMax、用量稳定、能直接完成官方注册和结算，官方直连路径最短。需要同时接多个模型、统一账单、统一 Key，或者希望在国内网络环境里少维护几套配置，网关更合适。

选择网关时，重点确认四件事：支持哪些 MiniMax 模型、是否兼容你用的接口（OpenAI 或 Anthropic）、计费口径是否清楚、异常时的支持渠道。先小额测试，再放生产流量。可以到模型价格核对模型和计费，从注册入口创建测试 Key。

常见问题

MiniMax API 的 Base URL 是哪个？

国际站 OpenAI 兼容是 https://api.minimax.io/v1，中国站是 https://api.minimax.cn/v1。Anthropic 兼容分别用 https://api.minimax.io/anthropic 和 https://api.minimax.cn/anthropic。以你注册的站点为准。

MiniMax API 兼容 OpenAI SDK 吗？

兼容常用聊天接口。把 base_url 指向 MiniMax 的 /v1 地址，模型名换成 MiniMax 的模型名即可。但兼容不等于全部一致，思考字段、Token 参数和工具调用细节仍有差异。

为什么返回内容为空，finish_reason 是 length？

输出上限被思考 token 用完了。M3 系列会把思考计入输出预算，先把 max_completion_tokens 调大，再检查是否设置了过低的 max_tokens。

可以关闭思考吗？

MiniMax-M3.1-Flash 强制开启思考，传 thinking: disabled 会返回 400。其他模型是否支持关闭，以当前官方文档为准；想降延迟，优先调低 reasoning_effort。

从 OpenAI 迁移要改哪些地方？

至少改 Key、Base URL、模型名和输出参数；再检查流式字段、工具调用、超时重试和日志。建议先跑一条非流式 curl，再跑流式 Python，最后做灰度切换。

下一步

先选一个模型，用 curl 跑通非流式请求，再用 Python 跑流式；确认 content 和 reasoning_content 都能正确解析后，再接入业务。需要统一入口，可以注册中商起航 AI 网关，用模型价格页核对可用模型和计费。