腾讯云TokenHub调用混元Hy3 API指南：接入步骤、快慢思考模式切换与价格说明

混元 Hy3 正式版发布后，后端开发者面临的首要任务是将现有业务从 preview 版本平滑迁移到正式版，或从零接入新 API。这涉及模型标识符更换、TokenHub 服务开通、OpenAI 兼容接口编写、快慢思考模式参数配置及最新计费核算。本指南聚焦这些开发实操环节，提供可直接复用的代码示例和参数配置建议，帮助开发者快速完成接入并控制调用成本。

混元Hy3 preview与正式版怎么选？模型标识符有何区别？

在开始编写代码之前，开发者首先需要明确自己应该调用哪个版本的模型。腾讯云 TokenHub 平台目前同时提供了混元 Hy3 的预览版和正式版，两者在模型标识符、能力侧重点和适用场景上存在明显差异。

1. 模型标识符区分

正式版与预览版的模型标识符如下：

• 正式版标识符：hy3。这是最新发布的正式版本，强化了在 Coding（代码生成）、长文本处理和 Agent（智能体）工作流方面的能力。如果你的业务场景涉及复杂的代码编写、长文档总结摘要或者需要模型作为智能体进行多步推理和工具调用，应该优先使用 hy3 标识符。
• 预览版标识符：hy3-preview。这是早期发布的预览版本，同样面向 Agent 工作负载，支持交错式思考和 Function Calling（函数调用）。如果你正在进行早期的功能验证，或者业务系统暂时还未完成正式版的兼容性测试，可以继续使用该标识符。

2. 上下文窗口支持

无论是 hy3 还是 hy3-preview，两者均支持 256k 的上下文窗口。这意味着开发者可以在单次请求中传入约 20 万字以上的中文文本或大量的代码文件。对于需要处理超长上下文的场景，例如整个代码库的分析或者长篇财报的解读，这两个版本在输入长度上都能满足需求。

3. 版本选择建议

对于新启动的项目，直接使用 hy3 正式版标识符即可，以获取最新的模型能力优化。对于已经接入 hy3-preview 的存量项目，建议在测试环境中将模型标识符修改为 hy3 进行回归测试，确认业务逻辑无误后再在生产环境进行切换。需要注意的是，由于模型能力的升级，正式版在某些特定提示词下的输出风格可能与预览版存在细微差异，开发者应关注这种输出一致性的变化。

如何在腾讯云TokenHub平台开通服务并获取API Key？

要调用混元 Hy3 的 API，开发者需要通过腾讯云的大模型服务平台 TokenHub 来获取调用凭证。以下是完整的开通与获取步骤：

第一步：注册腾讯云账号并完成实名认证

如果你还没有腾讯云账号，需要先访问腾讯云官网进行注册。注册成功后，必须完成个人或企业的实名认证。根据国内云服务平台的合规要求，未进行实名认证的账号无法开通任何云服务，也无法生成有效的 API Key。

第二步：进入 TokenHub 控制台

登录腾讯云控制台后，在顶部搜索栏输入“TokenHub”或“大模型服务平台”，进入 TokenHub 的管理控制台。TokenHub 是腾讯云提供的统一大模型 API 调用网关，开发者可以在这里管理不同模型的访问权限和计费方式。

第三步：开通 TokenHub 服务

首次进入控制台时，系统会提示你开通 TokenHub 服务。阅读并同意服务协议后，点击开通。开通过程通常是即时的，不需要额外的审核等待。开通后，你将看到平台支持的各种大模型列表，包括混元系列以及其他第三方模型。

第四步：获取 API Key

在 TokenHub 控制台的左侧导航栏中，找到“API Key 管理”或“密钥管理”选项。点击“创建密钥”按钮，系统会为你生成一个以特定前缀开头的 API Key。请务必妥善保管这个 Key，它将在后续的代码调用中作为身份验证的凭证。为了安全起见，建议不要将 Key 硬编码在代码中，而是通过环境变量或密钥管理服务来注入。

如何用Python和curl调用混元Hy3的OpenAI兼容接口？

TokenHub 平台提供了兼容 OpenAI Chat Completions API 的接口地址，这意味着开发者可以直接使用现有的 OpenAI SDK 或任何支持 OpenAI 接口格式的 HTTP 客户端来调用混元 Hy3，无需学习全新的请求格式。

API 接入地址

混元 Hy3 的 API 基础地址（Base URL）为：https://tokenhub.tencentmaas.com/v1。在配置 SDK 时，需要将原本指向 OpenAI 官方的地址替换为这个地址。

1. Python 调用示例

使用 Python 调用时，最便捷的方式是安装官方的 OpenAI Python SDK。如果你还没有安装，可以通过 pip install openai 命令进行安装。

以下是一个完整的 Python 调用示例，展示了如何设置 Base URL、API Key，并发送一个基本的聊天补全请求：

import os
from openai import OpenAI

# 建议将 API Key 存储在环境变量中
# export TOKENHUB_API_KEY="你的API Key"
api_key = os.getenv("TOKENHUB_API_KEY")

# 初始化 OpenAI 客户端，指向 TokenHub 的接口地址
client = OpenAI(
    api_key=api_key,
    base_url="https://tokenhub.tencentmaas.com/v1"
)

# 发送请求
response = client.chat.completions.create(
    model="hy3",  # 使用正式版标识符
    messages=[
        {"role": "system", "content": "你是一个专业的后端开发助手。"},
        {"role": "user", "content": "请用 Python 写一个快速排序算法。"}
    ],
    # 可以在这里配置 reasoning_effort 参数，后续会详细讲解
    # extra_body={"reasoning_effort": "high"}
)

# 打印模型返回的文本内容
print(response.choices[0].message.content)

在这个示例中，model 参数设置为 hy3。如果你需要调用预览版，只需将其改为 hy3-preview。messages 数组遵循标准的 OpenAI 格式，包含 system 和 user 角色。

2. curl 调用示例

对于不使用 Python 的开发者，或者需要在终端中快速测试接口连通性的场景，可以使用 curl 命令直接发送 HTTP POST 请求。

curl -X POST https://tokenhub.tencentmaas.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy3",
    "messages": [
      {
        "role": "user",
        "content": "请解释一下什么是闭包，并给出一个 JavaScript 的例子。"
      }
    ],
    "reasoning_effort": "low"
  }'

在 curl 命令中，Authorization 头部需要携带你的 API Key。请求体是一个 JSON 字符串，其中 model 和 messages 是必填字段。reasoning_effort 是控制思考深度的可选参数，我们将在下一节详细说明。

reasoning_effort参数怎么配？快慢思考模式有何差异？

混元 Hy3 的一个核心特性是支持快慢思考模式的切换。开发者可以通过配置 reasoning_effort 参数来控制模型在生成回答时的思考深度，从而在响应延迟、Token 消耗和回答质量之间寻找平衡点。

1. 参数取值与行为说明

reasoning_effort 参数支持以下取值：

• low：快思考模式。模型会快速生成回答，不进行深度的内部推理。适用于日常对话、简单的信息提取、翻译等对延迟要求高且逻辑简单的任务。
• high：慢思考模式。模型在输出最终答案前，会进行深度的内部推理（生成 reasoning_content）。适用于复杂的数学计算、代码调试、多步骤的 Agent 任务规划等需要高准确率的场景。
• medium：中等思考模式。需要注意的是，在 TokenHub 网关层，medium 会被自动映射为 low。因此，如果你需要比 low 更深度的思考，请直接使用 high，不要依赖 medium。
• no_think：用于完全关闭思考过程的取值。在 TokenHub API 调用中，通常使用 low 即可实现类似效果。

2. 三种模式差异对比

为了更直观地展示不同模式的差异，以下表格对比了 low、medium（实际映射为 low）和 high 在关键指标上的表现：

3. ToolCall 场景下的自适应映射

在涉及 Function Calling（工具调用）的 Agent 场景中，模型需要准确地解析用户意图并生成正确的工具调用参数。为了保证工具调用的准确性和稳定性，TokenHub 官方说明，在 ToolCall 场景下，模型具备 adaptive thinking（自适应思考）能力。如果你在请求中设置了 reasoning_effort="low"，API 会自动将其映射为 high。

这意味着在开发 Agent 应用时，你不需要手动为每一次工具调用请求强制设置 high 模式，系统会自动提升思考深度。但开发者需要注意，这种自动映射会导致 ToolCall 请求的延迟和 Token 消耗显著高于普通的快思考请求，在成本评估时必须将这一因素考虑在内。

4. 慢思考模式下的历史回填

当使用 high 慢思考模式进行多轮对话时，模型在每一轮可能会生成 reasoning_content（思考过程内容）。为了保持上下文的连贯性，官方建议在每一轮请求中，都需要将上一轮模型返回的 reasoning_content 字段回填到 messages 数组中对应的 assistant 消息里。如果不进行回填，模型可能会丢失之前的思考上下文，导致多轮推理出现断层。

TokenHub怎么计费？混元Hy3正式版和preview版价格是多少？

接入 API 后，成本控制是开发者必须关注的问题。TokenHub 对混元 Hy3 的正式版和预览版采用了不同的计费策略。以下价格信息截至 2026-07-07，后续可能随官方调整而变化，请以 TokenHub 官方文档最新数据为准。

1. Hy3 正式版计费规则

混元 Hy3 正式版（hy3）采用了统一定价策略，不再根据上下文长度进行阶梯收费。这种定价方式简化了成本预估的难度。

2. Hy3 preview 阶梯计费规则

混元 Hy3 预览版（hy3-preview）采用了基于上下文长度的阶梯定价机制。上下文越长，单价越高。

3. 成本优化建议

• 利用缓存命中：对于包含大量固定系统提示词或长文档的重复请求，开启上下文缓存可以将输入成本降至原来的四分之一（正式版从 1 元降至 0.25 元）。
• 合理选择思考模式：如前所述，high 模式会生成额外的 reasoning_content，这部分内容也会计入输出 Token 消耗。对于简单任务务必使用 low 模式，避免不必要的 Token 浪费。
• 版本选择与成本：对于短上下文（<16k）的场景，正式版（1 元）比预览版（1.2 元）更便宜且能力更强。对于长上下文场景，正式版的统一定价（1 元）也优于预览版的阶梯高价。因此，从成本和能力角度综合考量，迁移到正式版都是更优的选择。

腾讯云TokenHub还有免费额度吗？怎么领取和使用？

为了方便开发者进行前期测试和功能验证，TokenHub 平台提供了新人免费体验包。

1. 免费额度规则

主账号可以一次性领取混元模型的免费 Tokens。目前明确列出的是针对 Hy3 preview 的 100 万 Tokens 免费额度，有效期为 90 天。

2. 领取与使用方式

• 领取入口：登录 TokenHub 控制台，在“资源包管理”或“免费体验”页面，找到对应的新人免费体验包进行领取。通常每个主账号只能领取一次。
• 有效期计算：免费额度的 90 天有效期从领取成功的那一刻开始计算，并非从账号注册日开始。过期后未使用完的额度将自动失效，不可延期。
• 抵扣顺序：在调用 API 时，系统会优先抵扣免费额度内的 Tokens，超出部分再按后付费（或购买的资源包）进行扣费。

3. 关于 Hy3 正式版免费额度

截至 2026-07-07，hy3 正式版是否有独立的免费体验额度，或是否共享 hy3-preview 的 100 万 Tokens 额度，尚未明确。由于模型版本和运营策略可能随时更新，建议开发者在领取页面以控制台实时显示的可用模型和额度信息为准。如果控制台显示正式版不可用免费额度，建议先用少量后付费资金进行测试，或继续使用 preview 版的免费额度进行初步功能验证。

常见问题排查

Q1：为什么设置了 reasoning_effort="medium" 但感觉响应速度和 low 一样？
A：这是因为 TokenHub 网关层将 medium 映射为了 low。如果你需要更深度的推理，请直接将参数修改为 high。

Q2：为什么在 ToolCall 场景下设置了 low 模式，依然很慢且 Token 消耗大？
A：官方说明，在 ToolCall 场景下模型具备 adaptive thinking 能力，为了保证工具调用的准确性，API 会自动将 low 映射为 high。这会导致模型进行慢思考，从而增加延迟和 Token 消耗。这是预期内的行为。

Q3：Hy3 正式版和 preview 版可以共用同一个 API Key 吗？
A：可以。TokenHub 平台的 API Key 是账号级别的，只要你的账号开通了对应模型的调用权限，同一个 Key 可以通过修改请求体中的 model 参数来切换调用不同的模型。

Q4：免费额度的 90 天有效期是从什么时候开始算？
A：从你在控制台成功点击领取免费体验包的那一刻开始计算 90 天。如果在领取后 90 天内未使用完毕，剩余额度将自动清零。

Q5：调用接口时提示模型不存在怎么办？
A：首先检查请求体中的 model 参数拼写是否正确（正式版为 hy3，预览版为 hy3-preview）。其次，检查你的 TokenHub 控制台是否已经成功开通了该模型的调用权限。如果模型列表文档页面存在更新延迟未显示 hy3，请以《混元调用指南》为准直接尝试调用。

Q6：慢思考模式下，每一轮请求都需要回填历史的 reasoning_content 字段吗？
A：是的。为了保证多轮对话中推理逻辑的连贯性，建议在构造 messages 数组时，将上一轮 assistant 回复中的 reasoning_content 字段一并放入对应的消息对象中，避免模型丢失思考上下文。

下一步操作建议

登录 TokenHub 控制台领取免费体验包，使用本文提供的 Python 或 curl 示例进行首次调用，直观感受快慢思考模式的输出差异，再决定是否进行全面的业务迁移。