Hunyuan parameter and protocol differences

For Hunyuan models, adjust your chosen protocol's parameters using this page. See Chat Completions, Responses and Messages for full request and response structures.

Applicable models

Model	Applies to
hy4-preview	Supports Chat, Responses and Messages; Chat effort levels: `none/high`; default: `high`
hy3	Supports Chat, Responses and Messages; Chat effort levels: `none/low/high`; default: `high`. Configure retained thinking and tool limits as below

Chat Completions differences

Field	Difference
`thinking.type`	Both models enable thinking by default; explicitly switch with `enabled/disabled`. Available `reasoning_effort` levels are listed above
`reasoning_effort`	For Hy3 with `tools`, `low` maps to `high`; the model then selects reasoning depth for the tool task
`max_tokens`, `max_completion_tokens`	Both limit thinking and the final answer; the latter takes precedence. At least `16000` is recommended for Hy3 thinking, not required as the field minimum
`top_k`, `repetition_penalty`	Silently ignored when supplied by the client; do not treat these as Qwen-style extensions
`n`	Must be `1` when thinking is enabled
`preserved_thinking`	Hy3 retained-thinking switch; enabled by default with `tools`, disabled for plain text conversations. The spelling is `preserved_thinking`
Historical `reasoning_content`	When returning tool results, preserve the previous assistant thinking and `tool_calls`. Enabling retained thinking does not fill in missing client history
`tool_choice`	In thinking mode, use `auto/none`, not `required` or a named function
`web_search_options`	Hy3 native search extension: set `enable: true`; `search_source` uses `standard/lite`, defaulting to `standard`. This row only describes Hy3 search

Responses differences

Field	Difference
`max_output_tokens`	Includes thinking and the final answer; allow budget for more than visible text
`tool_choice`	Hy3 only supports `auto/none`, not `required` or a named function object
`previous_response_id`	Hy3 rejects nonempty values with `400`; include history yourself in `input` for multi-turn conversations
`reasoning.preserved_thinking`	Hy3 retained-thinking switch, placed inside `reasoning`; default behavior matches Chat
`text.format`	Supports `text/json_object/json_schema`; Hy3 JSON Schema requires `additionalProperties: false`
`web_search` in `tools`	Hy3 native search uses `type: "web_search"`, configured differently from Chat's `web_search_options`

Messages differences

Field	Difference
`thinking.type`, `max_tokens`	Explicit switches use `enabled/disabled`; `max_tokens` includes thinking and the final answer. Leave room for answer text when setting `budget_tokens`
`HY-Preserved-Thinking`	Hy3 retained-thinking Header; supports `true/false`; omitted values follow the default policy. Do not place Chat's top-level field in a Messages request body
Historical thinking blocks	Preserve the returned assistant content with tool results. If Hy3 omits `signature`, do not fabricate a signature; Claude's required-signature rule does not apply

Cache differences

Field	Difference
`prompt_cache_key`	Chat cache-identifier extension; keep the prefix and identifier stable, and confirm hits from responses
Retained thinking and caching	Retained thinking carries reasoning forward; it does not imply a cache hit. Complete, stable history helps reuse prefixes
Cache usage	Chat: inspect `usage.prompt_tokens_details.cached_tokens`; Responses: returned `usage.input_tokens_details.cached_tokens`; Messages: returned `usage.cache_read_input_tokens`

Request examples

Replace MODEL_ID with the full platform model ID and use your own API Key. All examples below use text input.

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": "Explain how to troubleshoot an API timeout in three points"}],
    "reasoning_effort": "high",
    "max_completion_tokens": 16384
  }'