mcpField
F
freeimg-hunyuan

freeimg-hunyuan

github.com/wu529778790Creative & media4200 installsUpdated 5w ago
Repository

About freeimg-hunyuan

freeimg-hunyuan is a skill for generating images with Tencent Cloud Hunyuan 3.0, for users who need text-to-image or reference-image editing. It uses the CloudBase AI gateway and offers both a CLI script and a web interface.

Key features

  1. 01Text-to-image and reference-image editing
  2. 02Set image size and prompt revision
  3. 03Add lower-right watermark text
  4. 04Download generated images locally
  5. 05Web-based setup guide

Use cases

  1. 01Create illustrations from text prompts
  2. 02Edit composition or content from a reference image
  3. 03Generate posters or banners in set aspect ratios

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wu529778790/shenzjd-skills --skill freeimg-hunyuan

After installing, type/freeimg-hunyuanin Claude Code to confirm it loaded.

Bundled filesREADME.mdscripts/generate.mjs

Details

From the project README

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 1280x720PPT 配图、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 查看再给用户

Comments

Markdown supported