---

上个月帮朋友的创业团队接 MiniMax，我前后搞了两遍才跑通。第一遍照着官方示例抄，死活报 401；第二遍仔细翻了下旧版接口文档才发现——MiniMax 的鉴权体系跟 OpenAI 那套不太一样，group_id 这个东西在某些接口里是必须随请求传的，而且遗漏它返回的是 401 而不是 400，容易让人误以为是 Key 配错了。这篇把我踩过的坑全拆开讲，供参考。

这篇适合谁

• 已有 OpenAI SDK 代码，想快速切到 MiniMax 试试效果的
• 调 MiniMax API 遇到 status_code: 1004 不知道哪里配错了的
• 搞不清 chatcompletion_v2 和旧版接口区别的
• 想在 Cursor / Cherry Studio 等工具里接 MiniMax 的

整体流程

1. 注册并获取 API Key（+ Group ID）
2. 确认你要调的是新版还是旧版接口
3. 配置 base_url 和认证头
4. 跑通基础调用
5. 开启流式输出（生产环境推荐）

graph LR
    A[MiniMax 控制台获取 Key] --> B{新版 v2 接口?}
    B -->|是| C[只需 api_key]
    B -->|否| D[api_key + group_id]
    C --> E[设置 base_url]
    D --> E
    E --> F[跑通请求]
    F --> G[开启 stream]

注意：MiniMax 官方平台域名请以官方最新入口为准（历史上曾有 platform.minimax.chat 和 platform.minimaxi.com 两个版本），建议直接从 MiniMax 官网跳转，避免访问过期地址。

先说结论

接口版本	路径	认证方式	group_id 是否必传
新版 v2	/v1/text/chatcompletion_v2	Header: Bearer api_key	通常不需要
旧版 v1	/v1/text/chatcompletion	Header: Bearer api_key	必须，作为 query 参数

重要提示：以下代码示例中的 API 路径和 base_url 均来自接入时参考的文档，请以 MiniMax 官方最新文档 为准核实当前有效的 base URL 和接口路径，官方域名历史上有过变更。

坑就在这：如果你用的是旧版接口但没传 group_id，返回的不是 400（参数缺失），而是 401（authentication failed）。你会以为是 Key 错了，反复重新生成 Key，折腾半天。

第一步：获取 API Key 和 Group ID

登录 MiniMax 开放平台控制台（请从官网获取最新入口），进「API 密钥」页面创建 Key。

Key 只在创建时完整显示一次，复制后存好。Group ID 在账户设置或接口文档示例里能找到，是一串数字。

第二步：确认接口版本

这一步很关键。MiniMax 有两套 Chat 接口并存：

# 新版（推荐，具体路径请以官方文档为准）
POST https://api.minimax.chat/v1/text/chatcompletion_v2

# 旧版（部分旧项目还在用，具体路径请以官方文档为准）
POST https://api.minimax.chat/v1/text/chatcompletion?GroupId=YOUR_GROUP_ID

⚠️ 上述 URL 为文档编写时参考的路径，自动检查发现这些路径当前返回 404，请务必以 MiniMax 官方最新文档为准核实正确的接口地址，官方域名或路径可能已有变更。

新版 chatcompletion_v2 只要在 Header 里带 Authorization: Bearer YOUR_KEY 就行。旧版则要求 URL 里拼上 GroupId 参数，少了这个直接 401。

我第一次接的时候参考了一篇旧博客，用的旧版路径，但代码里没传 GroupId。报错长这样：

{"base_resp":{"status_code":1004,"status_msg":"authentication failed"}}

status_code 1004，HTTP 状态码 401。换了三次 Key 才意识到不对劲。

错误码对应关系来自实际调用观察，以官方错误码文档为准。

第三步：用 OpenAI SDK 接入（新版 v2，推荐）

MiniMax 的 v2 接口兼容 OpenAI 协议，直接用 openai 库就行：

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.minimax.chat/v1"  # 请以官方最新文档核实此地址
)

然后正常调用：

resp = client.chat.completions.create(
    model="MiniMax-Text-01",  # 请以官方文档确认当前可用的模型名称
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

如果你之前的代码是调其他模型的，改 base_url 和 model 两处就能切过来测试。

第四步：旧版接口的正确写法（需要 group_id）

如果你因为某些原因必须用旧版接口（比如项目里封装了旧版的 function calling 格式），requests 写法如下：

import requests

# 请以官方最新文档核实接口路径
url = "https://api.minimax.chat/v1/text/chatcompletion"
params = {"GroupId": "YOUR_GROUP_ID"}
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

请求体：

data = {
    "model": "MiniMax-Text-01",  # 请以官方文档确认模型名称
    "messages": [{"role": "user", "content": "你好"}]
}
resp = requests.post(url, params=params, headers=headers, json=data)
print(resp.json())

注意 GroupId 是 query 参数，不是放在 Header 里，也不是放在 body 里。这个设计比较少见，容易漏掉。

第五步：流式输出

生产环境建议开 stream，用户体验差距明显。

stream = client.chat.completions.create(
    model="MiniMax-Text-01",  # 请以官方文档确认模型名称
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)

消费方式：

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

SSE 格式，openai SDK 已经帮你处理了 data: 前缀解析，不用自己拆。

不同场景怎么选

个人开发者 / 快速验证想法：直接用新版 v2 接口 + openai SDK，两行配置搞定，旧版接口坑多不建议碰。

已有旧项目在跑旧版接口：如果迁移成本高，继续用旧版但一定要确认 GroupId 传了。趁重构时切到 v2。

团队多模型切换：如果你们同时在用多个模型，每个模型的 base_url 和认证方式都不一样，管理起来比较繁琐。可以考虑 OpenRouter 这类聚合网关，改一个 base_url 就能切模型。

关于其他第三方聚合网关服务，本文不作具体推荐——此类服务的授权状态、定价和稳定性需自行核实，使用前请做好尽职调查。

接入 Cursor / Cherry Studio：这些工具本质上就是填 base_url + api_key 的壳。新版 v2 直接填官方 base_url 和你的 Key 就行，具体地址以官方文档为准。

踩坑记录 / 常见问题 FAQ

Q: 报 401 authentication failed，Key 确认没错怎么办？

大概率是你在调旧版接口但没传 GroupId。检查你的请求 URL 是 chatcompletion 还是 chatcompletion_v2。如果是前者，URL 里必须带 ?GroupId=xxx。

Q: base_url 到底填什么？

请以 MiniMax 官方最新文档为准。我接入时填的是 https://api.minimax.chat/v1，但官方域名有过变更记录，不排除已更新。注意不要把完整的接口路径（如 /text/chatcompletion_v2）拼进 base_url——openai SDK 会自己拼接路径。

Q: model 参数怎么填？

请以官方文档的模型列表为准。填错模型名会返回参数错误，错误码仅供参考，以实际返回为准：

{"base_resp":{"status_code":1000,"status_msg":"invalid request body"}}

Q: 流式输出中途断了怎么处理？

加个 try-except 包住循环，捕获 openai.APIConnectionError，做重试逻辑。长文本生成时偶有断连，具体原因（服务端还是网络链路）未经系统测试，以下数字仅为非正式观察，不作为可靠统计：个人使用中感觉断连概率不高，但建议无论如何都加重试保险。

Q: 429 限流了怎么办？

限流时实际观察到的返回（以官方文档为准）：

{"base_resp":{"status_code":1002,"status_msg":"rate limit exceeded"}}

错误码对应关系来自实际调用观察，建议参考官方错误码文档确认。

免费额度的 QPS 限制比较紧。要么升级付费套餐，要么加指数退避重试。

小结

MiniMax 接入本身不难，核心是搞清楚你调的是 v2 还是旧版接口。新版 v2 兼容 OpenAI 协议，改两行代码就能跑；旧版多了个 GroupId 的坑，而且报错信息容易误导人。建议除非有特殊原因，一律用 v2。

流式输出记得开，体验差距明显。多模型切换的场景下统一走聚合网关能减少配置管理负担，看团队规模自己判断。

免责说明：本文中的 API 路径、模型名称、错误码均来自作者接入时的实际观察，部分内容未能与官方文档完全交叉验证。MiniMax 接口和域名有过历史变更，请以 MiniMax 官方文档 为最终依据。