FreeImg Hunyuan — 腾讯混元生图（免费 10 万张额度）
调用腾讯云混元 3.0 生图模型（走 CloudBase AI 网关），支持文生图与垫图 （图生图）。完全免费，不花一分钱：额度来自微信「小程序成长计划」激励 资源包——10 万张 AI 生图 + 10 亿 Token，全行业开发者免费领取，6 个月有效， 额度烧在你自己云开发环境的资源包上。
可视化网页版 + 图文教程：freeimg.shenzjd.com/hunyuan —— 网页里有从领取资源包、创建密钥到出图的完整备注教程（Step 0 卡片式引导）， 不想配本地环境时在网页上填密钥即用，两者共用同一套腾讯云凭据。
When to Use
- User 明确要混元 / Hunyuan / 腾讯云出图，或需要垫图（参考图改图）
- User 走微信小程序生态、想用「小程序成长计划」激励资源包的10 万张免费生图额度
- User 已配置过腾讯云密钥并要求继续用混元
When NOT to Use:
- User 只想免费快速出图、零配置 → 用
freeimg-z-imageskill（z-image-turbo，免注册免领取） - User 不愿花几分钟领取免费资源包（虽然不领也不产生费用，但没有资源包时按量计费）
Core Pattern
Step 0: 首次使用 — 免费领取资源包并配置凭据
额度领取（免费，全行业开发者可领；网页版有同款图文教程卡片）：
-
领激励资源包：微信公众平台「行业能力 → 小程序成长计划」领取资源包 （10 万张 AI 生图 + 10 亿 Token，6 个月有效），点「去使用」创建一个 云开发环境，记下环境 ID——资源包就绑定在这个环境上
-
建密钥：腾讯云控制台 访问管理 → API 密钥管理 「新建密钥」，复制 SecretId 与 SecretKey
-
写配置（只需一次，不要把密钥写进仓库、日志或对话输出）：
mkdir -p ~/.freeimg-hunyuan && printf "TCB_ENV_ID=你的环境ID\nTCB_SECRET_ID=你的SecretId\nTCB_SECRET_KEY=你的SecretKey\n" > ~/.freeimg-hunyuan/config.env && chmod 600 ~/.freeimg-hunyuan/config.env
脚本按以下优先级读取凭据：环境变量 TCB_ENV_ID / TCB_SECRET_ID /
TCB_SECRET_KEY → 配置文件 ~/.freeimg-hunyuan/config.env。都没有时打印上述引导退出。
依赖说明：脚本用官方 @cloudbase/node-sdk（网关鉴权是自定义签名，不自行复刻），
首次运行自动装到 ~/.freeimg-hunyuan/sdk（需本机有 node + npm，十几秒），之后复用。
Step 1: 生成图片
# 文生图
scripts/generate.mjs --prompt "提示词" --out 输出.jpg [--size 1024x1024] [--no-revise] [--footnote "品牌名"]
# 垫图（图生图）：--image 接图片路径、base64 或 data URL
scripts/generate.mjs --prompt "提示词" --image 垫图.jpg --out 输出.jpg
--size：只支持1024x1024/1280x720/720x1280/2048x512（上游限制：宽高 [512,2048] 且面积 ≤ 1024x1024）--no-revise：关闭模型自动润色提示词（默认开启）--footnote：右下角水印文字 ≤16 字符；默认单个空格=无水印 （去水印的合规责任在使用方）- 提示词上限 4000 字，中文即可
- 429/5xx 已内置 2 秒重试一次；仍失败按错误提示处理
Step 2: 交付
- 生成后先查看图片（Read 工具）确认质量再交给用户；不满意换提示词重生成
- 返回的图片 URL 是签名地址会过期，脚本已立即下载落盘，只交付本地文件
- 垫图模式提示词写「保持构图，把 ×× 换成 ××」这类改图指令效果更好
Quick Reference
| 需求 | 参数 | 用途 |
|---|---|---|
| 1:1 方图 | --size 1024x1024 | 头像、图标、知识卡片 |
| 16:9 横图 | --size 1280x720 | PPT 配图、banner |
| 9:16 竖图 | --size 720x1280 | 手机海报、小红书 |
| 4:1 超宽 | --size 2048x512 | 公众号头图、横幅 |
环境变量：TCB_ENV_ID、TCB_SECRET_ID、TCB_SECRET_KEY（凭据）、
FREEIMG_HUNYUAN_CONFIG（自定义配置文件路径）、FREEIMG_HUNYUAN_SDK_DIR（自定义 SDK 安装目录）。
Common Mistakes
- 把密钥提交进仓库或贴进对话：SecretId/SecretKey 等同账号权限，只放
~/.freeimg-hunyuan/config.env（chmod 600）或环境变量 - 用不支持的尺寸：如 1536x2048 会被拒绝，只能四选一（见 Quick Reference）
- 422 还在重试：422 是提示词触发内容审核，同样内容重发必然再失败，改措辞
- 没有资源包直接生成：会按量计费产生费用；引导用户先免费领取「小程序成长计划」激励资源包（10 万张生图额度）并绑定所用环境
- 环境 ID 填错：资源包绑定在领取时创建的那个环境，凭据对应的环境必须有资源包
- 以为输出是 PNG：混元上游下发的是 JPEG，脚本按原样落盘，扩展名由
--out决定—— 用.png会得到「名字是 png、内容是 jpeg」的文件，交付前缀名一律写.jpg - 生成后不检查就交付：先 Read 查看再给用户