MiniMax API 接入教程：endpoint 路径与 group_id 传参变动，踩坑 401 看这篇

发布时间：2026/6/27 9:23:04

上周我们项目要把对话模块从 MiniMax 旧版模型切到新版老板说社区评价性价比不错。我心想直接把旧配置 copy 过来改个 model 名不就行了结果一跑直接 401{status_code: 1004, status_msg: Authentication failed, please check your api key}折腾了大半天才发现新版接口在group_id的传参位置和 chat endpoint 路径上有两处变动直接复用旧配置必挂。这篇把坑全标出来15 分钟跑通。这篇适合谁之前用过 MiniMax 旧版模型abab6.5s 等现在要切到新版接口的开发者第一次接 MiniMax API想一步到位用新版接口的用 OpenAI SDK 兼容模式接入改个 base_url 就想跑通的团队里有人报 1004 / 401 错误排查了半天没头绪的整体流程注册 MiniMax 开放平台拿到 API Key确认你要调的 endpoint 版本新版 v2 兼容接口还是旧版 v1这是关键分叉点配置鉴权头新版接口的 group_id 放哪里跟旧版不一样发起第一次调用验证返回可选接入聚合网关统一管理多模型先说结论新旧接口的两处配置差异配置项旧版 v1 接口abab 系列新版 v2 兼容接口endpoint 路径/v1/text/chatcompletion?GroupIdxxx/v1/chat/completionsgroup_id 传参位置URL query 参数不需要传Bearer Token 已绑定组织鉴权头Authorization: Bearer {key}Authorization: Bearer {key}相同model 字段示例abab6.5s/abab5.5以控制台模型列表页为准说明旧版 endpoint 路径格式可参考官方文档核实新版 OpenAI 兼容接口的实际路径为/v1/chat/completions以platform.minimax.chat官方文档为准。重点就两个endpoint 路径变了group_id 不再需要拼在 URL 里。如果你的 Key 本身配置有问题会直接返回 1004。第一步拿到 API Key登录platform.minimax.chat进「API Keys」页面生成一个。新版 v2 接口不需要传 GroupId鉴权信息已通过 Bearer Token 绑定到你的账户。第二步确认 endpoint 路径新版 OpenAI 兼容接口完整 URLPOST https://api.minimax.chat/v1/chat/completions旧版路径是/v1/text/chatcompletion需要 GroupId 拼在 URL 里两者不要混用。以官方文档为准如路径有变动请以platform.minimax.chat文档页为准。第三步配置鉴权头headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json }就这样不需要传 GroupId。旧版那个?GroupIdxxx在新版接口里已经废弃。第四步发起调用以下三段代码需要连续运行第二、三段依赖前面定义的变量import requests headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } # 请将 model 名称替换为控制台模型列表页中的实际 ID data { model: YOUR_MODEL_ID, messages: [{role: user, content: 你好}] } resp requests.post( https://api.minimax.chat/v1/chat/completions, headersheaders, jsondata ) print(resp.json())正常返回就说明跑通了。如果返回 1004往下看 FAQ。关于 model ID请登录platform.minimax.chat控制台在模型列表页查看当前可用的模型 ID直接填写控制台显示的名称不要依赖第三方文章中的名称。第五步可选用 OpenAI SDK 兼容模式MiniMax 的新版接口兼容 OpenAI SDK 协议已有 OpenAI 代码改两行就能切from openai import OpenAI client OpenAI( api_keyYOUR_MINIMAX_KEY, base_urlhttps://api.minimax.chat/v1 ) # 请将 model 名称替换为控制台模型列表页中的实际 ID resp client.chat.completions.create( modelYOUR_MODEL_ID, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)这个方式代码改动量最小。如果你同时还在用其他厂商的模型代码结构完全一样只需要换base_url和model名。说到多模型管理如果你团队同时用 MiniMax Claude GPT每个厂商单独管 Key 挺烦人的。聚合 API 可以选 OpenRouter、ofox.io 这类改个base_url就能切不同模型团队后台能看到每个人调了哪些模型、花了多少钱。使用聚合平台时请在对应平台的模型列表页确认实际可用的 model ID不同平台的 ID 命名可能与原厂不同。流式输出配置如果你需要打字机效果加个stream: True。注意 SSE 响应每行以data:开头需要去掉前缀再解析最后一行是data: [DONE]import requests import json url https://api.minimax.chat/v1/chat/completions headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } data { model: YOUR_MODEL_ID, messages: [{role: user, content: 你好}], stream: True } with requests.post(url, headersheaders, jsondata, streamTrue) as r: for line in r.iter_lines(): if line: decoded line.decode() if decoded.startswith(data: ): payload decoded[len(data: ):] if payload [DONE]: break chunk json.loads(payload) # 根据实际返回结构取 delta 内容 print(chunk)不同场景怎么选个人开发者 / 快速验证直接用 requests 新版接口代码量少不用装额外依赖。已有 OpenAI 项目要迁移用 OpenAI SDK 兼容模式改base_url和model就行代码改动量最小。团队多人协作 / 多模型混用建议走聚合网关统一管理 Key 和用量。多个工程师各自申请各厂商的 Key月底对账是噩梦。需要旧版模型abab6.5s 等旧版模型仍然走/v1/text/chatcompletion?GroupIdxxx路径不要与新版接口混用。确认你调的模型名对应哪个 endpoint 版本。价格参考⚠️ 以下价格仅供参考随时可能变动且美元/人民币换算依赖汇率请以platform.minimax.chat官方定价页为准。模型输入价格输出价格新版模型以控制台为准请查阅官方定价页请查阅官方定价页abab6.5s¥0.1/M tokens¥0.1/M tokensabab5.5¥0.015/M tokens¥0.015/M tokens如果你的场景是长输出写文章、代码生成输出 token 的成本会比短回答场景高不少建议在官方定价页核算实际成本。常见问题 FAQQ: 返回 1004 Authentication failed 怎么排查三步走①确认 Header 格式是Bearer key不是Bearer: key多了冒号就挂②确认 Key 没过期去控制台看状态③确认账户有余额。余额为 0 时报错信息有时仍显示 authentication failed容易误导排查方向。Q: 我用旧版 endpoint 加了 GroupId 为什么也报错如果你调的是新版接口但 URL 里拼了 GroupId接口本身不会因为多了这个参数而报错——但如果你同时把 model 写成了旧版模型名比如abab6.5s新版接口不认这个 model会返回{status_code: 1002, status_msg: Invalid parameter}新旧接口对应不同的 model 名称请在控制台模型列表页确认当前接口支持的 model ID。Q: OpenAI SDK 模式下报 401 Invalid API key 怎么办openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}这个报错说明 SDK 确实连上了 MiniMax 的服务器不是网络问题但 Key 不对。检查你是不是把其他厂商的 Key 填进去了。Q: 怎么查看当前可用的模型列表登录platform.minimax.chat控制台在模型列表页查看所有可用模型及其对应的 model ID。以控制台为准不要依赖第三方文章中的名称。Q: 社区里看到的模型昵称和官方 API 里的 model ID 对不上怎么办社区讨论中常出现各种非官方昵称与官方 API 的 model ID 不一定有明确对应关系。建议直接以platform.minimax.chat的模型列表页为准填写控制台显示的 model ID不要猜名字。小结整个接入过程不复杂核心就是别把旧版配置直接搬过来。记住两点新版接口走/v1/chat/completionsgroup_id 不用传。model ID 以控制台模型列表页为准这是最容易踩坑的地方。