Call the Tencent Cloud Hunyuan 3.0 image generation model (via the CloudBase AI gateway), supportstext-to-imageandreference image (image-to-image)。Completely free, not a single cent: the quota comes from the WeChat "Mini Program Growth Plan" incentive resource pack——100,000 AI-generated images + 1 billion Tokens, free for developers across all industries, valid for 6 months, the quota is consumed from the resource pack in your own Cloud Development environment.
Visual web version + illustrated tutorial：freeimg.shenzjd.com/hunyuan —— the web page hasthe complete annotated tutorial from claiming the resource pack and creating a key to generating images(Step 0 card-style guide), if you don't want to set up a local environment, just enter your key on the web page and use it; both share the same set of Tencent Cloud credentials.
When to Use
- The user explicitly wants Hunyuan / Hunyuan / Tencent Cloud image generation, or needsreference image(editing an image with a reference image)
- The user is in the WeChat Mini Program ecosystem and wants to use the incentive resource pack of the "Mini Program Growth Plan"100,000 free image generation quota
- The user has already configured Tencent Cloud keys and requests to continue using Hunyuan
When NOT to Use:
- The user only wants free and fast image generation with zero configuration → use
freeimgskill (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
Claiming the quota (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 → Mini Program Growth Plan" (100,000 AI-generated images + 1 billion Tokens, valid for 6 months), click "Go to Use" to create a Cloud Development 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 "Create Key", copy the SecretId and SecretKey
-
Write the configuration(only once,do not write the key into the repository, logs, or conversation output）：
mkdir -p ~/.hunyuan && printf "TCB_ENV_ID=你的环境ID\nTCB_SECRET_ID=你的SecretId\nTCB_SECRET_KEY=你的SecretKey\n" > ~/.hunyuan/config.env && chmod 600 ~/.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 ~/.hunyuan/config.env. If neither exists, it prints the above guidance and exits.
Dependency note: the script uses the official @cloudbase/node-sdk(gateway authentication is a custom signature, do not reimplement it yourself),
on first run it automatically installs to ~/.hunyuan/sdk(requires node + npm on the machine, takes a dozen seconds), and reuses it afterwards.
Step 1: Generate an image
# 文生图
scripts/generate.mjs --prompt "提示词" --out 输出.png [--size 1024x1024] [--no-revise] [--footnote "品牌名"]
# 垫图（图生图）：--image 接图片路径、base64 或 data URL
scripts/generate.mjs --prompt "提示词" --image 垫图.jpg --out 输出.png
--size: only supports1024x1024/1280x720/720x1280/2048x512(upstream limit: width and height [512,2048] and area ≤ 1024x1024)--no-revise: disable the model's automatic prompt polishing (enabled by default)--footnote: watermark text in the bottom-right corner ≤16 characters; default is a single space = no watermark (the user is responsible for compliance when removing the watermark)- Prompt limit is 4000 characters, Chinese is fine
- 429/5xx has a built-in 2-second retry once; if it still fails, handle it according to the error message
Step 2: Delivery
- After generationFirst view the image(Read tool) confirm the quality before delivering to the user; if unsatisfied, change the prompt and regenerate
- The returned image URL is a signed address that will expire; the script has already downloaded it to disk immediately, so only deliver the local file
- In image-reference mode, prompts written as image-editing instructions like "keep the composition, replace ×× with ××" work better
Quick Reference
| Requirement | Parameter | Use case |
|---|---|---|
| 1:1 square image | --size 1024x1024 |
Avatars, icons, knowledge cards |
| 16:9 horizontal image | --size 1280x720 |
PPT illustrations, banners |
| 9:16 vertical image | --size 720x1280 |
Mobile posters, Xiaohongshu |
| 4:1 ultra-wide | --size 2048x512 |
WeChat Official Account header images, banners |
Environment variables:TCB_ENV_ID、TCB_SECRET_ID、TCB_SECRET_KEY(credentials),
HUNYUAN_CONFIG(custom configuration file path),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 have the same account permissions, so only put them in
~/.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 pack: this will incur pay-as-you-go charges; guide the user to first claim the "Mini Program Growth Plan" incentive resource pack for free (100,000 image generation credits) and bind it to the environment in use
- Wrong environment ID entered: the resource pack is bound to the environment created when it was claimed; the environment corresponding to the credentials must have a resource pack
- Deliver without checking after generation: Read and view it first before giving it to the user