hunyuan-image（浑源图像）

Hunyuan Image - 腾讯混元生图

基于腾讯混元大模型的AI图像生成服务。

功能

• 文本生成图像
• 支持多种分辨率
• 支持多种绘画风格
• 支持参考图引导
• 支持超分增强

前置要求

1. 安装Python依赖

pip install tencentcloud-sdk-python

2. 配置腾讯云密钥

需要的环境变量：

• TENCENT_SECRET_ID - 腾讯云SecretId
• TENCENT_SECRET_KEY - 腾讯云SecretKey

# Windows PowerShell - 永久设置
[Environment]::SetEnvironmentVariable("TENCENT_SECRET_ID", "your-secret-id", "User")
[Environment]::SetEnvironmentVariable("TENCENT_SECRET_KEY", "your-secret-key", "User")

# 或临时设置（当前会话）
$env:TENCENT_SECRET_ID = "your-secret-id"
$env:TENCENT_SECRET_KEY = "your-secret-key"

获取密钥步骤：

1. 访问 https://console.cloud.tencent.com/cam/capi
2. 点击「新建密钥」
3. 复制 SecretId 和 SecretKey
4. ⚠️ 注意：SecretKey 只显示一次，请妥善保存

3. 验证配置

# 检查环境变量是否已设置
if ($env:TENCENT_SECRET_ID -and $env:TENCENT_SECRET_KEY) {
    Write-Host "✅ 环境变量已配置"
} else {
    Write-Host "❌ 请设置 TENCENT_SECRET_ID 和 TENCENT_SECRET_KEY"
}

# 测试生成
python scripts/generate.py "一只小猫"

使用方法

基础用法

# 生成图片
python {baseDir}/scripts/generate.py "雨中竹林小路"

# 指定风格
python {baseDir}/scripts/generate.py "少女, 樱花, 动漫风格" --style 201

# 指定分辨率
python {baseDir}/scripts/generate.py "未来城市" --resolution 1024:768

# 生成多张
python {baseDir}/scripts/generate.py "山水画" --num 4

参数说明

风格列表（常用）

完整列表：https://cloud.tencent.com/document/product/1729/105846

输出

生成的图片保存在 {output}/{date}/{job_id}/ 目录下：

• image_0.png - 生成的图片
• info.json - 任务信息（包含扩写后的描述）

注意事项

1. 异步接口：API是异步的，需要等待任务完成
2. 并发限制：默认1个并发
3. 地域限制：仅支持 ap-guangzhou
4. Prompt扩写：默认开启，可提升生成效果
5. 水印：默认不添加水印。使用 --logo 参数可添加"图片由AI生成"水印

踩坑记录

1. 状态码陷阱 ⚠️

坑：API返回 JobStatusCode: 5 可能是成功！需要检查 ResultDetails：

if status == '4' or (status == '5' and result.get('ResultDetails') == ['Success']):
    print('✅ 实际生成成功！')
    # 处理图片...

2. Prompt内容限制 🚫

坑：某些历史人物名字可能触发内容审核

实测结果：

建议：避免直接使用敏感历史人物全名，用描述性词汇替代

3. 网络超时问题 🌐

坑：API偶尔连接超时（ConnectTimeoutError）

解决：

• 增加重试机制
• 设置合理的超时时间（60秒以上）
• 使用稳定的网络环境

4. 风格编号无效 ❌

坑：文档中的风格编号 201 实际调用时报错 StyleId参数有误

解决：不传 --style 参数，让API自动选择默认风格

5. 图片下载超时问题 ⏱️

坑：下载大图片时可能超时

解决：增加超时时间设置

# 设置合理的超时时间（30秒）
urllib.request.urlopen(req, timeout=30)

6. Prompt扩写效果 ✨

惊喜：开启扩写（默认）后，简单描述会被AI优化为详细描述

示例：

• 输入："一只可爱的猫咪"
• 扩写后："一只可爱的猫咪，拥有圆润的身体和柔软的毛发，它的眼睛大而圆，流露出友好的笑容..."

建议：保持原始描述简洁，让AI自动扩写提升效果

8. 并发限制 ⏳

坑：默认只有1个并发，同时提交多个任务会排队

解决：

• 顺序执行，等待前一个完成
• 或购买更多并发额度

最佳实践 💡

1. Prompt编写：简洁描述 + 让AI扩写 > 冗长描述
2. 错误处理：检查 ResultDetails 而不仅是状态码
3. 内容规避：用"古代诗人"代替"李白"，用"美少女"代替具体人名
4. 网络重试：生产环境务必添加重试机制
5. 分辨率：竖版推荐 768:1024，横版推荐 1024:768

示例

# 生成动漫风格头像
python scripts/generate.py "可爱女孩, 短发, 微笑, 樱花背景" --style 201 --resolution 768:768

# 生成赛博朋克壁纸
python scripts/generate.py "未来城市, 霓虹灯, 雨夜" --style 501 --resolution 1920:1080 --clarity x2

# 生成水墨画
python scripts/generate.py "山水, 瀑布, 松树, 云雾" --style 101 --resolution 1024:768

相关链接

• API文档
• 腾讯云控制台
• 风格列表

许可证

MIT License

English Version