腾讯混元 API 怎么接入？密钥申请与 SDK 调用
数据截至 2026-07，价格与限额以各官网为准。
先把这件事讲清楚：腾讯混元的接入路径现在正处在一个过渡期，老的混元控制台不再新增模型能力，新用户开新服务建议直接去 TokenHub；密钥拿到手之后，混元同时支持 OpenAI 兼容和 Anthropic 兼容两条端点，后者可以直接把 Claude Code 的请求指过去，这是它比较少被人提起的一个亮点。
如果你是第一次接混元 API，按下面这个顺序走一遍：先搞清楚该去哪个平台开通，再拿密钥，再挑一条兼容协议接进你的代码。三步顺序别打乱，尤其第一步，选错了平台后面容易白折腾。
第一步：先弄清楚该去老控制台还是 TokenHub
这是接混元最容易被忽略、但又最该先弄明白的一件事。腾讯云官方文档里反复出现同一条提示，原文是这么写的：
“为进一步提升大模型服务体验，腾讯混元大模型相关功能将逐步迁移至 TokenHub。迁移后，原平台将不再新增模型能力，并停止支持新购模型服务，但用户已购买的模型服务可继续使用，暂不受影响。如需开通新的模型服务或使用更多模型能力，请前往 TokenHub。”
翻译成人话就是：老的”混元大模型”控制台（也就是文档里 product/1729 这条线）正在被 TokenHub 替代。已经在老平台开通过服务的老用户不受影响，继续能用；但如果你是新用户，或者想开通新的模型能力，官方建议直接去 TokenHub，而不是继续按老教程走老控制台。
这一步之所以重要，是因为网上不少教程写得比较早，截图和路径还停留在老控制台，你如果照着搜到的老教程一路点下去，有可能发现某些模型能力已经开不了了，或者页面布局和教程对不上——这不是教程错了，是平台本身在迁移中。本文接下来讲的密钥申请、OpenAI 兼容端点、Anthropic 兼容端点，这几条能力在两边入口下都存在，但新用户建议优先走 TokenHub 那条路径去开通，遇到”开不了新模型”的情况，第一反应应该是去 TokenHub 看看而不是死磕老控制台。
这里再提一句容易搞混的地方：TokenHub 上还有一个专门面向 Coding Agent 的订阅套餐，叫 Hy Token Plan，分 Lite/Standard/Pro/Max 四档，官方写明适配 Claude Code、Cursor、Cline、Codex CLI、OpenCode、Kilo Code 这些编码工具。但这个套餐官方原文明确限制：“仅限在 AI 工具内使用，禁止以 API 形式用于自动化脚本、自定义应用后端或非交互式批量调用”。也就是说，如果你是想自己写代码调用混元的接口（本文讲的场景），Hy Token Plan 这套订阅制套餐不是给你用的，它是给编辑器工具内部消耗用量用的，价格体系也和下面要讲的按 token 后付费不是一回事。本文后面讲的密钥申请和调用方式，指的都是原生 API（按 token 后付费），不是 Hy Token Plan。两套东西名字都带”混元""Token”，写代码之前先分清楚自己要的是哪一套，免得开错服务。
第二步：拿密钥，注意有两种形态
不管走老控制台还是 TokenHub，拿密钥的大致路径是：登录腾讯云账号 → 找到”混元大模型”产品页 → 完成实名认证（个人用身份证，企业用营业执照）→ 进入”API Key 管理”页面 → 创建 API Key。
这里有个新手容易踩的坑：混元的密钥其实有两种形态，长得不一样，用途也不完全一样，别混用：
sk-开头的字符串：这是给 OpenAI 兼容接口和 Anthropic 兼容接口用的密钥，格式上跟你熟悉的 OpenAI/Anthropic 官方密钥长得很像，也是本文接下来重点讲的那种。- SecretId / SecretKey（云 API 密钥）：这是腾讯云体系里更通用的一套密钥，32 位大小写字母加数字组成，SecretKey 只在首次创建时展示一次。这套密钥主要用于走腾讯云传统的云 API 签名调用方式，跟
sk-那种直接塞进Authorization头的用法不是一回事。
如果你只是想用 OpenAI SDK 或者 Anthropic SDK 直接调用（也就是本文讲的这条路），记住去创建 sk- 开头的那种密钥，SecretId/SecretKey 那套不需要碰。这条提醒看着简单，但确实是新手在控制台里最容易点错、创建出一个用不上的密钥类型的地方。
另外一个通用提醒，不只针对混元：密钥展示的窗口往往就那一次，关掉弹窗前一定当场复制存进密码管理器；密钥别直接写进代码里提交到 Git 仓库，放到环境变量里读取更稳妥，换密钥时也不用改代码。
第三步：OpenAI 兼容端点，用官方 openai 包直接调
混元的第一条兼容协议是 OpenAI 兼容。这意味着你不需要装什么混元专属 SDK，直接用官方的 openai 这个 Python 包（或对应语言的 OpenAI SDK），换两个参数就能跑：
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("HUNYUAN_API_KEY"),
base_url="https://api.hunyuan.cloud.tencent.com/v1",
)
completion = client.chat.completions.create(
model="hunyuan-turbos-latest",
messages=[{"role": "user", "content": "Say this is a test."}],
)
print(completion.choices[0].message.content)
完整的请求路径是 https://api.hunyuan.cloud.tencent.com/v1/chat/completions，但你不用自己拼这段，SDK 会在 base_url 后面自动加上标准的 /chat/completions 路径，你只管把 base_url 填成上面这串地址就行。api_key 从环境变量 HUNYUAN_API_KEY 读，跑之前记得先在环境里 export 好。
有两个跟标准 OpenAI 接口不完全一样的细节，官方文档里专门提了一句，值得留意：第一，调用 OpenAI 官方接口时如果指定了 stop 参数，模型会停在匹配内容之前；但混元这边的行为是停在匹配内容之后，如果你的代码里对截断位置有精确依赖（比如靠 stop 做结构化提取），迁移过来要重新测一下这个边界行为，别想当然照搬 OpenAI 那边的假设。第二，Embedding 接口目前只支持 input 和 model 两个参数，model 固定填 hunyuan-embedding，dimensions 固定是 1024，不支持像某些服务那样自定义降维。
顺带说一句实操建议：第一次跑通之前，先用 curl 单独测一下密钥和网络通不通，比直接在项目代码里排查快得多。调不通通常就三种可能——密钥没读到、base_url 拼错、或者本地网络访问不了这个域名，curl 能最快帮你把这三种情况区分开。
第四步：Anthropic 兼容端点，能直接接 Claude Code
这是混元这套接入体系里比较容易被忽略、但实际很实用的一个能力：除了 OpenAI 兼容，混元原生 API 还提供一条 Anthropic 兼容端点，认证方式、请求格式都跟 Anthropic 官方 API 对齐。
地址是：
base_url: https://api.hunyuan.cloud.tencent.com/anthropic
完整请求路径是 https://api.hunyuan.cloud.tencent.com/anthropic/v1/messages，认证方式是 x-api-key 请求头传密钥，跟 Anthropic 官方的认证习惯一致（不是 OpenAI 那种 Authorization: Bearer 的写法）。请求体需要指定 model（官方示例用的是 hunyuan-2.0-thinking-20251109）、max_tokens、stream，也可以带 system 和 messages 字段。如果你用流式调用，返回的事件类型也跟 Anthropic 官方一致：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop，这几个事件名字如果你之前用过 Anthropic 官方 SDK 应该很眼熟，处理逻辑基本能照搬。
这个端点最实用的一个用法，是官方文档专门写了一节”通过 Claude Code 接入使用”：装好 Claude Code 之后，改一下配置文件里的 base_url 和密钥，执行 claude 命令，就能把 Claude Code 原本发给 Anthropic 官方的请求改指向混元。这跟前面提到的 Hy Token Plan 不是一回事——Hy Token Plan 是 TokenHub 上的订阅套餐，走的是套餐额度，且官方明确限制只能在工具内用；而这里说的 Anthropic 兼容端点是原生 API 的能力，本质上还是按 token 后付费调用，只是刚好协议格式跟 Anthropic 官方对齐，所以能让 Claude Code 这类原生支持 Anthropic 协议的工具直接切换过来。如果你想要的是”用混元省钱跑 Claude Code”，这条 Anthropic 兼容端点是更直接的路径，不用绕去套餐订阅那条线。
要不要用这条 Anthropic 兼容端点，取决于你现有的代码栈：如果你的项目本来就在用 Anthropic 官方 SDK 或者 Claude Code，直接换 base_url 和密钥迁移成本最低；如果你的项目一直用的是 OpenAI SDK 生态，走前面讲的 OpenAI 兼容端点会更顺手，两条路选一条对口的就行，不用两个都接。
常见坑 / 注意
- 别用老教程照抄的路径开新服务：官方明确说老控制台不再新增模型能力，新用户/新模型建议走 TokenHub，遇到”开不了”先查是不是走错了平台。
- 别把 Hy Token Plan 和原生 API 搞混：Hy Token Plan 是 TokenHub 面向编码工具的订阅套餐，官方限制”禁止以 API 形式用于自动化脚本”；本文讲的密钥申请、OpenAI/Anthropic 兼容端点，都是原生 API 按 token 后付费的路线，两套体系价格和使用限制都不一样。
- 密钥别选错类型：要接 SDK 直接调用，创建
sk-开头的密钥；SecretId/SecretKey 是给腾讯云传统签名调用方式用的，两者别混用。 stop参数截断位置和 OpenAI 官方不一样：混元是停在匹配内容之后，OpenAI 官方是停在之前，有精确依赖的代码迁移过来要重新验证。- Anthropic 兼容端点认证用
x-api-key：不是 OpenAI 那种Authorization: Bearer写法，接错头会直接鉴权失败。 - 密钥只显示一次：当场复制存好，别关了弹窗才想起来。