Hy โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generationAuthentication: Tokenhub API Key / Bearer
Hy Image is Tencent Hunyuan's image generation model, supporting text-to-image and reference-image editing. 3.5 Preview supports continuous editing using conversation history.
Basic information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Not supported |
Hy-Image-3.0 image generation โ
API description โ
Enter a text prompt to generate an image synchronously. If you do not pass size but specify a size or ratio in the prompt, the model selects the closest item among the preset 37 combinations. If neither is specified, the model predicts automatically. For details, see Appendix: Hy-Image-3.0 preset size list.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generation
Request parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model ID. Value: hy-image-v3 |
| prompt | Required | string | Text used for image generation, with a maximum length of 8192 characters. |
| images | Optional | array[string] | Reference image 0~3. Image URLs or Base64 are supported. Formats: png / jpeg / jpg. Size per image: โค 10 MB. |
| size | Optional | string | Generation size, in the format ${width}x${height}.Constraints: โ Both width and height must be within the [512, 2048] pixel range. โก The product of width and height (image area) must not exceed 1024ร1024 pixels.If not specified, the model selects/predicts from the preset 37 combinations.For details, see Appendix: Hy-Image-3.0 preset size list. |
| seed | Optional | integer | Generation seed, in the range [1, 4294967295]. It applies only when the number of generated images is 1. If not specified or set to 0, a random seed is used by default. |
| footnote | Optional | string | Custom watermark content. It is limited to 16 characters regardless of whether it is Chinese or English, and is generated in the lower-right corner of the image. |
| revise | Optional | boolean | Whether to rewrite the prompt. |
Request example โ
# Text-to-Image
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "hy-image-v3",
"prompt": "An orange kitten on the windowsill looks toward the camera",
"size": "1024x1024"
}'Response parameters โ
| Parameter | Type | Description |
|---|---|---|
| id | string | The id of this request. |
| created | integer | Unix timestamp. |
| data | list | An array of the returned image generation content. |
| data[n].url | string | The generated image URL is a temporary URL and is valid for 12 hours. Download and save it immediately. |
| data[n].revised_prompt | string | The rewritten prompt. It is returned only when revise is enabled. |
| request_id | string | A unique request identifier used for troubleshooting. |
| tokenhub_usage | object | Token usage. |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing/settlement. |
Response example โ
{
"id": "4-WandImage-a786becfdc80433b8cff4aa344c8fd3d",
"created": 1785125529,
"data": [
{
"url": "https://aigc-image.cos.myqcloud.com/xxx/result.png",
"revised_prompt": "An orange kitten sits on a sun-drenched windowsill, turns to look at the camera, with detailed fur and a blurred background"
}
],
"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2",
"tokenhub_usage": {
"total_tokens": 1024
}
}The returned url is a temporary address that is valid for 12 hours. This address requires authentication, so accessing it directly from the browser address bar may be denied. We recommend downloading it in one of the following ways.
curl -o generated_image.png 'https://aigc-image.cos.myqcloud.com/xxx/result.png'Alternatively, use the HTTP client in your code to download and save it to local storage.
Error codes โ
| HTTP status code | Description | Handling recommendation |
|---|---|---|
400 | The request format is invalid. | Check the field types/values in the request body (for example, size constraints, prompt length, and model name). |
401 | Authentication failed. | Check whether API_KEY is valid and whether Authorization uses the Bearer format. |
422 | Input or output moderation failed (blocked by the content safety policy). | The input or output triggers content safety moderation. Adjust the prompt or business policy. |
429 | The number of concurrent requests exceeds the limit. | The concurrency limit has been reached. Apply backoff and retry, and control call concurrency. |
500 | Internal error. | A server exception occurred. Retry the request. If the error persists, contact technical support and provide the request_id. |
Hy-Image-3.5-Preview image generation (text-to-image / image-to-image / multi-turn editing) โ
API description โ
Use the Chat/Messages protocol to input one or more context turns (text plus an optional reference image) and generate an image synchronously. If you do not pass size, the model determines the final width and height based on the prompt semantics and the generate_max_pixels area tier. If you pass size, the image is generated at the specified size, and the maximum supported resolution is 4096ร4096 (4K).
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v35-generation
Request parameters โ
2.1 Top-level parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model ID. Value: hy-image-v3.5-preview |
| messages | Required | array[object] | Content from multiple conversation turns, arranged from oldest to newest. The server uses the last role=user message in the array as the current image generation instruction, and passes the remaining objects through as historical context for multi-turn editing. For the element structure, see section 2.2 messages element structure. |
| size | Optional | string | Generation size, in the format ${width}x${height}.Constraints: 1. Both width and height are positive integers with a value range of [256, 8192]. 2. Width ร height (area) must not exceed 16777216, so the maximum supported resolution is 4096ร4096 (4K).If you do not pass this parameter or pass an empty string, the model determines the size based on the prompt semantics and generate_max_pixels.If you pass a specific value, the image is generated at the specified size. To generate 4K output, pass "size": "4096x4096" directly. |
| seed | Optional | integer | Generation seed. It is of the int64 type, with a range of [0, 2^63-1]. If set to 0 or not specified, the server assigns a random value. Negative values are rejected. |
| generate_max_pixels | Optional | integer | Specifies the target area of the generated image in pixels. It applies only when size is not passed.3 enumerated tiers are supported: 1048576 (1K, 1024ร1024), 2359296 (1.5K, default), 4194304 (2K).If you pass a non-enumerated intermediate value, it is classified into the closest area tier. Note: The highest tier of this parameter is 2K.To achieve a higher resolution, use size instead. |
| resize_max_pixels | Optional | integer | The maximum area (in pixels) of the input reference image. If the original image area is at or below the threshold, the image is passed through as is. If the original image area is larger than the threshold, it is scaled down proportionally to approach the threshold before being input to the model, which controls the context token consumption caused by large images (4K/6K). If not specified, the default value is 1048576 (1024ร1024). |
| session | Optional | string | The session ID used for consistent hash scheduling of the inference service. Multiple requests in the same session are routed to the same inference instance to increase the KV-cache hit rate. In multi-turn conversations, keep the same session value throughout the entire session. |
| footnote | Optional | string | Custom watermark content, up to 16 characters (counted with utf8.RuneCount regardless of whether it is Chinese or English), generated in the lower-right corner of the image. |
| use_search_tool | Optional | object | The external search enhancement switch. The structure is fixed as {"value": true} or {"value": false}. It is disabled by default. |
2.2 messages element structure โ
The structure of each element in messages[n] is as follows.
| Parameter | Required | Type | Description |
|---|---|---|---|
| role | Required | string | The role. Supported values: user / assistant / tool. The tool role appears only when a previous image generation result is fed back in as context for the next turn. |
| content | Optional | array[object] | The specific content of this turn. For the element structure, see section 2.3 "content element structure". It can be omitted if assistant does not send text and only triggers a tool call. |
| reasoning | Optional | string | When it is role=assistant, it is used only for multi-turn feedback input. Pass through the original thinking process text from the previous response as is. |
| tool_calls | Optional | array | When it is role=assistant, it is used only for multi-turn feedback input. The element structure follows the standard OpenAI tool_call, that is, {id, type:"function", function:{name, arguments}}, where arguments is a JSON string. |
| tool_call_id | Optional | string | When it is role=tool, it is used only for multi-turn feedback input. It must match the previous assistant.tool_calls[i].id exactly, character for character. |
2.3 content element structure โ
The structure of each element in messages[n].content[m] is as follows.
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Required | string | The content type, either text or image_url. |
| text | Optional | string | Used when it is type=text, indicating the specific text. |
| image_url | Optional | object | Used when it is type=image_url, with the structure {"url": "..."}. The http(s) public network URL or data:image/...;base64,... format is supported. Size per image: โค 20 MB. Total number of images: โค 20. If the limit is exceeded, the server automatically truncates from the furthest turn to the nearest turn. |
| is_generate | Optional | bool | Only when feeding generated image content back in as role=tool, pass true to mark that the image was generated by the generate tool in the previous turn. Do not pass this parameter in other scenarios. |
Request examples โ
Single-turn text-to-image (4K output)
# Text-to-Image
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v35-generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "hy-image-v3.5-preview",
"size": "4096x4096",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Draw a golden retriever running on the beach in warm evening light"
}
]
}
]
}'Single-turn generation based on a reference image (text + reference image)
# Reference-Based Image Generation
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v35-generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "hy-image-v3.5-preview",
"session": "demo-session-001",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Draw a cat in the style of this image"
},
{
"type": "image_url",
"image_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
}
}
]
}
]
}'Multi-turn editing (append the three messages in assembled_history from the previous response as is).
{
"model": "hy-image-v3.5-preview",
"session": "demo-session-001",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Draw a cat in the style of this image"
},
{
"type": "image_url",
"image_url": {
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I will use the generation tool to create the image as required."
}
],
"reasoning": "The user wants to draw a cat in the style of the dog...",
"tool_calls": [
{
"id": "generate@call_0",
"type": "function",
"function": {
"name": "generate",
"arguments": "{\"recaption\":\"a cat in similar style...\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "generate@call_0",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://result.example.com/generated-image.png"
}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "The image you requested has been completed."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Change the cat to a Ragdoll and the background to a fireplace"
}
]
}
]
}Response parameters โ
| Parameter | Type | Description |
|---|---|---|
| id | string | The trace ID of this request, unique across the entire stream. |
| object | string | A fixed value of image.chat.completion.chunk. |
| created | integer | A Unix timestamp in seconds. |
| model | string | The internal version identifier returned by the actual upstream service (for example, HY-Image-3.5-Preview-4090-Tob-vX.Y). It changes with upstream releases and is not the same as the hy-image-v3.5-preview you passed in the request body. It is for reference only, and we do not recommend that clients use this field to decide business branches. |
| round | integer | The LLM turn this frame belongs to, counted from 0. |
| choices | list | The fixed length is 1. |
| choices[0].delta | object | The primary image delivery object, with the structure {"type":"image", "image":{"url":"...", "width":..., "height":..., "source":"generate", "tool_call_id":"generate@call_0"}}.choices[0].delta.image.url is the final delivery URL of this image generation, and clients should read this field first. |
| choices[0].finish_reason | string | null | In a successful final frame it is usually null (after the upstream service sends the image as the last delta frame, it ends the stream directly without an additional completion frame).It is a non-null value such as error only when a content safety block/business error occurs.When determining whether a request succeeded, we recommend checking whether choices[0].delta.image.url exists instead of relying on finish_reason. |
| usage.total_tokens | integer | The total number of tokens consumed by this task (based on the upstream service; v3.5 currently does not distinguish between prompt and completion). |
| tokenhub_usage.total_tokens | integer | The token consumption used for billing/settlement on the TokenHub gateway side, usually consistent with usage.total_tokens. |
| request_id | string | A unique request identifier used for troubleshooting. |
| assembled_history | list | The message sequence assembled by the server for context injection in the next turn. Its structure is the same as the messages elements in the request body.It usually consists of the following 3 objects: 1.role=assistant (contains reasoning + tool_calls, describing the reasoning and tool calls of this turn) 2.role=tool (contains the intermediate URL of the image generated by the tool, with tool_call_id matching โ ) 3.role=assistant (contains only closing text such as "The image you requested is complete.") In multi-turn editing, append the array as is to messages of the next turn. |
| error | object | Included only in a failed final frame, using the OpenAI format {type, code, message, request_id}. |
choices[0].delta.image.url is the final image URL. assembled_history.content.image_url.url is the intermediate image URL used for subsequent editing. Preserve assembled_history for subsequent requests, and save the final result separately.
Response examples โ
Successful response:
{
"id": "1374200352-WandImage-085edfe2367d4a688f68e813af3665a5",
"object": "image.chat.completion.chunk",
"created": 1789720599,
"model": "HY-Image-3.5-Preview-4090-Tob-v1.2",
"round": 0,
"choices": [
{
"index": 0,
"delta": {
"type": "image",
"image": {
"url": "https://result.example.com/generated-image.png",
"width": 4096,
"height": 4096,
"source": "generate",
"tool_call_id": "generate@call_0"
}
},
"finish_reason": null
}
],
"usage": {
"total_tokens": 20000
},
"tokenhub_usage": {
"total_tokens": 20000
},
"request_id": "a1c00d07-041b-4daa-bae0-b7eabf2bc33a",
"assembled_history": [
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I will use the generation tool to create the image as required."
}
],
"reasoning": "The user instruction is \"dance\", which needs to be concretized into a specific visual representation...",
"tool_calls": [
{
"id": "generate@call_0",
"type": "function",
"function": {
"name": "generate",
"arguments": "{\"recaption\":\"...\",\"image_width\":\"855\",\"image_height\":\"1226\",\"source_image_indices_list\":\"[\\\"rdnd\\\"]\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "generate@call_0",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://result.example.com/generated-image.png"
}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "The image you requested has been completed."
}
]
}
]
}Failed response (for example, blocked by content moderation):
{
"id": "abc123",
"object": "image.chat.completion.chunk",
"created": 1785125530,
"model": "HY-Image-3.5-Preview-4090-Tob-v1.2",
"round": 0,
"choices": [
{
"index": 0,
"delta": {},
"finish_reason": "error"
}
],
"error": {
"type": "invalid_request_error",
"code": "content_filter",
"message": "input moderation rejected",
"request_id": "xxxxxxxx"
}
}The returned url is a temporary address that is valid for 12 hours. This address requires authentication, so accessing it directly from the browser address bar may be denied. We recommend downloading it in one of the following ways.
curl -o generated_image.png 'https://result.example.com/generated-image.png'Alternatively, use the HTTP client in your code to download and save it to local storage.
Error codes โ
| HTTP status code | Description | Handling recommendation |
|---|---|---|
400 | The request format is invalid. | Check the field types/values in the request body (for example, size constraints, message structure, and model name). |
401 | Authentication failed. | Check whether API_KEY is valid and whether Authorization uses the Bearer format. |
422 | Input or output moderation failed (blocked by the content safety policy). | The input or output triggers content safety moderation. Adjust the prompt or business policy. |
429 | The number of concurrent requests exceeds the limit. | The concurrency limit has been reached. Apply backoff and retry, and control call concurrency. |
500 | Internal error. | A server exception occurred. Retry the request. If the error persists, contact technical support and provide the request_id. |
Appendix โ
Hy-Image-3.0 preset size list โ
If you do not pass size, the model selects/predicts from the following 37 combinations. If you pass size, it must satisfy the constraints (width and height must be within the 512~2048 range, and their product must be at or below 1024ร1024). The format is "width x height".
2048 x 512 | 1984 x 512 | 1920 x 512 | 1856 x 512 |
|---|---|---|---|
1792 x 512 | 1728 x 512 | 1664 x 512 | 1600 x 512 |
1536 x 512 | 1472 x 576 | 1408 x 640 | 1344 x 704 |
1280 x 768 | 1216 x 832 | 1152 x 896 | 1088 x 960 |
1024 x 1024 | 960 x 1088 | 896 x 1152 | 832 x 1216 |
768 x 1280 | 704 x 1344 | 640 x 1408 | 576 x 1472 |
512 x 1536 | 512 x 1600 | 512 x 1664 | 512 x 1728 |
512 x 1792 | 512 x 1856 | 512 x 1920 | 512 x 1984 |
512 x 2048 | 768 x 1024 | 720 x 1280 | 1024 x 768 |
1280 x 720 | - | - | - |
Reference image input constraints โ
| Model | Supported formats | Size per image | Quantity |
|---|---|---|---|
| Hy-Image-3.0 | png / jpeg / jpg, image URL or Base64 supported | โค 10MB | 0~3 image |
| Hy-Image-3.5-Preview | png / jpeg / jpg, image URL or Base64 supported | โค 20MB | โค 20 images at most |
We recommend using a direct CDN link that requires no authentication. If the domain is on a private network or requires authentication, contact the TokenHub team to add it to the allowlist.
FAQ โ
1. How do I choose between the two models? โ
Hy-Image-3.0 is a traditional text-to-image API with a simple request body (prompt + size), suitable for single-turn batch image generation and cost-sensitive integration scenarios. Hy-Image-3.5-Preview uses the Chat/Messages protocol and supports multi-image input, multi-turn editing context, and thinking process rewriting, delivering better text rendering, realism, and editing consistency. It supports output up to 4K, making it suitable for professional visual content creation scenarios such as posters, UI design, and product image editing.
2. How do I generate 4K images? โ
Only Hy-Image-3.5-Preview supports this. Simply pass "size": "4096x4096". The width and height must be within the 256~8192 range, and the area must not exceed 16777216. As long as the area constraint is satisfied, other 4K-tier ratios such as "5461x3072" are also supported. Because the highest tier of generate_max_pixels is 2K (4194304), you must use the size parameter to generate 4K output.
3. How do I use size / generate_max_pixels together? (Hy-Image-3.5-Preview) โ
- Pass only
size: Forces generation at the exact width and height, overriding the model's autonomous decision. Use this approach for4Kscenarios. size+generate_max_pixels: The internal logic calculates the final width and height. It selects the size that is optimal for model performance while staying as close as possible to the ratio ofsizeand the area tier ofgenerate_max_pixels.- Pass only
generate_max_pixels: The default ratio is1:1, and the area is assigned to one of the1K,1.5K, or2Ktiers. - Pass neither: The model decides autonomously based on the prompt semantics (the default is the
1.5Ktier).
4. How do I pass the size parameter in Hy-Image-3.0? โ
The format is ${width}x${height} (for example, 1024x1024). Both width and height must be within the 512~2048 range, and the area must not exceed 1024ร1024. We recommend using a combination from the Hy-Image-3.0 preset size list in the appendix. If you do not pass it, you can describe the ratio in the prompt (for example, "landscape 16:9"), and the model automatically selects the closest preset size.
5. When does seed apply? How do I reproduce results? โ
Hy-Image-3.0: The value range is [1, 4294967295]. It applies only when the number of generated images is 1. If not passed or set to 0, a random seed is used.
Hy-Image-3.5-Preview: The value range is [0, 2^63-1]. If set to 0 or not passed, the server assigns a random seed. Negative values are rejected. To reproduce the same result, fix seed + prompt + size.
6. Should I disable revise (prompt rewriting)? (Hy-Image-3.0) โ
When rewriting is enabled, the model automatically rewrites and optimizes the prompt to improve image generation quality, which takes approximately 11 seconds. We recommend disabling this feature only if you have already implemented your own prompt rewriting logic. Otherwise, image generation quality may degrade significantly.
7. How do I assemble the context for multi-turn editing? (Hy-Image-3.5-Preview) โ
messages of the (N+1)th request = messages of turn N (including the first user message) + assembled_history of the turn N response (usually three messages: assistant + tool + assistant) + the new user message of the current turn. Because the server prepares objects that are ready to use for assembled_history, you do not need to aggregate SSE deltas yourself or assemble a multi-level nested JSON. For reference, see the connection format of the assistant / tool / assistant messages in the "Multi-turn editing" request example above.
8. Do generated image links expire? โ
Yes, they expire. The generation results of both models are temporary URLs valid for 12 hours. After generation succeeds, download and save them immediately. Hy-Image-3.0 uses data[n].url. Hy-Image-3.5-Preview uses choices[0].delta.image.url (the final delivery image for business use). To retain the historical context for the next editing turn, you can also save assembled_history.content.image_url.url (the intermediate artifact). All URLs are temporary signed URLs, so do not rely on them long term.
Supported specifications by version โ
| Version | Resolution | Ratio | Reference image |
|---|---|---|---|
hy-image-v3 | 512โ2048 px | Specify width / height | Up to 3 images |
hy-image-v3.5-preview | 256โ8192 px | Specify width / height | Up to 6 images |
Pixel area limits โ
| Version | Maximum pixel area | Prompt limit |
|---|---|---|
hy-image-v3 | 1024ร1024 | 8192 characters |
hy-image-v3.5-preview | 16,777,216 px / 4096ร4096 | 100k tokens |