只改三个参数，我把混元 Hy4 正式版接进了自己的代码

摘要：

腾讯混元大模型 Hy4 正式版于 2026 年 11 月 4 日发布，总参数 770B，首次引入视觉理解与电脑操作。开发者可通过大模型服务平台 TokenHub 用 OpenAI 兼容接口调用，仅需修改 base_url、api_key、model 三个参数，新用户可领 100 万免费 Tokens。

这篇是我把 Hy4 正式版接进自己项目后的完整记录：从这次升级到底改了什么，到怎么用 TokenHub 三个参数跑通第一个请求，再到接入时踩过的站点坑。如果你已经在用 OpenAI 兼容接口，照着做很快就能跑通。

一、混元 Hy4 正式版的核心升级点

说实话，我对"大版本升级"这类消息一向有点麻木。8 月底 Hy4 preview 出来时我就试过，这次正式版刚发布那几天，我也没急着动手。直到这周看到"混元大模型"的搜索热度在往上走，才索性坐下来把这次升级的材料完整读了一遍。

腾讯混元在 2026 年 11 月 4 日发布的 Hy4 正式版，几个关键信息我整理成一张表：

MoE 是"混合专家"架构的意思：模型总参数很大，但每次推理只激活其中一部分，所以 770B 的模型实际每次只调动 49B 参数在干活。

发布信息里让我多看了两眼的是这两条：幻觉率从 preview 版的 12.95% 降到 7.2%；游戏开发相关评测 GameDev 较 preview 提升 19.1%。幻觉率就是模型"一本正经说错话"的比例，做问答类业务的人对这个数字最敏感。

二、混元 Hy4 API 调用方法：三个参数即可跑通

我手上有个小工具，原来一直走 OpenAI 兼容协议调其他模型。这次切到 Hy4，我只做了三件事：在 TokenHub 控制台创建 API Key、开通 Hy4 模型服务、改代码里的三个值。

之前我给另一个项目换模型，光是对 SDK、改请求结构、调返回字段解析就折腾了一下午。这次 Python 代码一行业务逻辑都没碰。

改完的代码长这样：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",                        # TokenHub 控制台创建的 API Key
    base_url="https://tokenhub.tencentmaas.com/v1", # 广州地域接入地址
)

response = client.chat.completions.create(
    model="hy4",
    messages=[
        {"role": "user", "content": "用三句话解释什么是 MoE 架构"}
    ],
    stream=True,
)

for chunk in response:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

几个容易被问到的点：

• 协议：混元 Hy4 在 TokenHub 上同时支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种协议。
• 鉴权：OpenAI 兼容路径用请求头 Authorization: Bearer YOUR_API_KEY，Anthropic 路径用 x-api-key。
• 流式输出：输出较长时建议打开 stream，能避免长响应触发网关超时。

代码改到这里就结束了，但我更看重的其实是它背后的兼容性：TokenHub 兼容 OpenAI 和 Anthropic 两套标准协议，绝大多数支持自定义模型服务的 AI 编码工具都能用同样的思路接入。已有配置指引的工具包括 CodeBuddy Code、Claude Code、Codex、OpenCode、OpenClaw、Cursor、Cline、Roo Code、Kilo Code、WorkBuddy、Hermes Agent——服务地址指向 TokenHub 的 Base URL，模型名填 hy4 即可，Hy4 三种协议都支持，基本不用担心适配问题。

三、混元 Hy4 接入注意事项：站点匹配与旧接口迁移

不过，"只改三个参数"这个结论，是我排查完一个报错之后才真正确认的。第一次配完调用，我收到的其实是一个 401 鉴权错误，提示 API Key 无效。

我心里想：这不行啊，Key 是刚复制的。排查了一会儿才发现问题——TokenHub 广州站和新加坡站是相互独立的站点，API Key 不互通。我的 Key 在广州站创建，代码里却误填了新加坡的地址：

另一个容易碰到的是 402 类错误：模型服务没在控制台开通就直接调用，会返回 402，和模型支不支持该协议无关。所以这里给大家一个建议：先在控制台开通 混元 Hy4 模型服务，再确认 Key 的创建站点和代码里的 Base URL 是同一个。这两步做对，基本一次就通——只是希望后续报错信息能直接提示"站点不匹配"，能少走不少弯路。

还有一点给老用户：以前用过混元老接口（api.hunyuan.cloud.tencent.com）的朋友，腾讯混元大模型相关功能正在逐步迁移至 TokenHub，迁移后原平台不再新增模型能力、停止支持新购模型服务，已购买的服务可继续使用。换句话说，想用 Hy4 这类新模型，入口就是 TokenHub；好在两边都是 OpenAI 兼容协议，迁移基本就是换 base_url、换 API Key、换 model 名。过渡期两套入口并存，搜接入教程时留意一下别用错旧地址。

四、混元 Hy4 价格与免费额度

价格方面，Hy4 正式版与 preview 版保持一致，TokenHub 刊例价为每百万 Token 输入 6 元、输出 18 元、缓存命中 0.3 元。目前 Hy4 有限时优惠：至 2026 年 12 月 31 日，在线推理后付费调用按目录价 5 折结算，折后每百万 Token 输入 3 元、输出 9 元、缓存命中 0.15 元——像本文这样用 OpenAI SDK 调接口，实际就是按这个折后价扣费。新用户注册可领取 100 万 Tokens 免费体验额度。

五、总结

一句话评价：Hy4 正式版能力补上了视觉理解和电脑操作，接入方式又足够省事，值得自己动手跑一遍。

已经在用 OpenAI 兼容接口的老用户，直接换三个参数就能对比效果；第一次接触大模型 API 的朋友，先领免费额度，用上面那段 Python 代码跑通第一个请求就行。想动手试的话，可以从大模型服务平台 TokenHub 开始。