freeimg-hunyuan

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-image skill（z-image-turbo，免注册免领取）
• User 不愿花几分钟领取免费资源包（虽然不领也不产生费用，但没有资源包时按量计费）

Core Pattern

Step 0: 首次使用 — 免费领取资源包并配置凭据

额度领取（免费，全行业开发者可领；网页版有同款图文教程卡片）：

1. 领激励资源包：微信公众平台「行业能力 → 小程序成长计划」领取资源包 （10 万张 AI 生图 + 10 亿 Token，6 个月有效），点「去使用」创建一个 云开发环境，记下环境 ID——资源包就绑定在这个环境上

2. 建密钥：腾讯云控制台 访问管理 → API 密钥管理 「新建密钥」，复制 SecretId 与 SecretKey

3. 写配置（只需一次，不要把密钥写进仓库、日志或对话输出）：

   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 查看再给用户