腾讯混元本地调用失败主因是API路径错配：控制台用TokenHub（Bearer Token），而项目误用旧SDK（CAM密钥）。需确认URL、请求头、SDK包是否属同一套体系，并检查Token绑定子账号、endpoint格式及LiteLLM兼容性问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
腾讯混元模型在控制台能正常调用、返回结果，但本地项目发起请求却持续失败——这种情况不是模型没开，而是鉴权、路由或协议层存在隐性错配，必须逐层排查。
先确认你用的是哪套接口体系
腾讯混元目前存在两套并行的 API 接入路径：传统腾讯云 SDK 接口（CAM 密钥体系）和 TokenHub OpenAI 兼容接口（Bearer Token 体系）。【两者密钥完全不通用，endpoint 域名、认证头、参数结构全部不同】。控制台默认走的是 TokenHub 路径，而你的项目代码很可能还在用老 SDK 的 CAM 方式调用，这是最常见的一击必中原因。
打开你项目的配置文件或初始化代码，检查是否出现以下任一特征：
- 请求 URL 包含
tencentcloudapi.com或hunyuan.tencentcloudapi.com - 请求头中含
X-TC-SecretId、X-TC-SecretKey等字段 - 使用了
TencentCloud.Hunyuan或TencentCloud.CommonSDK 包
只要命中任意一条，说明你正试图用旧协议连新服务，立刻切换到 TokenHub 路径。
验证 TokenHub API Key 是否有效且未被绑定子账号
第一步：访问 TokenHub 控制台 →「API Key 管理」→ 找到你正在使用的 Key，确认状态为「启用」。
第二步：点击该 Key 右侧「查看详情」，检查「绑定子账号」字段是否为空。如果显示某个子账号 ID，【该 Key 将无法被主账号或其他子账号调用，且错误码固定为 403，不会提示具体原因】。
第三步：用 curl 快速验签（替换 YOUR_TOKEN 和 YOUR_ASSISTANT_ID）：
curl -X GET "https://open.hunyuan.tencent.com/openapi/v1/agent/verify?assistant_id=YOUR_ASSISTANT_ID" -H "Authorization: Bearer YOUR_TOKEN"
返回 200 表示 Key 有效；返回 401 说明 Bearer 后少空格或 Token 错误；返回 403 且 assistant_id 确认无误，则大概率是子账号绑定问题，需删除重建 Key。
检查项目中的 endpoint 和请求头格式
方法一：直连 TokenHub OpenAI 兼容接口（推荐）
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
将请求 URL 改为 https://api.hunyuan.cloud.tencent.com/v1/chat/completions，不要用 open.hunyuan.tencent.com 或 hunyuan.tencentcloudapi.com。
请求头必须严格设置为：Authorization: Bearer YOUR_TOKEN_HERE —— 注意Bearer 和 Token 之间是一个英文半角空格，不能是中文空格、制表符或换行。
方法二：若必须走腾讯云 SDK 路径
则需确保已开通「混元大模型」服务（非 TokenHub），且 API 密钥来自「API 密钥管理」页而非 TokenHub。此时 endpoint 应为 https://hunyuan.tencentcloudapi.com，Region 固定填 ap-guangzhou，并启用 HttpProfile.ReqMethod = POST 与 ContentType = application/json; charset=utf-8，否则返回 400。
排查 LiteLLM 或 AI 工具代理层的兼容性陷阱
第一步：确认你是否在 Roo Code、Cursor 或 WorkBuddy 中通过 LiteLLM 代理接入混元
这类工具生成的 messages 数组常以 assistant 角色结尾，而混元强制要求最后一条消息必须是 user 或 tool。LiteLLM 默认不重写 message 序列，会导致 400 错误。
第二步：在 LiteLLM 配置中启用 message rewrite 插件或手动补一条空 user 消息
例如，在请求体末尾追加：{"role": "user", "content": ""}，即可绕过校验。这一步不可省略，否则所有带工具调用的对话都会中断。
第三步：移除 OpenAI 特有字段
检查 payload 中是否含 parallel_tool_calls、reasoning_effort、function.strict 等字段。混元会直接拒绝含这些字段的请求，删掉再试。
