腾讯混元接入需严格匹配协议类型：OpenAI兼容层用https://api.hunyuan.cloud.tencent.com/v1/和OpenAI格式API Key；Anthropic兼容层用https://api.hunyuan.cloud.tencent.com/anthropic和专用模型名；原生API用https://hunyuan.ai.tencentcloudapi.com及腾讯云签名鉴权。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
腾讯混元接入时需根据目标工具或开发框架的协议支持情况，匹配对应的 API 兼容层，否则会出现 400 错误、消息格式不识别、模型不可见等问题。
确认你用的客户端或 SDK 支持哪种协议
先看工具文档或源码里明确声明的兼容类型：OpenAI、Anthropic 或原生腾讯云 API（hunyuan.ai.tencentcloudapi.com）。比如 Cursor、Roo Code、LiteLLM 默认走 OpenAI 协议；Claude Code 或 Anthropic Python SDK 则只认 Anthropic 协议；而腾讯云官方 SDK 必须用原生域名和签名机制。
若不确定，打开终端执行 curl -v 抓包看请求头中是否含 anthropic-version 或 OpenAI-Organization ——前者指向 Anthropic 兼容层，后者是 OpenAI 兼容层。
按接入目标选对应协议与 endpoint
方法一：对接 OpenAI 生态工具（如 LiteLLM、CherryStudio、Open WebUI）
使用 OpenAI 兼容接口，base_url 填 https://api.hunyuan.cloud.tencent.com/v1/，API Key 从腾讯云控制台【创建 API KEY】获取（非 SecretId/SecretKey），模型 ID 如 hunyuan-turbo 或 hunyuan-pro 直接传入即可。
方法二：对接 Anthropic 生态工具（如 Claude Code、Anthropic Python SDK）
将 Claude Agent SDK 与 You.com HTTP MCP 服务器集成，支持 Python 和 TypeScript。当开发者提及 Claude Agent SDK、Anthropic Agent SDK 或将 Claude 与 MCP 工具集成时使用。
必须改用 Anthropic 兼容 endpoint：https://api.hunyuan.cloud.tencent.com/anthropic，且 model 参数只能填混元支持的 Anthropic 模型名，例如 hunyuan-2.0-thinking-20251109。注意：此处的 API Key 仍需在腾讯云控制台单独创建，与 OpenAI 兼容 KEY 不互通。
方法三：调用原生腾讯云 API（如通过 requests 手动签名）
endpoint 为 https://hunyuan.ai.tencentcloudapi.com，必须携带 X-TC-SecretId、X-TC-SecretKey、X-TC-Timestamp 等腾讯云标准鉴权头，Action 字段设为 TextGeneration 或 ChatCompletions，不支持 OpenAI 的 /chat/completions 路径。
避坑要点：协议混用会直接失败
第一步：检查你填的 base_url 和 API Key 类型是否匹配——OpenAI 兼容 KEY 绝不能配到 Anthropic endpoint 上，反之亦然。
第二步：确认模型 ID 是否存在于对应协议的可用列表中。OpenAI 兼容层不认 hunyuan-2.0-thinking-20251109，Anthropic 兼容层也不认 hunyuan-turbo。
第三步：若使用 LiteLLM，必须显式指定 --model 参数并带上 provider 前缀，例如 hunyuan/hunyuan-turbo，否则它会默认走 OpenAI 验证逻辑导致 400。
