接 Hy4 要改几处？三个参数、五步与三个坑

把大模型接进自己的脚本，卡点常常不在模型笨，而在第一行调用：地址填错、鉴权头写错、model 名多带一个前缀，接口就甩回看不懂的错误码。腾讯混元 Hy4 正式版于 2026 年 11 月 4 日上线，官方文档给出的路径很短：同一份 OpenAI 或 Anthropic SDK 代码，通常只要替换 Base URL、API Key 与 model 三个参数就能跑。但"通常"背后藏着地域站点、协议路径、命名、能力差异、错误码和流式报错，一处没对上就停摆。

先划清边界，免得和站内其他文章撞角度。本篇只管把 Hy4 正式版 API 接进工作流，不含账单核算（单价幻觉、缓存计价、跨渠道对账见《大模型 API 定价横评》）、发布事件（见《腾讯 Hy4 正式版发布》与 8 月 28 日《Hy4 preview 开源发布》两篇热点）、多模型看图选型（见本批《多模型视觉输入横评》）。最需要点明的是：Hy4 正式版的模型权重尚未开源，官方称将于近期开源权重并发布系统卡片，所以本篇只讲托管 API 接入，不涉及本地部署 Hy4 正式版；站内《Hy4 preview 自部署 SOP》讲的是上一代 hy4-preview 权重用 vLLM、SGLang 自部署，是另一条路。全文按五步展开，之后单列三个坑与三套价格，日期一律写绝对日期，命令与字段以腾讯云官方文档和 2026 年 11 月 4 日发布口径为准。

先看全局：一个入口、三处参数、两条协议族

腾讯云把 Hy4 放在 TokenHub 统一入口后：OpenAI 或 Anthropic 风格的请求都先打到同一个 Base URL，由 TokenHub 按路径分发协议实现，鉴权也在这一层统一做，你保留原客户端、只改三个值。三处参数各管一段：Base URL 定地域与协议入口，API Key 定鉴权，model 定落到哪个模型。三条协议路径挂在同一 Base URL 下：/v1/chat/completions 走 OpenAI Chat Completions，覆盖全部模型、最通用；/v1/responses 走 OpenAI Responses，支持模型有限；/v1/messages 走 Anthropic Messages。认证头随协议族走，OpenAI 两条路径用 Authorization: Bearer YOUR_API_KEY，Anthropic 用 x-api-key: YOUR_API_KEY；YOUR_API_KEY 只是占位符说明，真实脚本用环境变量注入，别把密钥写进源码。先记一条红线：TokenHub 上的模型名是 hy4，OpenRouter 上的 id 是 tencent/hy4，两套命名不能互抄。理解这一层收敛，后面几个坑几乎都能提前预判：鉴权、命名与能力支持度都被收口到统一入口，任何一处按原生 SDK 的习惯去套都会对不上，差异正是从这里长出来的。

第一步：拿钥匙、开模型，402 从哪来

在腾讯云 TokenHub 控制台做两件事：创建 API Key，开通 Hy4 模型服务。顺序别反，也别只做一半。很多人拿到 Key 就发请求，收到 402 却误以为是鉴权或参数写错，其实是服务没开通：官方文档明确 402 与协议无关，OpenAI 路径、Anthropic 路径都会返回，未开通模型或额度不足时调用落到 402xxx 这一族。开通后用只读请求 GET /v1/models 确认在线列表，带同样鉴权头即可，官方示例响应含 {"id":"hy4","status":"online"}，其中 id 就是第二步要填的 model 值，status 为 online 才可调。养成先看列表再填 model 的习惯，比照记忆里的字符串硬写稳妥得多，也能顺带确认所在站点到底开通了哪些模型、以及你关心的名字是否真的存在。响应结构示意如下：

{
  "data": [
    {"id": "hy4", "status": "online"},
    {"id": "hy4-preview", "status": "online"}
  ]
}

还有一件几乎人人撞一次的事：广州站点与新加坡站点相互独立，各有各的 API Key，广州建的 Key 不能拿去新加坡站点用，反过来也一样。第一步建 Key 时就按地域定好，别等配 Base URL 才发现钥匙和地址不配套；这个不互通会在 401002 那里再出现。

第二步：只改三个参数：地域、路径、认证头

官方那句"同一份 SDK 代码通常只需替换 Base URL、API Key 与 model"落到三处具体改动。Base URL 按地域二选一：广州 https://tokenhub.tencentmaas.com/v1，新加坡 https://tokenhub-intl.tencentmaas.com/v1；国际版文档另列等价地址 https://tokenhub-intl.tencentcloudmaas.com/v1，是同一新加坡站点的另一种写法，选一个用、别拼接。两地域是独立站点，API Key 不互通，Base URL 与 Key 必须成对配套。把这些地址、路径与认证头集中写进一份配置，比散落在多个客户端里逐个改更不容易漏，尤其团队同时用广州和新加坡两个地域时，一处配错往往要排查半天。

协议路径与认证头按下表对齐，三条路径都在同一 Base URL 下，换协议是换路径和认证头，不是换域名：

表里 YOUR_API_KEY 仍是占位符说明，真实脚本一律用环境变量。一次标准调用形状如下，以 OpenAI 风格 curl 为例，密钥从环境变量取、不写死：

curl https://tokenhub.tencentmaas.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"hy4","messages":[{"role":"user","content":"你好"}]}'

第三步：model 名别写错，附最小可跑 Python

这步最该圈红。TokenHub 平台模型名是 hy4（正式版）与 hy4-preview（上一代）；OpenRouter 上的 id 是 tencent/hy4 与 tencent/hy4-preview。背后可能是同一模型，但字符串与平台都不同：往 TokenHub 的 model 字段填 tencent/hy4，或拿 hy4 去 OpenRouter 当 id，都是错的。本篇 TokenHub 调用一律填 hy4，tencent/hy4 只在讲 OpenRouter 收录信息时出现，绝不混写。hy4-preview 是 8 月 28 日发布的上一代，不是 2026 年 11 月 4 日上线的正式版；价格、能力、上下文规格按各自模型计，代际混用连账单都对不上。

下面这段最小可跑 Python 用 OpenAI 官方 SDK，密钥从环境变量读，Base URL 指向广州站点，model 填 hy4，无任何硬编码密钥：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    base_url="https://tokenhub.tencentmaas.com/v1",
)

response = client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)

print(response.choices[0].message.content)

业务在新加坡只换 base_url 与该站点的 Key 即可，其余不动，这正是"改三个参数"：结构不变，只换值。换 Anthropic 风格客户端才需要连路径、认证头一起换到 /v1/messages 与 x-api-key。TokenHub 是统一入口，model 填平台模型名而非厂商原始名，和直接对接单模型原生 API 的习惯不同；把写死 model 的地方收成一个配置常量，比逐文件替换省事。

第四步：把图片喂进去

正式版新增的看图能力，腾讯云《图片理解》官方示例很直接：把 messages 里的 content 从单个字符串换成数组，放两类元素，{"type":"image_url","image_url":{"url":"图片 URL"}} 描述图片，{"type":"text","text":"请描述这张图片..."} 提问。image_url 里的 url 既可放可访问图片地址，也可放内联 data URL。本地图片用 base64.b64encode(...) 编码后拼成 data:image/jpeg;base64,... 放进同一个 url 字段：

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    base_url="https://tokenhub.tencentmaas.com/v1",
)

with open("photo.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")
data_url = "data:image/jpeg;base64," + encoded

response = client.chat.completions.create(
    model="hy4",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": data_url}},
                {"type": "text", "text": "请描述这张图片里有什么"},
            ],
        }
    ],
)

print(response.choices[0].message.content)

content 数组的类型别写反，图片用 image_url、文字用 text，data URL 的 MIME 类型要与实际格式一致（JPEG 写 jpeg、PNG 写 png）。OpenRouter 的 GET https://openrouter.ai/api/v1/models 在 2026 年 11 月 4 日实抓把 tencent/hy4 的 modality 标为 text+image->text（文本加图片输入、文本输出），context_length 为 1,048,576，max_completion_tokens 为 65,536，支持参数含 reasoning、reasoning_effort、response_format、structured_outputs、tools、tool_choice、temperature、max_tokens、stop。这是 OpenRouter 侧对 tencent/hy4 的收录，判断能力范围方便，但别把这个 id 抄回 TokenHub 代码。多模型看图选型交给《多模型视觉输入横评》（/zh/posts/llm-vision-input-comparison-review）。

第五步：接进工具链与验收

官方列出的可接入客户端有 CodeBuddy Code、Claude Code、Codex、OpenCode、OpenClaw、Cursor、Cline、Roo Code、Kilo Code、WorkBuddy、Hermes Agent，接法是同一套三步：控制台建 Key 并开通模型（第一步）、把客户端服务地址指向 Base URL、替换 model 名并确认所用协议路径（OpenAI 风格对应 /v1/chat/completions 或 /v1/responses，Anthropic 风格对应 /v1/messages）。先发一条最简文本请求，再逐步打开图片与工具调用。验收别只看返回 200，至少核对：model 确实是 hy4、认证头与路径匹配、内容能从 choices[0].message.content 取出、usage 里 token 数量级对得上，第四步的看图请求也单独跑一遍。把这几项写成固定清单，每次换地域、换客户端或升级 SDK 后都重跑一遍，比出事之后再回头查便宜得多；验收阶段顺手造一次流式中途异常，还能提前验证解析逻辑是否兜得住。

思考模式用 thinking: {"type":"enabled"} 开启，Python SDK 里这个字段不在标准参数列表，要放进 extra_body：

response = client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "解释一下这段代码的作用"}],
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message
print(message.content)
reasoning = getattr(message, "reasoning_content", None)
if reasoning:
    print(reasoning)

思维链落在 reasoning_content，它不是 SDK 声明字段，要用 getattr(message, "reasoning_content", None) 取，直接写属性访问在部分 SDK 版本会被挡或抛错；Anthropic 路径的思考内容则在 thinking 内容块里，取法不同，别串台。

三个坑：差异、错误码、流式报错

坑一，把 TokenHub 当成标准 API 的一对一套壳。差异有四处：统一入口与统一鉴权，所有协议共用一个 Base URL、认证头还按协议族区分；model 必须填平台模型名 hy4；思考、工具调用、多模态、缓存及部分采样参数支持度因模型而异，个别字段可能被静默忽略或降级；usage 字段尤其缓存相关 token 明细不同模型不完全一致，以实际返回为准。默认"可能不同"比默认相同安全。

坑二，错误码看错层。业务错误码是 6 位数字，前三位对应 HTTP 状态码：400xxx 参数、401xxx 认证、429xxx 限流。三个最常撞上：401002 表示 API Key 无效，常见原因除拼错过期，就是地域不互通，用广州 Key 调新加坡站点或反过来都会被当成无效 Key；402xxx 表示模型未开通或额度不足，对应第一步；429xxx 表示限流，响应可能带 Retry-After，按指数退避重试而非猛刷。排查顺序固定为：先看 Key 与地域是否配套，再看模型开通与额度，最后才怀疑限流，三层逐一排除。

坑三，流式报错藏在中途。官方文档说明流式传输过程中出错时，错误信息以 SSE 错误帧夹在数据流中间，只判断首包成功就继续解析，会在中途遇到结构不同的帧而崩掉，或把错误帧当正常内容吞掉，得到看似成功却残缺的输出。解析流要把每一帧都当可能的错误帧：逐帧判类型，遇错误帧取出信息并终止消费，同时收尾连接与缓冲。非流式无此问题，但流式是工具链客户端常用模式，验收阶段值得造一次中途异常验证解析逻辑。

价格与优惠：三套口径分开算

第一套是腾讯云人民币刊例价，每百万 tokens 计：输入 6 元、输出 18 元、缓存命中 0.3 元，与 preview 相同，是后面所有折扣的计算基准。第二套是只作用于 TokenHub 的官方限时活动：即日起至 2026 年 12 月 31 日 TokenHub 按刊例价 5 折结算，Token Plan 订阅积分消耗 2.5 折持续至 2026 年 11 月 18 日，WorkBuddy 与 CodeBuddy 在 2026 年 11 月 4 日至 11 月 15 日提供一定额度免费，具体额度以官方页面为准、未公布的不编；免费口径严格按官方日期区间理解。单价幻觉、缓存计价与跨渠道对账见《大模型 API 定价横评》（/zh/posts/llm-api-pricing-comparison-review）。

第三套是 OpenRouter 美元收录价，来自 2026 年 11 月 4 日实抓的 GET https://openrouter.ai/api/v1/models：tencent/hy4 每百万 token 输入 $0.417、输出 $1.2505、缓存读 $0.021，tencent/hy4-preview 为 $0.834、$2.501、$0.042。两道界线要划清：OpenRouter 收录价不等于腾讯云官方价，两套数字不能互相换算；TokenHub 的 5 折只作用于腾讯云自己刊例价，不套到 OpenRouter。接 TokenHub 估成本用第一套乘第二套当期折扣，比较托管平台才看第三套，把折扣、平台、币种混在一张表里最后一定对不上账单。分不清时先问一句这个数字属于哪个平台、哪种币种、含不含活动，多半就能定位到串味的地方；三套口径各自留档，换季做预算时也省得重新翻文档。

常见问题

Q1：只改三个参数真的够吗？ A1：对多数沿用 OpenAI 或 Anthropic SDK 的代码够，三个参数是 Base URL、API Key、model；但协议路径要对齐，OpenAI 风格落 /v1/chat/completions 或 /v1/responses、Anthropic 风格落 /v1/messages，认证头随协议族换。开启思考、看图或工具调用还要额外传字段，那属于能力参数。

Q2：为什么拿到 Key 一调用就返回 402？ A2：402xxx 是模型未开通或额度不足，与鉴权、参数写法无关。回第一步确认 Hy4 服务已开通、额度可用，再用 GET /v1/models 看 id 为 hy4 的条目是不是 online；别去改认证头，那是 401 那一层。

Q3：TokenHub 该填 hy4 还是 tencent/hy4？ A3：填 hy4。hy4 是 TokenHub 平台名，tencent/hy4 是 OpenRouter 的 id，两套命名不能混。hy4-preview 是 8 月 28 日发布的上一代，不是 2026 年 11 月 4 日上线的正式版，要正式版就填 hy4。

Q4：广州创建的 Key 能直接调新加坡站点吗？ A4：不能。广州 https://tokenhub.tencentmaas.com/v1 与新加坡 https://tokenhub-intl.tencentmaas.com/v1 是独立站点，API Key 不互通，用错会撞 401002 无效 Key。建 Key 时定好地域，让 Base URL 与 Key 成对配套。

Q5：Hy4 正式版能下载权重自己部署吗？ A5：截至本篇写作时正式版权重尚未开源，官方称将于近期开源权重并发布系统卡片，因此没有本地部署正式版的路径，本篇只讲托管 API 接入。站内《Hy4 preview 自部署 SOP》讲的是上一代 hy4-preview 用 vLLM、SGLang 自部署，是另一回事。

延伸阅读

• Hy4 preview 自部署 SOP：vLLM 与 SGLang 跑权重
• 大模型 API 定价横评：token 账怎么算
• 腾讯 Hy4 preview 开源发布热点（8 月 28 日）
• 腾讯 Hy4 正式版发布热点
• 多模型视觉输入横评：看图能力怎么选