MiniMax Agent GroupID新手配置指南

MiniMax Agent API调用需先判断接口版本：v1接口必须传Group ID，v2接口通常无需；Group ID仅在控制台API密钥详情页显示为纯数字，旧版需通过URL参数或X-Group-ID请求头传递，漏传将返回401；可用OpenAI SDK兼容模式自动适配v2接口。

刚拿到MiniMax Agent的API密钥，却卡在Group ID配置这一步——控制台没找到入口、文档写得模糊、请求总返回401，根本跑不通基础调用。

确认是否需要Group ID

先别急着去控制台翻 Group ID，第一步更应该看清楚自己调用的是哪条 API 路径：

，那 Group ID 就是必传项；，那在绝大多数场景里其实不需要再带 Group ID，直接用 api_key 做鉴权就够了。

这个判断直接决定后续所有操作方向。错判版本，后面填再多次Group ID也没用。

从控制台准确提取Group ID

登录MiniMax开放平台控制台（务必通过正式跳转，避免访问platform.minimax.chat等已过期域名）→ 进入「API密钥」管理页 → 找到你刚创建的Key条目 → 点击右侧「查看详情」。

Group ID就显示在弹窗里，是一串纯数字，不是UUID也不是字母混合字符串。

。如果弹窗里没看到，说明你创建的是v2专用密钥，该密钥默认绑定v2接口，不需要Group ID。

旧版接口中正确携带Group ID

方法一：直接把它当作 query 参数，追加到 URL 末尾
也就是把https://api.minimax.chat/v1/text/chatcompletion改成：https://api.minimax.chat/v1/text/chatcompletion?group_id=123456789，这里的123456789需要替换成你从控制台复制出来的真实 ID。

方法二：放在请求头里（部分SDK支持）
Header中增加X-Group-ID: 123456789。注意不是Authorization头，也不是Bearer格式。

⚠️关键提醒：旧版接口若漏传Group ID，服务器返回401而非400，极易误判为api_key错误。反复重生成Key只会浪费时间。

用OpenAI SDK兼容模式绕过Group ID

第一步：安装最新版openai包（≥1.45.0）
pip install --upgrade openai

第二步：初始化客户端时指定base_url和default_headers

from openai import OpenAI
client = OpenAI(
  api_key="your_api_key_here",
  base_url="https://api.minimax.chat/v1",
  default_headers={"X-Group-ID": "123456789"}
)

第三步：调用chat.completions.create时路径自动补全为/v1/text/chatcompletion_v2，此时Group ID被忽略，仅用于v1兼容兜底。这样既适配现有OpenAI代码，又避开v1的Group ID陷阱。