接入腾讯混元大模型必须按通道类型匹配协议、认证与请求结构：OpenAI兼容接口用TokenHub密钥和/v1路径，原生API用CAM密钥和hunyuan.tencentcloudapi.com，Anthropic接口用TokenHub密钥和/anthropic路径，三者字段、鉴权、model名称均不可混用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
将腾讯混元大模型接入已有项目时，必须替换原有模型的通信协议、认证方式与请求结构，否则请求会因签名失败、路由错误或字段不兼容而被直接拒绝。
确认当前项目调用的是哪类接口规范
先检查你项目中已有的大模型调用代码或配置文件：若使用 OpenAI SDK（如 openai==1.0+）或直调 /v1/chat/completions 路径，说明走的是 OpenAI 兼容接口；若调用的是 https://hunyuan.tencentcloudapi.com/ 且带 X-TC-Action 请求头，则是原生腾讯云 API 3.0 接口；若使用 Anthropic SDK 并设置 ANTHROPIC_BASE_URL，则需对接 Anthropic 兼容层。这三者配置路径、鉴权逻辑、参数字段完全不同，不能混用。
混元官方同时提供三种接入通道：OpenAI 兼容接口（通过 TokenHub）、原生腾讯云 API 3.0（需 CAM 密钥）、Anthropic 兼容接口（api.hunyuan.cloud.tencent.com/anthropic）。选错通道会导致 401 或 404 错误，且错误信息不明确。
OpenAI 兼容接口配置替换（最常用）
方法一：修改环境变量与初始化参数
将原项目中 OPENAI_API_KEY 的值替换为从 腾讯云 TokenHub 控制台 创建的 API Key；把 OPENAI_BASE_URL 改为 https://api.hunyuan.cloud.tencent.com/v1/。注意末尾斜杠不可省略，否则部分 SDK 会拼接出错路径。
方法二：硬编码客户端（仅限测试）
在 Python 中，若原用 client = OpenAI()，改为：client = OpenAI(base_url="https://api.hunyuan.cloud.tencent.com/v1/", api_key="your_tokenhub_api_key")。这一步必须同步更新 model 名称——原用 gpt-4o 的地方，要换成混元实际支持的型号，例如 hunyuan-2.0-instruct-20251111 或 hunyuan-pro，否则返回 404。
【model 字段必须显式指定，且必须与 TokenHub 后台开通的模型权限一致】。TokenHub 控制台创建 API Key 时若未勾选对应模型，即使请求发出去也会被拦截，错误码为 403。
原生腾讯云 API 3.0 接入配置
第一步：安装并导入腾讯云 SDK
pip install tencentcloud-sdk-python → 确保版本 ≥ 3.0.1129，旧版本不支持 hunyuan 模块。
第二步：替换密钥与地域
将原项目中的 SecretId 和 SecretKey 替换为腾讯云 CAM 控制台生成的子账号密钥（主账号密钥禁止用于生产）；地域参数必须设为 "ap-guangzhou"，其他地域如 ap-beijing 当前不提供混元服务，会返回 InvalidRegion 错误。
复杂任务工程化执行框架 — Sprint Contract 协商、三代理角色切换、对抗性评估、任务分解与上下文管理。3+ 文件修改或多模块设计时自动触发，防止复杂任务中的上下文污染和自我评估偏差。
第三步：重写请求构造逻辑
原 OpenAI 风格的 JSON body（含 messages 字段）需彻底重构：混元原生 API 使用 Input + ChatInput 结构，system prompt 必须放在 Input.ChatInput.System，用户消息放在 Input.ChatInput.Messages 数组中，且每条消息必须带 Role（"user" 或 "assistant"）和 Content 字段。漏掉 Role 或大小写错误（如写成 "User"）将导致 400 报错。
Anthropic 兼容接口配置
若项目已基于 Claude SDK 构建 Agent 工作流，只需两处变更：
① 将 ANTHROPIC_BASE_URL 环境变量设为 https://api.hunyuan.cloud.tencent.com/anthropic；
② 将 ANTHROPIC_AUTH_TOKEN 设为 TokenHub 获取的 API Key（不是 CAM 密钥）；
③ 在 messages.create() 调用中，model 参数必须使用混元 Anthropic 兼容列表中的型号，例如 hunyuan-2.0-thinking-20251109。该型号不支持 OpenAI 的 functions 字段，但支持 thinking 字段（值为 {"type": "enabled"}），用于触发深度推理路径。
注意：Anthropic 接口不接受 temperature 超过 1.0 的值，设为 1.2 会直接返回 422 错误。
关键配置项核对清单
1. 请求域名是否匹配所选通道：OpenAI 通道用 api.hunyuan.cloud.tencent.com/v1，Anthropic 通道用 api.hunyuan.cloud.tencent.com/anthropic，原生 API 用 hunyuan.tencentcloudapi.com；
2. 认证凭据类型是否匹配：TokenHub API Key 仅适用于 OpenAI/Anthropic 通道，CAM SecretId/SecretKey 仅适用于原生 API 通道；
3. model 名称是否在对应通道的可用列表中：TokenHub 后台开通的模型权限、OpenRouter 上展示的型号、腾讯云控制台混元服务页列出的型号，三者范围不完全重叠；
4. 请求体结构是否按通道规范重写：OpenAI 通道保留 messages 数组，Anthropic 通道必须用 messages + system 字段，原生 API 通道必须用嵌套的 Input.ChatInput 结构。
