Call the Tencent Cloud Hunyuan 3.0 image generation model (through the CloudBase AI gateway), supportingText-to-imageandImage reference (image-to-image)。Completely free, costs nothing: the quota comes from the WeChat 「小程序成长计划」 incentive resource pack——100,000 AI-generated images + 1 billion Tokens, free for developers across all industries, valid for 6 months, the quota is drawn from the resource pack of your own CloudBase environment.
Visual web version + illustrated tutorial：freeimg.shenzjd.com/hunyuan —— The web page hasthe complete step-by-step tutorial from claiming the resource pack and creating keys to generating images(Step 0 card-style guidance); if you don't want to set up a local environment, just fill in the keys on the web page to use it, and both share the same set of Tencent Cloud credentials.
When to Use
- The user explicitly wants Hunyuan / Tencent Cloud image generation, or needsImage reference(reference-image editing)
- The user is in the WeChat Mini Program ecosystem and wants to use the 「小程序成长计划」 incentive resource pack100,000 free image generation quota
- The user has already configured Tencent Cloud keys and asks to continue using Hunyuan
When NOT to Use:
- The user just wants free, fast image generation with zero configuration → use
freeimg-z-imageskill (z-image-turbo, no registration or claiming required) - The user is unwilling to spend a few minutes claiming the free resource pack (although not claiming it incurs no cost, without the resource pack it is billed by usage)
Core Pattern
Step 0: First use — claim the free resource pack and configure credentials
Quota claiming (free, available to developers across all industries; the web version has the same illustrated tutorial card):
-
Claim the incentive resource pack: claim the resource pack on the WeChat Official Accounts Platform under 「Industry Capabilities → 小程序成长计划」 (100,000 AI-generated images + 1 billion Tokens, valid for 6 months), click 「Use Now」 to create a CloudBase environment, and note down theenvironment ID——the resource pack is bound to this environment
-
Create a key: Tencent Cloud Console Access Management → API Key Management click 「Create Key」, and copy the SecretId and SecretKey
-
Write the configuration(only once,do not write the key into repositories, logs, or conversation output）：
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
The script reads credentials in the following priority order: environment variable TCB_ENV_ID / TCB_SECRET_ID /
TCB_SECRET_KEY → configuration file ~/.freeimg-hunyuan/config.env. If neither is present, it prints the above guidance and exits.
Dependency note: the script uses the official @cloudbase/node-sdk(gateway authentication uses a custom signature, not reimplemented manually),
automatically installed to ~/.freeimg-hunyuan/sdkon first run (requires node + npm locally, takes a dozen seconds), and reused afterward.
Step 1: Generate images
# 文生图
scripts/generate.mjs --prompt "提示词" --out 输出.jpg [--size 1024x1024] [--no-revise] [--footnote "品牌名"]
# 垫图（图生图）：--image 接图片路径、base64 或 data URL
scripts/generate.mjs --prompt "提示词" --image 垫图.jpg --out 输出.jpg
--size: only supports1024x1024/1280x720/720x1280/2048x512(upstream restriction: width and height [512,2048] and area ≤ 1024x1024)--no-revise: disable automatic prompt polishing by the model (enabled by default)--footnote: watermark text in the bottom-right corner ≤16 characters; default single space = no watermark (the party using it is responsible for compliance in removing the watermark)- The prompt is limited to 4000 characters; Chinese is fine
- 429/5xx already has a built-in 2-second single retry; if it still fails, handle it according to the error prompt
Step 2: Delivery
- After generatingfirst view the image(Read tool) to confirm quality before handing it to the user; if not satisfied, change the prompt and regenerate
- The returned image URL is a signed address and will expire; the script has already downloaded it to disk immediately, so only deliver the local file
- In reference-image mode, prompts written as editing instructions like "keep the composition, replace ×× with ××" work better
Quick Reference
| Requirement | Parameter | Use |
|---|---|---|
| 1:1 square image | --size 1024x1024 |
Avatar, icon, knowledge card |
| 16:9 landscape image | --size 1280x720 |
PPT illustration, banner |
| 9:16 portrait image | --size 720x1280 |
Mobile poster, Xiaohongshu |
| 4:1 ultra-wide | --size 2048x512 |
WeChat Official Account header image, banner |
Environment variables:TCB_ENV_ID、TCB_SECRET_ID、TCB_SECRET_KEY(credentials),
FREEIMG_HUNYUAN_CONFIG(custom config file path),FREEIMG_HUNYUAN_SDK_DIR(custom SDK installation directory).
Common Mistakes
- Commit the key into the repository or paste it into the conversation: SecretId/SecretKey and the like carry the same account permissions; put them only in
~/.freeimg-hunyuan/config.env（chmod 600) or environment variables - Use an unsupported size: for example, 1536x2048 will be rejected; you can only choose one of the four (see Quick Reference)
- 422 is still retrying: 422 means the prompt triggered content moderation; resending the same content will inevitably fail again, so change the wording
- Generate directly without a resource package: this will incur pay-as-you-go charges; guide the user to first claim the free "小程序成长计划" incentive resource package (100,000 image generations) and bind it to the environment in use
- Wrong environment ID entered: the resource package is bound to the environment created when it was claimed; the environment corresponding to the credentials must have a resource package
- Assuming the output is PNG: what Hunyuan upstream delivers is JPEG, and the script saves it to disk as-is, with the extension determined by
--out— using.pngwill result in a file "named png, containing jpeg"; when delivering, always write the prefix name as.jpg - Delivering without checking after generation: Read it first before giving it to the user