Hunyuan 參數與協定差異
了解 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.ai/v1/chat/completions' \
-H 'Authorization: Bearer your-api-key' \
-H 'Content-Type: application/json' \
--data '{
"model": "MODEL_ID",
"messages": [{"role": "user", "content": "用三點說明如何排查 API 逾時"}],
"reasoning_effort": "high",
"max_completion_tokens": 16384
}'