For calls to the Hy4 GA release, use hy4 as the model ID in the request; hy4-preview is a separate preview ID. TokenHub documentation also provides fields for Hy4's extended thinking, reasoning effort, image input, and tool calls.
Suitable tasks: Calling the Hy4 GA release on Tencent Cloud TokenHub, setting reasoning effort, or submitting text and image inputs.
Unsuitable tasks: Treating hy4-preview as the GA model ID; using this article as a complete guide to obtaining credentials or initializing an SDK.
Applicable model version: Hy4 GA release, with the call value hy4.
Applicable client, agent, or API: TokenHub OpenAI Chat Completions; the documentation also says hy4 is compatible with the OpenAI Responses and Anthropic Messages APIs.
Recommended reasoning tier and parameters: The documentation says Hy4 has extended thinking enabled by default, with a default reasoning effort of high; the request example uses thinking: {"type":"enabled"} and reasoning_effort: "high".
The example below follows TokenHub's Chat Completions request format and combines the GA model ID, reasoning parameters, and an image content block. Replace YOUR_API_KEY and YOUR_IMAGE_URL with your own values.
curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "hy4",
"messages": [{"role": "user", "content": [
{"type": "text", "text": "请描述图片中的主要内容。"},
{"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}}
]}],
"thinking": {"type": "enabled"},
"reasoning_effort": "high",
"stream": false
}'GA release: model: "hy4".
Preview release: model: "hy4-preview"; do not use it interchangeably with the GA release.
The documentation lists a Hy4 context window of 1024k, a maximum input of 960k, and a maximum output of 64k.
Image input uses content blocks in messages[].content: set type: "image_url" and put the image address in image_url.url. A text block can be included in the same array.
For streaming requests, set stream: true. To include usage in the final data chunk, add stream_options: {"include_usage": true}.
Set model explicitly to hy4 in the request and make sure hy4-preview has not been carried over.
To control thinking explicitly, pass thinking: {"type":"enabled"} as in the documentation's request example; the reasoning-effort example uses reasoning_effort: "high". The documentation also says Hy4 has extended thinking enabled by default and defaults to high reasoning effort.
For image understanding, add an image_url content block and a text task description to the content array of the user message.
For tool calls, send the standard Chat Completions tools / tool_choice structure. If the reasoning context from the documentation's example needs to continue in a later turn, include the assistant's reasoning_content along with the tool result.
Check model, tool_calls, finish_reason, and usage in the response to confirm that the service returned the expected model and completion status.
TokenHub's model table explicitly identifies hy4 as the “Hy4 GA release” and says it enhances capabilities for agentic, long-horizon, and real-world productivity tasks, while introducing visual understanding for the first time. The table lists it separately from hy4-preview.
The documentation says hy4 is compatible with OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. Its request examples consistently use https://tokenhub.tencentmaas.com/v1/chat/completions.
The basic conversation, extended thinking, reasoning effort, tool call, and image understanding examples all set model to hy4. The extended thinking example shows thinking: {"type":"enabled"}; the reasoning configuration example shows reasoning_effort: "high".
The image understanding example passes {"type":"image_url","image_url":{"url":"YOUR_IMAGE_URL"}} in the content array and can also pass {"type":"text","text":"..."}.
The documentation says streaming calls return incremental results over SSE; stream_options.include_usage can be used to get the complete usage in the final chunk.
This article records the model ID and request fields in TokenHub documentation. Support for specific protocol fields depends on the selected API protocol and the current TokenHub documentation.
The documentation's image example uses URL input. No additional limits on image size, format, accessibility, or Base64 are inferred from it.
reasoning_content appears in the documentation's response and tool-continuation examples. Whether to store or display it should be determined according to the application's own data-handling policies.
The Tencent Cloud Developer Community's Hy4 setup guide lists a different base_url. Check the address against the official documentation for the service you use.
On 2026-11-16, Tencent Cloud TokenHub's “Hunyuan API Guide” was opened through Tabbit to check the model table and the sections on basic conversation, extended thinking, reasoning effort, streaming requests, tool calls, and image understanding. The page showed a last-updated time of 2026-11-16 12:15:31. The documentation page was readable; authentication-related non-document requests returned 401, which did not affect verification of the public content.
Hy4