跳到内容

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是否重写提示词。

请求示例 ​

bash
# 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"
}'

响应参数 ​

参数类型说明
idstring本次请求的 id。
createdintegerUnix 时间戳。
datalist返回的图片生成内容数组。
data[n].urlstring生成的图片 URL 为临时 URL,有效期为 12 小时。请立即下载并保存。
data[n].revised_promptstring重写后的提示词,仅在启用 revise 时返回。
request_idstring用于排查问题的唯一请求标识符。
tokenhub_usageobject令牌使用量。
tokenhub_usage.total_tokensinteger本次任务消耗的令牌数,用于计费/结算。

响应示例 ​

json
{
  "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 小时 的临时地址。该地址需要认证,因此直接在浏览器地址栏访问可能会被拒绝。建议采用以下方式之一下载。

bash
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 输出)

bash
# 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"
        }
      ]
    }
  ]
}'

单轮基于参考图生成(文本 + 参考图)

bash
# 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 中的三条消息原样追加)。

json
{
  "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"
        }
      ]
    }
  ]
}

响应参数 ​

参数类型说明
idstring本次请求的追踪 ID,在整个流中唯一。
objectstring固定值 image.chat.completion.chunk。
createdinteger以秒为单位的 Unix 时间戳。
modelstring实际上游服务返回的内部版本标识符(例如 HY-Image-3.5-Preview-4090-Tob-vX.Y)。它会随上游发布而变化,与请求体中传入的 hy-image-v3.5-preview 并不相同。仅供参考,不建议客户端将该字段用于业务分支判断。
roundinteger该帧所属的 LLM 轮次,从 0 开始计数。
choiceslist固定长度为 1。
choices[0].deltaobject主要的图片交付对象,结构为 {"type":"image", "image":{"url":"...", "width":..., "height":..., "source":"generate", "tool_call_id":"generate@call_0"}}。
choices[0].delta.image.url 是本次图片生成的最终交付 URL,客户端应优先读取该字段。
choices[0].finish_reasonstring | null在成功的最终帧中通常为 null(上游服务将图片作为最后一个 delta 帧发送后,不再追加完成帧而直接结束流)。
仅在发生内容安全拦截/业务错误时,才为 error 这类非 null 的值。
判断请求是否成功时,建议检查 choices[0].delta.image.url 是否存在,而非依据 finish_reason。
usage.total_tokensinteger本次任务消耗的总令牌数(以上游服务为准,v3.5 目前不区分 prompt/completion)。
tokenhub_usage.total_tokensinteger用于 TokenHub 网关侧计费/结算的令牌消耗量,通常与 usage.total_tokens 一致。
request_idstring用于排查问题的唯一请求标识符。
assembled_historylist服务端为下一轮上下文注入而组装的消息序列,结构与请求体中的 messages 元素相同。
通常由以下 3 个对象组成:1.
role=assistant(包含 reasoning + tool_calls,描述本轮的推理与工具调用)2.
role=tool(包含工具生成图片的中间 URL,且 tool_call_id 与 ① 一致)3.
role=assistant(仅包含「您请求的图片已完成。」这类收尾文本)在多轮编辑中,请将该数组原样追加到下一轮的 messages中。
errorobject仅在失败的最终帧中包含,采用 OpenAI 格式 {type, code, message, request_id}。

choices[0].delta.image.url 是最终图片 URL。assembled_history.content.image_url.url 是用于后续编辑的中间图片 URL。后续请求中请保留 assembled_history,并将最终结果另行保存。

响应示例 ​

成功响应:

json
{
  "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."
        }
      ]
    }
  ]
}

失败响应(例如被内容审核拦截):

json
{
  "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 小时 的临时地址。该地址需要认证,因此直接在浏览器地址栏访问可能会被拒绝。建议采用以下方式之一下载。

bash
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 5121984 x 5121920 x 5121856 x 512
1792 x 5121728 x 5121664 x 5121600 x 512
1536 x 5121472 x 5761408 x 6401344 x 704
1280 x 7681216 x 8321152 x 8961088 x 960
1024 x 1024960 x 1088896 x 1152832 x 1216
768 x 1280704 x 1344640 x 1408576 x 1472
512 x 1536512 x 1600512 x 1664512 x 1728
512 x 1792512 x 1856512 x 1920512 x 1984
512 x 2048768 x 1024720 x 12801024 x 768
1280 x 720---

参考图输入限制条件 ​

模型支持格式单张图片大小数量
Hy-Image-3.0png / jpeg / jpg,支持图片 URL 或 Base64≤ 10MB图片 0~3 个
Hy-Image-3.5-Previewpng / 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-v3512–2048 px指定 width / height最多 3 张
hy-image-v3.5-preview256–8192 px指定 width / height最多 6 张

像素面积限制 ​

版本最大像素面积提示词上限
hy-image-v31024×10248192 个字符
hy-image-v3.5-preview16,777,216 px / 4096×4096100k 个令牌

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages