Hy
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generation认证: Tokenhub API Key / Bearer
Hy Image 是腾讯混元的图片生成模型,支持文生图以及参考图编辑。3.5 Preview 支持利用对话历史进行连续编辑。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 解除护栏支持 | 不支持 |
Hy-Image-3.0 图片生成
API 说明
输入文本提示词以同步方式生成图片。若不传入 size 而在提示词中指定尺寸或比例,模型会从预设的 37 个 组合中选取最接近的一项。两者都不指定时,模型将自动预测。详情请参阅 附录:Hy-Image-3.0 预设尺寸列表。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v3-generation
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型 ID。取值:hy-image-v3 |
| prompt | 必填 | string | 用于生成图片的文本,最大长度为 8192 个字符。 |
| images | 选填 | array[string] | 参考图 0~3 个。支持图片 URL 或 Base64。格式:png / jpeg / jpg。单张图片大小:≤ 10 MB。 |
| size | 选填 | string | 生成尺寸,格式为 ${width}x${height}。限制条件:① 宽度与高度都必须在 [512, 2048] 像素范围内。② 宽度与高度的乘积(图片面积)不得超过 1024×1024 像素。不指定时,模型会从预设的 37 个 组合中选取/预测。详情请参阅 附录:Hy-Image-3.0 预设尺寸列表。 |
| seed | 选填 | integer | 生成种子,范围为 [1, 4294967295]。仅当生成图片数为 1 个 时生效。不指定或设置为 0 时,默认使用随机种子。 |
| footnote | 选填 | string | 自定义水印内容,无论中文还是英文都限制为 16 个字符,生成在图片右下角。 |
| revise | 选填 | boolean | 是否重写提示词。 |
请求示例
# 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"
}'响应参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id | string | 本次请求的 id。 |
| created | integer | Unix 时间戳。 |
| data | list | 返回的图片生成内容数组。 |
| data[n].url | string | 生成的图片 URL 为临时 URL,有效期为 12 小时。请立即下载并保存。 |
| data[n].revised_prompt | string | 重写后的提示词,仅在启用 revise 时返回。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
| tokenhub_usage | object | 令牌使用量。 |
| tokenhub_usage.total_tokens | integer | 本次任务消耗的令牌数,用于计费/结算。 |
响应示例
{
"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
}
}返回的 url 是有效期为 12 小时 的临时地址。该地址需要认证,因此直接在浏览器地址栏访问可能会被拒绝。建议采用以下方式之一下载。
curl -o generated_image.png 'https://aigc-image.cos.myqcloud.com/xxx/result.png'或者在代码中使用 HTTP 客户端下载并保存到本地存储。
错误码
| HTTP 状态码 | 说明 | 处理建议 |
|---|---|---|
400 | 请求格式有误。 | 请检查请求体中字段的类型/取值(例如 size 限制条件、prompt 长度、模型名称)。 |
401 | 认证失败。 | 请确认 API_KEY 是否有效、Authorization 是否使用 Bearer 格式。 |
422 | 输入或输出审核失败(被内容安全策略拦截)。 | 输入或输出触发了内容安全审核。请调整提示词或业务策略。 |
429 | 并发请求数超出限制。 | 已达到并发限制。请采用退避策略重试,并控制调用并发度。 |
500 | 内部错误。 | 服务端发生异常。请重试请求。若错误持续存在,请联系技术支持并提供 request_id。 |
Hy-Image-3.5-Preview 图片生成(文生图 / 图生图 / 多轮编辑)
API 说明
使用 Chat/Messages 协议输入一个或多个上下文轮次(文本 + 可选的参考图),以同步方式生成图片。若不传入 size,模型会依据提示词语义与 generate_max_pixels 面积等级来决定最终的宽度与高度。传入 size 时,将按指定尺寸生成图片,支持的最大分辨率为 4096×4096(4K)。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-image/v35-generation
请求参数
2.1 顶层参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型 ID。取值:hy-image-v3.5-preview |
| messages | 必填 | array[object] | 多个对话轮次的内容,按从旧到新的顺序排列。服务端会将数组中最后一条 role=user 消息作为当前的图片生成指令,其余对象则原样作为多轮编辑的历史上下文传入。元素结构请参阅章节 2.2 messages 元素结构。 |
| size | 选填 | string | 生成尺寸,格式为 ${width}x${height}。限制条件:1. 宽度与高度都为正整数,取值范围为 [256, 8192]。2. 宽度 × 高度(面积)不得超过 16777216,因此支持的最大分辨率为 4096×4096(4K)。若不传入该参数或传入空字符串,模型会依据提示词语义与 generate_max_pixels 来决定尺寸。若传入具体取值,则按指定尺寸生成图片。 如需生成 4K 输出,请直接传入 "size": "4096x4096"。 |
| seed | 选填 | integer | 生成种子,为 int64 类型,范围为 [0, 2^63-1]。设置为 0 或不指定时,服务端会分配随机值。负值将被拒绝。 |
| generate_max_pixels | 选填 | integer | 以像素为单位指定生成图片的目标面积。 仅在未传入 size 时生效。支持 3 个枚举等级:1048576(1K、1024×1024)、2359296(1.5K,默认值)、4194304(2K)。若传入非枚举的中间值,会被归类到最接近的面积等级。 注意:该参数的最高等级为 2K。如需实现更高分辨率,请改用 size。 |
| resize_max_pixels | 选填 | integer | 输入参考图的最大面积(像素)。若原图面积不超过该阈值,则将图片原样传入。若原图面积大于该阈值,则在输入模型前按比例缩小至接近阈值,以控制大尺寸图片(4K/6K)带来的上下文令牌消耗。不指定时,默认值为 1048576(1024×1024)。 |
| session | 选填 | string | 用于推理服务一致性哈希调度的会话 ID。同一会话的多次请求会被路由到同一推理实例,以提高 KV-cache 命中率。在多轮对话中,请在整个会话中保持相同的 session 取值。 |
| footnote | 选填 | string | 自定义水印内容,最多 16 个字符(无论中文还是英文,均按 utf8.RuneCount 计算),生成在图片右下角。 |
| use_search_tool | 选填 | object | 外部搜索增强开关。结构固定为 {"value": true} 或 {"value": false}。默认关闭。 |
2.2 messages 元素结构
messages[n] 中各元素的结构如下。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| role | 必填 | string | 角色。支持的取值:user / assistant / tool。tool 角色仅在将上一次图片生成结果作为下一轮上下文重新输入时出现。 |
| content | 选填 | array[object] | 本轮的具体内容。元素结构请参阅章节 2.3「content 元素结构」。若 assistant 不发送文本而仅触发工具调用,则可省略。 |
| reasoning | 选填 | string | 为 role=assistant 时,仅用于多轮回传。请将上一次响应的原始思考过程文本原样传入。 |
| tool_calls | 选填 | array | 为 role=assistant 时,仅用于多轮回传。元素结构遵循标准 OpenAI tool_call,即 {id, type:"function", function:{name, arguments}},其中 arguments 为 JSON 字符串。 |
| tool_call_id | 选填 | string | 为 role=tool 时,仅用于多轮回传。必须与上一次的 assistant.tool_calls[i].id 逐字符完全一致。 |
2.3 content 元素结构
messages[n].content[m] 中各元素的结构如下。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| type | 必填 | string | 内容类型,为 text 或 image_url。 |
| text | 选填 | string | 为 type=text 时使用,表示具体的文本。 |
| image_url | 选填 | object | 为 type=image_url 时使用,结构为 {"url": "..."}。支持 http(s) 公网 URL 或 data:image/...;base64,... 格式。单张图片大小:≤ 20 MB。图片总数:≤ 20。超出限制时,服务端会按从最远轮次到最近轮次的顺序自动截断。 |
| is_generate | 选填 | bool | 仅在将生成的图片内容作为 role=tool 重新输入时,传入 true 以标记该图片由上一轮的 generate 工具生成。其他场景请勿传入该参数。 |
请求示例
单轮文生图(4K 输出)
# 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"
}
]
}
]
}'单轮基于参考图生成(文本 + 参考图)
# 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"
}
}
]
}
]
}'多轮编辑(将上一次响应 assembled_history 中的三条消息原样追加)。
{
"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"
}
]
}
]
}响应参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id | string | 本次请求的追踪 ID,在整个流中唯一。 |
| object | string | 固定值 image.chat.completion.chunk。 |
| created | integer | 以秒为单位的 Unix 时间戳。 |
| model | string | 实际上游服务返回的内部版本标识符(例如 HY-Image-3.5-Preview-4090-Tob-vX.Y)。它会随上游发布而变化,与请求体中传入的 hy-image-v3.5-preview 并不相同。仅供参考,不建议客户端将该字段用于业务分支判断。 |
| round | integer | 该帧所属的 LLM 轮次,从 0 开始计数。 |
| choices | list | 固定长度为 1。 |
| choices[0].delta | object | 主要的图片交付对象,结构为 {"type":"image", "image":{"url":"...", "width":..., "height":..., "source":"generate", "tool_call_id":"generate@call_0"}}。choices[0].delta.image.url 是本次图片生成的最终交付 URL,客户端应优先读取该字段。 |
| choices[0].finish_reason | string | null | 在成功的最终帧中通常为 null(上游服务将图片作为最后一个 delta 帧发送后,不再追加完成帧而直接结束流)。仅在发生内容安全拦截/业务错误时,才为 error 这类非 null 的值。判断请求是否成功时,建议检查 choices[0].delta.image.url 是否存在,而非依据 finish_reason。 |
| usage.total_tokens | integer | 本次任务消耗的总令牌数(以上游服务为准,v3.5 目前不区分 prompt/completion)。 |
| tokenhub_usage.total_tokens | integer | 用于 TokenHub 网关侧计费/结算的令牌消耗量,通常与 usage.total_tokens 一致。 |
| request_id | string | 用于排查问题的唯一请求标识符。 |
| assembled_history | list | 服务端为下一轮上下文注入而组装的消息序列,结构与请求体中的 messages 元素相同。通常由以下 3 个对象组成:1.role=assistant(包含 reasoning + tool_calls,描述本轮的推理与工具调用)2.role=tool(包含工具生成图片的中间 URL,且 tool_call_id 与 ① 一致)3.role=assistant(仅包含「您请求的图片已完成。」这类收尾文本)在多轮编辑中,请将该数组原样追加到下一轮的 messages中。 |
| error | object | 仅在失败的最终帧中包含,采用 OpenAI 格式 {type, code, message, request_id}。 |
choices[0].delta.image.url 是最终图片 URL。assembled_history.content.image_url.url 是用于后续编辑的中间图片 URL。后续请求中请保留 assembled_history,并将最终结果另行保存。
响应示例
成功响应:
{
"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."
}
]
}
]
}失败响应(例如被内容审核拦截):
{
"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"
}
}返回的 url 是有效期为 12 小时 的临时地址。该地址需要认证,因此直接在浏览器地址栏访问可能会被拒绝。建议采用以下方式之一下载。
curl -o generated_image.png 'https://result.example.com/generated-image.png'或者在代码中使用 HTTP 客户端下载并保存到本地存储。
错误码
| HTTP 状态码 | 说明 | 处理建议 |
|---|---|---|
400 | 请求格式有误。 | 请检查请求体中字段的类型/取值(例如 size 限制条件、消息结构、模型名称)。 |
401 | 认证失败。 | 请确认 API_KEY 是否有效、Authorization 是否使用 Bearer 格式。 |
422 | 输入或输出审核失败(被内容安全策略拦截)。 | 输入或输出触发了内容安全审核。请调整提示词或业务策略。 |
429 | 并发请求数超出限制。 | 已达到并发限制。请采用退避策略重试,并控制调用并发度。 |
500 | 内部错误。 | 服务端发生异常。请重试请求。若错误持续存在,请联系技术支持并提供 request_id。 |
附录
Hy-Image-3.0 预设尺寸列表
若不传入 size,模型会从以下 37 个组合中选取/预测。若传入 size,则必须满足限制条件(宽度与高度需在 512~2048 范围内,且乘积不超过 1024×1024)。格式为「宽 x 高」。
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 | - | - | - |
参考图输入限制条件
| 模型 | 支持格式 | 单张图片大小 | 数量 |
|---|---|---|---|
| Hy-Image-3.0 | png / jpeg / jpg,支持图片 URL 或 Base64 | ≤ 10MB | 图片 0~3 个 |
| Hy-Image-3.5-Preview | png / jpeg / jpg,支持图片 URL 或 Base64 | ≤ 20MB | ≤ 最多 20 个 张图片 |
建议使用无需认证的直连 CDN 链接。若域名位于私有网络中或需要认证,请联系 TokenHub 团队将其加入允许列表。
常见问题
1. 两个模型之间该如何选择?
Hy-Image-3.0 是请求体(prompt + size)较为简单的传统文生图 API,适合单轮批量生成图片以及对成本敏感的集成场景。Hy-Image-3.5-Preview 采用 Chat/Messages 协议,支持多图输入、多轮编辑上下文与思考过程重写,在文字表现力、真实感和编辑一致性方面更出色。它支持最高 4K 输出,因此适合海报、UI 设计、商品图编辑等专业视觉内容创作场景。
2. 如何生成 4K 图片?
仅 Hy-Image-3.5-Preview 支持。传入 "size": "4096x4096" 即可。宽度与高度需在 256~8192 范围内,且面积不得超过 16777216。只要满足面积限制条件,也支持 "5461x3072" 这类其他 4K 级比例。由于 generate_max_pixels 的最高等级为 2K(4194304),因此如需生成 4K 输出,必须使用 size 参数。
3. size / generate_max_pixels 该如何配合使用?(Hy-Image-3.5-Preview)
- 仅传入
size:强制按精确的宽度与高度生成,覆盖模型的自主决定。4K场景请采用这种方式。 size+generate_max_pixels:由内部逻辑计算最终的宽度与高度。会在尽可能贴近size的比例与generate_max_pixels的面积等级的同时,选取对模型性能最优的尺寸。- 仅传入
generate_max_pixels:默认比例为1:1,面积会被分配到1K、1.5K、2K等级之一。 - 两者都不传入:由模型依据提示词语义自主决定(默认为
1.5K等级)。
4. 在 Hy-Image-3.0 中该如何传入 size 参数?
格式为 ${width}x${height}(例如 1024x1024)。宽度与高度都需在 512~2048 范围内,且面积不得超过 1024×1024。建议使用附录「Hy-Image-3.0 预设尺寸列表」中的组合。若不传入,则可在提示词中描述比例(例如「横版 16:9」),模型会自动选取最接近的预设尺寸。
5. seed 何时生效?如何复现结果?
Hy-Image-3.0:取值范围为 [1, 4294967295]。仅当生成图片数为 1 个 时生效。不传入或设置为 0 时,将使用随机种子。
Hy-Image-3.5-Preview:取值范围为 [0, 2^63-1]。设置为 0 或不传入时,服务端会随机分配种子。负值将被拒绝。如需复现相同结果,请固定 seed + prompt + size。
6. 是否应该关闭 revise(提示词重写)?(Hy-Image-3.0)
启用重写后,模型会自动重写并优化提示词以提升图片生成质量,大约需要 11 秒。仅在您已自行实现提示词重写逻辑时,才建议关闭该功能。否则,图片生成质量可能明显下降。
7. 多轮编辑的上下文该如何组装?(Hy-Image-3.5-Preview)
第 (N+1) 次请求的 messages = 第 N 轮的 messages(含第一条 user 消息)+ 第 N 轮响应的 assembled_history(通常为 assistant + tool + assistant 三条消息)+ 当前轮的新 user 消息。由于服务端已准备好可直接使用的对象供 assembled_history 使用,因此无需自行聚合 SSE delta 或组装多层嵌套的 JSON。如需参考,请查看上文「多轮编辑」请求示例中 assistant / tool / assistant 消息的衔接格式。
8. 生成的图片链接会过期吗?
会过期。两个模型的生成结果都是有效期为 12 小时 的临时 URL。生成成功后请立即下载并保存。Hy-Image-3.0 使用 data[n].url。Hy-Image-3.5-Preview 使用 choices[0].delta.image.url(面向业务的最终交付图片)。如需保留用于下一轮编辑的历史上下文,也可以保存 assembled_history.content.image_url.url(中间产物)。所有 URL 都是临时签名 URL,请勿长期依赖。
各版本支持规格
| 版本 | 分辨率 | 比例 | 参考图 |
|---|---|---|---|
hy-image-v3 | 512–2048 px | 指定 width / height | 最多 3 张 |
hy-image-v3.5-preview | 256–8192 px | 指定 width / height | 最多 6 张 |
像素面积限制
| 版本 | 最大像素面积 | 提示词上限 |
|---|---|---|
hy-image-v3 | 1024×1024 | 8192 个字符 |
hy-image-v3.5-preview | 16,777,216 px / 4096×4096 | 100k 个令牌 |