帮你快速理解、总结文档立即下载
文档中心>大模型服务平台 TokenHub>调用指南>图像生成模型>Hy 生图调用指南

Hy 生图调用指南

最近更新时间：2026-08-07 17:32:30
我的收藏

本页目录：

概述

混元生图是腾讯混元推出的图像生成模型系列。本文介绍如何通过 TokenHub 调用混元图片生成模型 Hy-Image-3.0（hy-image-v3）：凭文本提示词同步生成图片，支持自定义尺寸、生成种子、prompt 自动改写与图片水印脚注。
说明：
本接口为同步调用：一次请求直接返回生成结果，无需提交任务与轮询。

前提条件

已 注册腾讯云 账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。
说明：
下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

模型列表

模型名称
model 参数值
支持能力
提示词上限
尺寸范围
简要说明
Hy-Image-3.0
hy-image-v3
文生图/参考生图（同步）
8192 字符
宽高 [512, 2048]，面积 ≤ 1024×1024
支持 prompt 自动改写、37 组预设尺寸、自定义水印脚注。

文生图

1. 接口描述

输入文本提示词，同步生成图片。未传 size 时，若 prompt 中指定了尺寸或比例，模型从37个预设组合中选择最接近的一个；若未指定则自动预测，详情请参见 附录：预设尺寸列表。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/hunyuan-image/v3-generation

2. 输入参数

参数名
必选
类型
描述
model
是
string
模型 ID。取值：hy-image-v3
prompt
是
string
生成图片使用的文本。字符串长度不超过8192字符。
images
否
array[string]
参考图片，0~3 张。支持图片 URL 或 Base64。格式 png/jpeg/jpg；大小不超过10MB。
size
否
string
生成尺寸，格式 ${宽}x${高}。
约束：
1. 宽、高均在 [512, 2048] 像素范围内。
2. 宽高乘积（图像面积）不超过 1024×1024 像素。
不传时模型从 37 个预设组合中选择/预测，详情请参见 附录：预设尺寸列表。
seed
否
integer
生成种子。范围 [1, 4294967295]，仅当生成图片数为1时生效；不传或为0时默认随机。
footnote
否
string
业务自定义水印内容，限制16个字符长度（不区分中英文），生成在图片右下角。
revise
否
boolean
是否对 prompt 改写。

3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/hunyuan-image/v3-generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "hy-image-v3",
  "prompt": "一只橙色小猫在窗台上看向镜头",
  "size": "1024x1024"
}'

4. 输出参数

参数名
类型
描述
id
string
此次请求的 id。
created
integer
Unix 时间戳。
data
list
返回的图片生成内容数组。
data[n].url
string
生成的图片地址，为临时地址，有效期 12 小时，请及时下载转存。
data[n].revised_prompt
string
改写后的 prompt（开启 revise 时返回）。
request_id
string
唯一请求标识，用于排查问题。
usage
object
用量消耗。
usage.total_tokens
integer
本次任务消耗的 token 数，用于计费/对账。

5. 响应示例

{
  "id": "4-WandImage-a786becfdc80433b8cff4aa344c8fd3d",
  "created": 1785125529,
  "data": [
    {
      "url": "https://aigc-image.cos.myqcloud.com/xxx/result.png",
      "revised_prompt": "一只橙色小猫坐在洒满阳光的窗台上，转身看向镜头，毛发细节清晰，背景虚化"
    }
  ],
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2",
  "usage": {
    "total_tokens": 1024
  }
}

6. 错误码

HTTP 状态码
说明
处理建议
400
请求格式有误
检查请求体字段类型/取值（如 size 约束、prompt 长度、模型名）。
401
鉴权不通过
检查 API_KEY 是否有效、Authorization 是否为 Bearer 格式。
422
输入、输出审核不通过（内容安全拦截）
输入或输出触发内容安全审核，需调整 prompt 或业务策略。
429
请求并发数超过限额
触发并发上限，建议退避重试并控制调用并发。
500
内部错误
服务端异常，可重试；持续失败请联系技术支持并附 request_id。

附录

预设尺寸列表

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
-
-

常见问题

1. size 参数怎么传？

size 格式为 ${宽}x${高}（例如 1024x1024），宽高均需在 [512, 2048] 范围内且面积不超过 1024×1024。建议直接使用 附录：预设尺寸列表 中的组合；不传时可在 prompt 中描述比例（例如“横版 16:9”），模型会自动选择最接近的预设尺寸。

2. revise（prompt 改写）要关闭吗？

开启改写时，模型会自动改写优化 prompt 以提升生图效果，改写约耗时11秒。仅当您已自行实现 prompt 改写逻辑时才建议关闭，否则对生图效果影响较大。

3. seed 什么时候生效？

仅在生成图片数为1时生效，范围 [1, 4294967295]；不传或传0时使用随机种子。需要复现同一结果时，请固定 seed 与 prompt。

4. 生成结果图片链接会过期吗？

会过期。生成结果为临时地址，有效期12小时，请在生成成功后及时下载 data[n].url 中的图片并转存到自有存储，切勿长期依赖该链接。
中国站