| Parameter 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. |
| Parameter 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. |
| 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}. |
| 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 | - | - | - |