hy-image-v3) through TokenHub: generate images synchronously from text prompts, with support for custom dimensions, generation seeds, automatic prompt rewriting, and image watermark footnotes.Model Name | model Parameter Value | Supported Capability | Prompt Limit | Size Range | Brief Description |
Hy-Image-3.0 | hy-image-v3 | Text-to-image/reference-based image generation (synchronous) | 8192 characters | Width and height [512, 2048], area ≤ 1024×1024 | Supports automatic prompt rewriting, 37 preset sizes, and custom watermark footnotes. |
Hy-Image-3.5-Preview | hy-image-v3.5-preview | Text-to-image/reference-based image generation/multi-turn editing (synchronous) | 100k tokens | Width and height ∈ [256, 8192], area ≤ 16777216 (4K, 4096×4096) | Uses the Chat/Messages protocol, supports multimodal input, multi-turn editing context, external search enhancement, automatic size determination by area tier, and up to 4K output. |
size is not passed and a size or aspect ratio is specified in the prompt, the model selects the closest match from 37 preset combinations. If neither is specified, the model predicts automatically. For details, see Appendix: Hy-Image-3.0 Preset Size List.POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generationParameter Name | Required | Type | Description |
model | Yes | string | Model ID. Value: hy-image-v3 |
prompt | Yes | string | Text used for image generation, with a length of up to 8192 characters. |
images | No | array[string] | Reference images, 0 to 3. Supports image URLs or Base64. Format: png / jpeg / jpg. Size per image: ≤ 10 MB. |
size | No | string | Generated size, format: ${width}x${height}.Constraints: ① Width and height are both within the range of [512, 2048] pixels; ② The product of width and height (image area) does not exceed 1024×1024 pixels. If not specified, the model selects/predicts from 37 preset combinations. For details, see Appendix: Hy-Image-3.0 Preset Size List. |
seed | No | integer | Generation seed, range: [1, 4294967295]. Takes effect only when the number of generated images is 1. If not specified or set to 0, a random seed is used by default. |
footnote | No | string | Custom watermark content, limited to 16 characters (regardless of Chinese or English), generated in the lower right corner of the image. |
revise | No | boolean | Whether to rewrite the prompt. |
# Text-to-Imagecurl -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"}'
Parameter Name | Type | Description |
id | string | id of this request. |
created | integer | Unix timestamp. |
data | list | Array of returned image generation content. |
data[n].url | string | The generated image URL is temporary and valid for 12 hours. Download and save it promptly. |
data[n].revised_prompt | string | The revised prompt, returned only when revise is enabled. |
request_id | string | Unique request identifier used for troubleshooting. |
tokenhub_usage | object | Token usage consumption. |
tokenhub_usage.total_tokens | integer | Number of tokens consumed by this task, used for billing/reconciliation. |
{"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}}
curl -o generated_image.png 'https://aigc-image.cos.myqcloud.com/xxx/result.png'
HTTP Status Code | Description | Handling Recommendation |
400 | The request format is incorrect. | Check the field types/values in the request body (such as size constraints, prompt length, and model name). |
401 | Authentication failed. | Check whether the API_KEY is valid and whether Authorization uses the Bearer format. |
422 | Input or output moderation failed (blocked by content safety). | 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 is reached. Retry with backoff and control the concurrency of calls. |
500 | Internal error. | A server exception occurs. Retry the request. If failures persist, contact technical support and provide the request_id. |
size is not passed, the model determines the final width and height based on the prompt semantics and the generate_max_pixels area tier. If size is passed, the image is generated at the specified size, with a maximum supported resolution of 4096×4096 (4K).POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v35-generationParameter Name | Required | Type | Description |
model | Yes | string | Model ID. Value: hy-image-v3.5-preview |
messages | Yes | array[object] | Content of multiple conversation turns, arranged in chronological order from oldest to newest. The server takes the last message with role=user in the array as the current image generation instruction, and passes through the remaining objects as historical context for multi-turn editing. For element structure, see section 2.2 messages element structure. |
size | No | string | Generated size, format: ${width}x${height}.Constraints: 1. Both width and height are positive integers, with a value range of [256, 8192]. 2. The width × height (area) must not exceed 16777216, which means the maximum supported resolution is 4096×4096 (4K). If this parameter is not passed or an empty string is passed, the model determines the size based on the prompt semantics and generate_max_pixels. If a specific value is passed, the image is generated at the specified size. To generate a 4K output, directly pass "size": "4096x4096". |
seed | No | integer | Generation seed, int64 type, range: [0, 2^63-1]. If set to 0 or not specified, the server assigns a random value. Negative values are rejected. |
generate_max_pixels | No | integer | Specifies the target area of the generated image in pixels. Takes effect only when size is not passed.Supports 3 enumeration levels: 1048576 (1K, 1024×1024), 2359296 (1.5K, default), and 4194304 (2K). If a non-enumeration intermediate value is passed, it is classified to the nearest area level.Note: The highest level of this parameter is 2K. To achieve a higher resolution, use size instead. |
resize_max_pixels | No | integer | Maximum area of the input reference image in pixels. If the original image area is less than or equal to the threshold, the image is passed through as is. If the original image area is greater than the threshold, the image is proportionally scaled to approximately the threshold before being fed into the model, to control context token consumption caused by large images (4K/6K). If not specified, the default value is 1048576 (1024×1024). |
session | No | string | Session ID, used for consistent hash scheduling in inference services. Multiple requests within the same session are routed to the same inference instance, improving the KV-cache hit rate. For multi-turn conversations, keep the same session value throughout the entire session. |
footnote | No | string | Custom watermark content, up to 16 characters (calculated by utf8.RuneCount, regardless of Chinese or English), generated in the lower right corner of the image. |
use_search_tool | No | object | External search enhancement switch. The structure is fixed as {"value": true} or {"value": false}. Disabled by default. |
Parameter Name | Required | Type | Description |
role | Yes | string | Role. Supported values: user / assistant / tool.The tool role appears only when feeding the previous image generation result back as the context for the next round. |
content | No | array[object] | The specific content of this round. For the element structure, see section 2.3 "content Element Structure". assistant can be omitted when only triggering tool calls without sending text. |
reasoning | No | string | Used only for multi-round backfeeding when role=assistant. Passes through the original chain-of-thought text from the previous response. |
tool_calls | No | array | Used only for multi-round backfeeding when role=assistant. The element structure follows the standard OpenAI tool_call: {id, type:"function", function:{name, arguments}}, where arguments is a JSON string. |
tool_call_id | No | string | Used only for multi-round backfeeding when role=tool. Must match the previous assistant.tool_calls[i].id character by character. |
Parameter Name | Required | Type | Description |
type | Yes | string | Content type, text or image_url. |
text | No | string | Used when type=text, indicating specific text. |
image_url | No | object | Used when type=image_url, with the structure {"url": "..."}.Supports http(s) public network URLs or data:image/...;base64,... format. Size per image: ≤ 20 MB. Total number of images: ≤ 20. If the limit is exceeded, the server automatically truncates by round from farthest to nearest. |
is_generate | No | bool | Fill in true only when feeding the generated image content back with role=tool, marking it as the image produced by the generate tool in the previous round. Do not pass this parameter in other scenarios. |
# Text-to-Imagecurl -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" }]}]}'
# Reference-Based Image Generationcurl -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://your-domain/dog.png" } }]}]}'
assembled_history in 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://your-domain/dog.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": "http://hunyuan-image-result-tob-1258344703.cos.ap-guangzhou.myqcloud.com/xxx/cat.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" }]}]}
Parameter Name | Type | Description |
id | string | Trace ID of this request, unique within the entire stream. |
object | string | Fixed image.chat.completion.chunk. |
created | integer | Unix timestamp in seconds. |
model | string | 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 equivalent to hy-image-v3.5-preview passed in the request body. It is for reference only, and clients are not advised to use this field for business branch decisions. |
round | integer | LLM round to which this frame belongs, counted from 0. |
choices | list | Fixed length of 1. |
choices[0].delta | object | Main image carrier, 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 often null (the upstream service sends the image as the last delta frame and then closes the stream directly without sending an additional completion frame). Only in cases of content security interception / business errors will it be a non-null value such as error.To determine whether the request is successful, the business side is advised to check whether choices[0].delta.image.url exists, rather than finish_reason. |
usage.total_tokens | integer | Total number of tokens consumed by this task (based on the upstream service; v3.5 currently does not split prompt/completion). |
tokenhub_usage.total_tokens | integer | token consumption used for billing/reconciliation on the TokenHub gateway side, generally consistent with usage.total_tokens. |
request_id | string | Unique request identifier used for troubleshooting. |
assembled_history | list | Message sequence assembled by the server for the next round of context injection, with a structure identical to the messages element in the request body, typically consisting of 3 objects:1. role=assistant (contains reasoning + tool_calls, describing the reasoning and tool calls for this round)2. role=tool (contains the intermediate URL of the image generated by the tool, with tool_call_id consistent with ①)3. role=assistant (contains only closing text, such as "The image you requested is complete.")For multi-turn editing, directly append the array as is to the next round of messages. |
error | object | Only carried in failed final frames, in OpenAI style {type, code, message, request_id}. |
choices[0].delta.image.url: Final delivered image URL (hosted at aigc-output-image-file-*.cos.ap-guangzhou.myqcloud.com), which already includes watermarking/post-processing. We recommend that your business read this field first as the final image.assembled_history[].content[].image_url.url (role=tool): Intermediate artifact URL (hosted at hunyuan-image-result-tob-*.cos.ap-guangzhou.myqcloud.com), which provides reusable historical context for the next round of multi-round editing. It must be appended during multi-round editing.{"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://aigc-output-image-file-1326893053.cos.ap-guangzhou.myqcloud.com/xxx/main.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": "http://hunyuan-image-result-tob-1258344703.cos.ap-guangzhou.myqcloud.com/text2image2/strategy/upload/xxx.png?..."}}]},{"role": "assistant","content": [{ "type": "text", "text": "The image you requested has been completed." }]}]}
{"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"}}
curl -o generated_image.png 'https://aigc-output-image-file-1326893053.cos.ap-guangzhou.myqcloud.com/xxx/main.png?...'
HTTP Status Code | Description | Handling Recommendation |
400 | The request format is incorrect. | Check the field types/values in the request body, such as size constraints, message structure, and model name. |
401 | Authentication failed. | Check whether the API_KEY is valid and whether Authorization uses the Bearer format. |
422 | Input or output moderation failed (blocked by content safety). | 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 is reached. Retry with backoff and control the concurrency of calls. |
500 | Internal error. | A server exception occurs. Retry the request. If failures persist, contact technical support and provide the request_id. |
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 | - | - | - |
Model | Supported Format | Single Image Size | Quantity |
Hy-Image-3.0 | png / jpeg / jpg, supports image URLs or Base64 | ≤ 10MB | 0 to 3 images |
Hy-Image-3.5-Preview | png / jpeg / jpg, supports image URLs or Base64 | ≤ 20MB | ≤ Up to 20 images |
"size": "4096x4096". The width and height must be within the range of 256 to 8192, and the area must not exceed 16777216. Other 4K-level aspect ratios (such as "5461x3072") are also supported as long as they satisfy the area constraint. Note that the highest tier of generate_max_pixels is 2K (4194304), so to generate 4K output, you must use the size parameter.size: forces image generation at the exact width and height, overriding the model's autonomous decision. Use this method for 4K scenarios.size + generate_max_pixels: The final width and height are calculated by internal logic, which aims to stay as close as possible to the aspect ratio of size and the area tier of generate_max_pixels, selecting the optimal dimensions for model performance.generate_max_pixels: The default aspect ratio is 1:1, and the area is assigned to one of the 1K, 1.5K, or 2K tiers.${width}x${height} (for example, 1024x1024). Both width and height must be within the range of 512 to 2048, and the area must not exceed 1024×1024. We recommend using the combinations in the appendix: Hy-Image-3.0 Preset Size List. If not passed, you can describe the aspect ratio in the prompt (for example, "landscape 16:9"), and the model will automatically select the closest preset size.messages in the (N+1)-th request = the messages from the N-th round (including the first user message) + the assembled_history from the N-th round response (typically three messages: assistant + tool + assistant) + the new user message for the current round. You do not need to aggregate SSE deltas yourself or assemble multi-level nested JSON, as the server has already prepared a ready-to-use object in assembled_history. For reference, see the concatenation format of the assistant / tool / assistant messages in the "Multi-Round Editing" request example above.data[n].url. For Hy-Image-3.5-Preview, use choices[0].delta.image.url (the final delivered image for business use). If you need to retain historical context for the next round of editing, you can also save assembled_history[].content[].image_url.url (the intermediate product). All URLs are temporary signed URLs, so do not rely on them long-term.Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback