混元 Hy4 preview API 怎么调用？OpenAI 兼容接口接入示例与 reasoning_effort 设置指南

Hy4 preview 刚开源，但对后端开发者来说，紧迫的问题不是模型强不强，而是存量代码怎么切过去、参数怎么设才不烧钱。好消息是它提供 OpenAI 兼容接口，走 OpenAI Chat Completions 协议，多数存量代码改掉 base_url 和 model id 就能跑通。坏消息是关思考的写法在两条路径上不一样：自建端点传 no_think，TokenHub 传 none，写混了轻则报错，重则思考照跑、token 照烧。这篇指南讲清自建端点、腾讯云 TokenHub、OpenRouter 三条接入路径的前提与标识符、可复制的 Python 与 curl 示例、官方建议的采样参数、reasoning_effort 的两档取值与 no_think 模式的用法，以及按任务分级控制推理力度的清单。文中端点、标识符、参数与价格核验于 2026 年 8 月 31 日，模型处于 preview 阶段，信息变动较快，接入前以平台当前文档为准。

接入 Hy4 preview 有哪几条路？自建端点、TokenHub、OpenRouter 各适合谁

先给结论。三条路径走的是同一套 OpenAI 兼容协议，代码可以互相移植，差异集中在三件事：前提条件、计费主体、关思考的写法。关键信息如下，均核验于 2026 年 8 月 31 日：

两个补充。TokenHub 有国际版端点，新加坡为 https://tokenhub-intl.tencentcloudmaas.com/v1，硅谷为 https://tokenhub-us.tencentcloudmaas.com/v1，按美元挂牌价计费，适合海外业务。OpenRouter 的挂牌价不等于腾讯官方定价，价格里包含平台自身的计费规则，走这条路径前建议先把平台的计费规则弄清楚。

各适合谁：

• 自建：手里有 GPU 集群和运维人力，数据不能出内网，或者调用量大到云端计费不划算。部署环节（官方预构建镜像、显存与量化、常见报错）这篇不展开，站内另有一篇 Hy4 部署教程，先把服务跑起来再回到这篇。
• TokenHub：不想碰 GPU 运维、业务在国内、需要官方计费口径。开通三步：注册腾讯云账号，开通 TokenHub 服务，控制台创建 API Key，模型规格在控制台的模型详情页可查。
• OpenRouter：已有 OpenRouter 账号、需要美元计费，或者想在一个入口里同时调多家模型。

如果团队同时维护自建端点和 OpenRouter 等多条通道，可以考虑 LiteLLM 这类 OpenAI 格式网关，统一 base_url 切换并追踪各通道的 token 用量。它是否已收录 hy4-preview 的模型标识符、能否透传 reasoning_effort，目前没有查到说明，接入前自行确认。

用 Python OpenAI SDK 和 curl 调 Hy4 preview，代码怎么写

下面的代码与官方发布的 vLLM 配方、TokenHub 调用指南逐项核对过，参数名和取值照官方示例走，替换消息内容即可直接用。

自建端点，Python：

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",  # 官方示例写法，本地服务不校验密钥
)

response = client.chat.completions.create(
    model="hy4-preview",
    messages=[{"role": "user", "content": "用一句话解释 MoE 架构"}],
    temperature=0.9,
    top_p=1.0,
)

msg = response.choices[0].message
print(getattr(msg, "reasoning_content", None))  # 思考过程
print(msg.content)  # 最终回答

自建端点，curl：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy4-preview",
    "messages": [{"role": "user", "content": "用一句话解释 MoE 架构"}],
    "temperature": 0.9,
    "top_p": 1.0
  }'

TokenHub，Python：

from openai import OpenAI

client = OpenAI(
    base_url="https://tokenhub.tencentmaas.com/v1",
    api_key="你的 TokenHub API Key",
)

response = client.chat.completions.create(
    model="hy4-preview",
    messages=[{"role": "user", "content": "用一句话解释 MoE 架构"}],
    temperature=0.9,
    top_p=1.0,
)

TokenHub，curl：

curl https://tokenhub.tencentmaas.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy4-preview",
    "messages": [{"role": "user", "content": "用一句话解释 MoE 架构"}],
    "temperature": 0.9,
    "top_p": 1.0
  }'

OpenRouter 不单独给代码，只改两处：base_url 换成 https://openrouter.ai/api/v1，model 换成 tencent/hy4-preview，其余写法一致。

三个容易卡住的点：

1. 思考过程和最终回答分属两个字段。思考在 reasoning_content，回答在 content。OpenAI SDK 的类型定义里没有 reasoning_content，IDE 不会补全，直接点访问可能报属性错误，用 getattr(msg, "reasoning_content", None) 取，或者解析原始响应 JSON。
2. 自建路径要看到思考与回答分离，部署时需开启推理框架的 reasoning parser，对应启动参数 --reasoning-parser hy_v4，否则思考可能混在 content 里一起返回。工具调用同理，需要 --tool-call-parser hy_v4。这两个属于部署配置，细节在站内那篇 Hy4 部署教程里。
3. TokenHub 除了 OpenAI Chat Completions，官方声明还兼容 OpenAI Responses 和 Anthropic Messages 两种协议，存量代码如果是后两种协议也能直接切，本文示例统一用 Chat Completions。

reasoning_effort 支持哪些值？关思考为什么自建写 no_think、TokenHub 写 none

这是全文最容易踩的坑，单独讲透。

先说结论：reasoning_effort 控制 Hy4 preview 在回答前是否展开思考过程，这个参数只有两档，没有 low，也没有 medium。自建路径是 high 和 no_think，high 是默认；TokenHub 路径是 high 和 none，high 同样是默认。官方仓库附带的聊天模板里写得很直接，reasoning_effort 的值不在允许列表内会直接抛异常，所以自建路径传错值会报错，不会静默降级。

两条路径关思考的写法，对照着看：

# 自建：no_think 走 chat_template_kwargs
response = client.chat.completions.create(
    model="hy4-preview",
    messages=[{"role": "user", "content": "把这段 JSON 转成 Markdown 表格"}],
    temperature=0.9,
    top_p=1.0,
    extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}},
)

# TokenHub：none 是请求体顶层参数，也可用 thinking 开关
response = client.chat.completions.create(
    model="hy4-preview",
    messages=[{"role": "user", "content": "把这段 JSON 转成 Markdown 表格"}],
    temperature=0.9,
    top_p=1.0,
    extra_body={"reasoning_effort": "none"},
    # 或者：extra_body={"thinking": {"type": "disabled"}},
)

差别在传参层级。自建的 no_think 走 chat_template_kwargs，这是推理框架把参数传给聊天模板的通道；TokenHub 的 none 是请求体顶层参数，另有一条 thinking.type 的开关写法，默认 enabled。extra_body 里的键会原样放进请求体，正好满足两种形态。把自建的写法原样搬到 TokenHub，或者反过来，都不行。自建传非法值会触发模板异常，这一点有官方模板代码支撑；TokenHub 收到 no_think 这类不认识的值是报错还是忽略，官方文档没有写明，属于待实测项，实测方法：带错误值发一次请求，看返回。

还有一个文档陷阱。TokenHub 的深度思考文档里有一张通用参数表，列了 low、medium、high 三档，但同一份文档针对 hy4-preview 的模型专属表格明确写的是只支持 none 和 high。以模型专属表格为准，照通用表格给 hy4-preview 传 low 或 medium，大概率踩坑。从混元旧版本或其他推理模型迁过来的团队也注意，别把之前的思考参数习惯直接套用，Hy4 的档位设置和它们不一样。

两档的实际行为：high 是默认深思考档，模型先在 reasoning_content 里展开推理，再给最终答案；no_think 模式和 none 档关掉思考过程，直接出答案。两档在输出质量和 token 消耗上的量化差异，官方没有给数据，属于待实测验证项。实测方法很朴素：同一个任务，开思考和关思考各跑一次，对比响应里 usage 字段的 token 数和答案质量，再决定你的任务用哪档。

temperature、top_p 照官方建议设，还是用通用经验值

直接照官方建议设：temperature 0.9，top_p 1.0。这组数值在官方模型卡、vLLM 官方配方、SGLang 官方 Cookbook 三处一致，是随模型发布给出的建议值，不是社区经验值。

很多团队的习惯是照搬 0.7 之类的通用温度，在 Hy4 上没有必要。如果业务确实想偏离，比如代码生成想降温度求稳定，官方没有给分场景建议，偏离后的效果要自己验证，不要默认通用经验值在这套采样分布上同样成立。

max_tokens 顺带一句：它是限制输出长度的通用手段，能兜住回答本身的长度，但 Hy4 上它是否同时限制思考过程的 token，官方文档没有写明，属于待实测项。实测方法：设一个很小的 max_tokens，开着思考发一次请求，看截断的是思考还是回答。实测结论出来之前，别把 max_tokens 当成思考膨胀的兜底手段。

一次调用到底烧多少 token？挂牌价、思考膨胀与按任务分级的清单

先把价格基准摆出来。据多家媒体援引腾讯官方发布，TokenHub 国内计费为：输入每百万 token 6 元，输出每百万 token 18 元，缓存命中的输入每百万 token 0.3 元。新加坡区域按美元计：输入 0.834 美元、输出 2.501 美元、缓存命中 0.042 美元，均按每百万 token 计。OpenRouter 挂牌价与新加坡区域数字一致，输入 0.834 美元、输出 2.501 美元，缓存读 0.042 美元、缓存写 0 美元，但这是平台挂牌价，包含平台自身计费规则，不等于腾讯官方定价。以上价格核验于 2026 年 8 月 31 日，正式接入前以平台当前页面为准。

价格不是重点，重点是长思考怎么把账单推高。默认 high 档下，模型先在 reasoning_content 里展开推理，这部分 token 如果计入输出侧计费，消耗会明显放大。reasoning_content 是否计入输出计费，官方文档没有明确，属于待实测项，实测方法：开思考和关思考各跑一次相同任务，对比 usage 里的输出 token 数和实际账单。

给一个估算框架，数字是假设条件，代入你自己的任务画像即可。假设一次调用输入 50k token（比如一篇长文档），思考 10k token，回答 3k token：

• 输入侧：50k ÷ 1M × 6 元 = 0.3 元
• 输出侧，若思考计入输出计费：(10k + 3k) ÷ 1M × 18 元 ≈ 0.234 元，单次合计约 0.53 元
• 输出侧，若思考不计费：3k ÷ 1M × 18 元 = 0.054 元，单次合计约 0.35 元

两种口径单次差 0.18 元左右，单看不多，批量跑一万次就是 1800 元的差距。批量业务上线前把计费口径实测清楚，比任何参数调优都值钱。

按任务分级设置推理力度的清单：

两个省钱的补充动作。一是利用缓存命中价：0.3 元每百万的缓存命中价是正常输入价的二十分之一，固定 system prompt、重复长前缀的场景（比如反复对同一批文档提问）值得专门设计前缀结构去命中缓存，具体命中机制以平台文档为准。二是把 usage 字段记进日志：每次调用返回的 usage 里有 prompt_tokens、completion_tokens、total_tokens，按档位、按任务类型统计，跑一周就能看出哪类任务在烧思考 token，哪类关了思考质量也没掉。

还有哪些限制和坑要提前知道

1M 上下文不能想当然用满。TokenHub 文档标的窗口是 1024k，最大输入 960k，最大输出 64k；OpenRouter 模型页标的是 1,048,576 上下文、64,000 最大输出。标称 1M 的窗口里，输入加输出要留出余量，云端路径还受账户配额约束，配额数值以控制台为准，容量规划别按一次塞满 1M 来做。

纯文本模型，不能传图。输入只收文本，图像输入会被拒绝并返回 HTTP 400。业务有多模态需求的，这个模型不满足，属于不适合的场景。

文档口径要交叉看。前面讲过的 TokenHub 深度思考文档通用表与模型专属表不一致，是 preview 阶段的典型现象。遇到参数行为和文档描述对不上，优先查模型专属说明和官方仓库的聊天模板，再开 issue 反馈。

常见问题

Hy4 preview 的 reasoning_effort 有 low 或 medium 档吗？
没有。自建路径只有 high（默认）和 no_think，TokenHub 路径只有 high（默认）和 none。TokenHub 深度思考文档的通用参数表列了 low、medium、high，但那张表不适用于 hy4-preview，以模型专属表格为准。

思考内容从哪个字段取？
reasoning_content，最终回答在 content。OpenAI SDK 类型里没有这个字段，用 getattr(message, "reasoning_content", None) 访问，或解析原始响应 JSON。

OpenRouter 上怎么关思考？
目前没有查到 OpenRouter 是否透传 reasoning_effort 或 no_think 的说明，属于待实测项。实测方法：带参数发一次请求，看响应里思考是否消失，或者是否直接报参数错误。

怎么选，下一步做什么

三步走：

1. 定路径。有 GPU 集群和运维人力、数据敏感或调用量极大，走自建；不想碰运维、业务在国内，走 TokenHub；已有 OpenRouter 账号或需要美元计费，走 OpenRouter。
2. 定参数。采样参数照官方建议，temperature 0.9、top_p 1.0；思考档位按上面的清单分级，简单任务关思考。
3. 定成本口径。上线前实测两件事：reasoning_content 是否计入输出计费，两档 usage 差异多大。这两个数字决定批量流量怎么分档。

适合现在就接入的：已跑通自建服务，或业务就是纯文本加长上下文加深推理的团队。建议先观望的：需要多模态输入的团队，以及对计费口径敏感但暂时没条件实测的团队，可以等 preview 转正式、文档口径统一后再接。

文中端点、模型标识符、参数取值与价格核验于 2026 年 8 月 31 日。Hy4 preview 处于 preview 阶段，档位、端点、价格都可能调整，接入前以腾讯云 TokenHub 文档、OpenRouter 模型页和官方仓库的当前内容为准。