必须显式配置GroupID仅适用于MiniMax旧版接口或非OpenAI兼容服务，新版v2接口已取消该参数；若Agent调试页cURL含X-Group-ID或文档要求传入，则需通过application.yml、环境变量或HTTP Header三种方式注入，并确保值准确无空格。

要在Java项目中正确配置MiniMax Agent所需的GroupID，必须明确它只在旧版接口或特定模型调用路径中生效，新版v2兼容接口已取消该参数依赖——但若你正在对接Agent实例、语音合成或非OpenAI兼容的底层服务，GroupID仍需显式传入，漏填会导致401认证失败而非400参数错误。

确认是否需要 GroupID

打开MiniMax控制台 → 进入「Agent」模块 → 点击已创建的Agent实例 → 查看「调试信息」或API文档说明页。如果文档中请求示例含 ?GroupId=grp_xxx 或要求Header中携带 X-Group-ID，则必须配置；若调用路径为 /v1/chat/completions 且使用 OpenAI 兼容模式，则【GroupID 不参与鉴权，填了反而可能触发校验失败】。

注意：Agent调试页自动生成的cURL命令里若出现 -H "X-Group-ID: grp_..." ，说明当前Agent绑定的是旧版接口体系，必须传。

获取 GroupID 的准确位置

登录 platform.minimax.chat → 右上角头像 → 「账户中心」→ 左侧菜单「组织管理」→ 页面中部找到「Group ID」字段（格式为 grp_ 开头的32位字符串）→ 复制保存。

不要从「API密钥」页找——那里只显示API Key，不显示Group ID；也不要复制「Account ID」，二者不同。

Java项目中注入 GroupID 的三种方式

方法一：通过 application.yml 配置（推荐用于Spring Boot）

在 application.yml 中添加：

minimax:
api-key: your_api_key_here
group-id: grp_abc123def456ghi789jkl012mno345
base-url: https://api.minimax.chat

这一步必须确保 group-id 字段名与后续代码中 @Value("${minimax.group-id}") 读取的key完全一致，大小写敏感。

方法二：环境变量注入（生产环境更安全）

启动JVM时设置：

-Dminimax.group-id=grp_abc123def456ghi789jkl012mno345

代码中用 @Value("${minimax.group-id}") 获取即可，无需硬编码，也避免密钥泄露风险。

方法三：手动构造HTTP Header（适用于OkHttp/HttpClient直连）

第一步：构建请求时，在Header中显式添加

headers.add("X-Group-ID", groupId)

第二步：确保该Header在Authorization之前设置完毕，否则部分网关会因顺序问题拒绝请求。

第三步：若使用RestTemplate，需在HttpHeaders对象中put进"X-Group-ID"，再封装进HttpEntity；若用WebClient，用.header("X-Group-ID", groupId)链式调用。

验证 GroupID 是否生效

① 启动项目后，在日志中搜索“grp_”字符串，确认配置值被成功加载；

② 发起一次Agent调用，抓包检查实际发出的HTTP请求中是否包含 X-Group-ID Header 或 URL query 中是否有 GroupId=；

③ 若返回仍是401且status_msg含“Authentication failed”，立刻检查Group ID是否复制完整——【少一位字符或混入空格都会导致认证失败】；

④ 用Postman复现相同请求，对比Java代码生成的Header与Postman手动设置是否完全一致。