Hunyuan 参数与协议差异
了解混元系列模型在兼容协议下的参数差异与使用方式。
使用混元模型时，根据本页调整所选协议的参数。完整请求和响应结构参阅 Chat Completions、Responses 和 Messages。
| 模型 | 适用范围 |
|---|
| hy4-preview | 支持 Chat、Responses、Messages；Chat 思考深度使用 none/high，默认 high |
| hy3 | 支持 Chat、Responses、Messages；Chat 思考深度使用 none/low/high，默认 high；保留式思考及工具限制按下表设置 |
| 字段 | 差异说明 |
|---|
thinking.type | 两款模型默认开启思考，使用 enabled/disabled 显式开关；reasoning_effort 的可用档位见上表 |
reasoning_effort | Hy3 携带 tools 时，low 会映射为 high；此时由模型根据工具任务决定推理深度 |
max_tokens、max_completion_tokens | 均限制思考与最终回答的总 Token 数，后者优先。Hy3 思考场景建议至少 16000，这是预算建议，不是字段最小值 |
top_k、repetition_penalty | 客户端传入时被静默忽略，不按 Qwen 等厂商的扩展字段使用 |
n | 开启思考时须为 1 |
preserved_thinking | Hy3 的保留式思考开关；携带 tools 时默认开启，普通文本对话默认关闭。字段拼写为 preserved_thinking |
历史 reasoning_content | 工具结果回填时，完整保留上一轮 assistant 的思考内容和 tool_calls；开启保留式思考不会替客户端补齐历史 |
tool_choice | 思考模式下不使用 required 或强制指定函数，使用 auto/none |
web_search_options | Hy3 的原厂搜索扩展：设置 enable: true；search_source 使用 standard/lite，默认 standard。此处仅说明 Hy3 的搜索字段 |
| 字段 | 差异说明 |
|---|
max_output_tokens | 包含思考与最终回答，避免只按可见文字预留预算 |
tool_choice | Hy3 仅支持 auto/none，不支持 required 或指定函数对象 |
previous_response_id | Hy3 不支持非空值，传入会返回 400；多轮对话通过 input 自行携带历史 |
reasoning.preserved_thinking | Hy3 的保留式思考开关，放在 reasoning 对象中；默认策略与 Chat 相同 |
text.format | 支持 text/json_object/json_schema；Hy3 的 JSON Schema 须包含 additionalProperties: false |
tools 中的 web_search | Hy3 原厂搜索扩展使用 type: "web_search"；与 Chat 的 web_search_options 配置位置不同 |
| 字段 | 差异说明 |
|---|
thinking.type、max_tokens | 显式开关使用 enabled/disabled；max_tokens 包含思考与最终回答，设置 budget_tokens 时为正文留出余量 |
HY-Preserved-Thinking | Hy3 的保留式思考 Header，支持 true/false；省略时采用默认策略。不要将 Chat 的顶层字段直接放入 Messages 请求体 |
| 历史 thinking 块 | 随工具结果保留实际返回的 assistant 内容。Hy3 不返回 signature 时无需补造签名，不套用 Claude 的签名必返规则 |
| 字段 | 差异说明 |
|---|
prompt_cache_key | Chat 的缓存标识扩展；保持相同前缀及稳定取值，通过响应确认实际命中 |
| 保留思考与缓存 | 保留式思考用于延续推理，不等于已经命中缓存；完整、稳定的历史有利于复用前缀 |
| 缓存用量 | Chat 查看 usage.prompt_tokens_details.cached_tokens；Responses 查看实际返回的 usage.input_tokens_details.cached_tokens；Messages 查看实际返回的 usage.cache_read_input_tokens |
将 MODEL_ID 替换为平台提供的完整模型 ID，API Key 使用自己的值。以下均使用文本输入。
curl 'https://api.agtcloud.cn/v1/chat/completions' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "用三点说明如何排查接口超时"}],
"reasoning_effort": "high",
"max_completion_tokens": 16384
}'