freeimg-hunyuan

FreeImg Hunyuan — Tencent Hunyuan 画像生成（無料 10 万枚分）

Tencent Cloud の Hunyuan 3.0 画像生成モデルを呼び出します（CloudBase AI ゲートウェイ経由）。テキストからの画像生成と画像を参照した画像生成（画像から画像）に対応しています。完全無料で、一切費用はかかりません。利用枠は WeChat「ミニプログラム成長プラン」のインセンティブリソースパッケージによるものです。全業界の開発者が無料で取得できるAI 画像生成 10 万枚分 + 10 億 Tokenで、有効期間は 6 か月です。利用枠はご自身のクラウド開発環境のリソースパッケージに適用されます。

ビジュアル版ウェブページ + 画像付きチュートリアル：freeimg.shenzjd.com/hunyuan —— ウェブページには、リソースパッケージの取得から、キーの作成、画像生成までを網羅した詳しいチュートリアル（Step 0 のカード形式のガイド）があります。ローカル環境を設定したくない場合は、ウェブページでキーを入力するだけですぐに利用できます。どちらも同じ Tencent Cloud の認証情報を使用します。

使用する場面

• ユーザーが Hunyuan／Tencent Cloud での画像生成を明示的に希望している、または画像を参照した画像生成（参考画像の編集）が必要な場合
• ユーザーが WeChat ミニプログラムのエコシステムを利用しており、「ミニプログラム成長プラン」のインセンティブリソースパッケージによる画像生成 10 万枚分の無料利用枠を希望する場合
• ユーザーが Tencent Cloud のキーをすでに設定しており、引き続き Hunyuan の利用を求めている場合

使用しない場面：

• ユーザーが無料ですぐに画像を生成したいだけで、設定を一切行いたくない場合 → freeimg-z-image skill（z-image-turbo、登録も取得手続きも不要）を使用します
• ユーザーが無料リソースパッケージの取得に数分かけたくない場合（取得しなくても費用は発生しませんが、リソースパッケージがない場合は従量課金になります）

基本的な手順

Step 0: 初回使用時 — 無料リソースパッケージを取得して認証情報を設定する

利用枠の取得（無料、全業界の開発者が取得可能。ウェブ版にも同じ内容の画像付きガイドカードがあります）：

1. インセンティブリソースパッケージを取得する：WeChat 公式プラットフォームの「業界向け機能 → ミニプログラム成長プラン」でリソースパッケージを取得します （AI 画像生成 10 万枚分 + 10 億 Token、有効期間 6 か月）。「利用する」をクリックしてクラウド開発環境を作成し、環境 IDを控えます。リソースパッケージはこの環境に紐付けられます

2. キーを作成する：Tencent Cloud コンソールの アクセス管理 → 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 秒後に 1 回自動再試行します。それでも失敗する場合は、エラーメッセージに従って対処してください

Step 2: 納品する

• 生成後はまず画像を確認し（Read ツール）、品質を確かめてからユーザーに渡します。満足できない場合は、プロンプトを変更して再生成してください
• 返される画像 URL は署名付きで、有効期限があります。スクリプトがすぐにダウンロードしてローカルに保存するため、ローカルファイルのみを渡してください
• 画像を参照するモードでは、「構図を維持して、×× を ×× に変える」のような画像編集の指示をプロンプトに含めると、より良い結果が得られます

クイックリファレンス

用途	パラメーター	使用例
1:1 正方形	--size 1024x1024	アバター、アイコン、ナレッジカード
16:9 横長	--size 1280x720	PPT の挿絵、バナー
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 インストール先）。

よくある間違い

• キーをリポジトリにコミットしたり、会話に貼り付けたりする：SecretId/SecretKey はアカウント権限と同等です。~/.freeimg-hunyuan/config.env（chmod 600）または環境変数にのみ保存してください
• 対応していないサイズを指定する：1536x2048 などは拒否されます。選択できるのは 4 種類のみです（クイックリファレンスを参照）
• 422 でも再試行を続ける：422 はプロンプトがコンテンツ審査に抵触したことを示します。同じ内容を再送しても必ず失敗するため、表現を変更してください
• リソースパッケージなしで生成する：従量課金となり、費用が発生します。まずユーザーに「ミニプログラム成長プラン」のインセンティブリソースパッケージ（画像生成 10 万枚分）を無料で取得し、使用する環境に紐付けるよう案内してください
• 環境 ID を間違える：リソースパッケージは取得時に作成した環境に紐付けられます。認証情報が示す環境にリソースパッケージが必要です
• 出力が PNG だと思い込む：Hunyuan の上流から返されるのは JPEG です。スクリプトはそのまま保存し、拡張子は --out で指定します。.png を指定すると「名前は png、内容は jpeg」のファイルになるため、納品時のファイル名には必ず .jpg を使用してください
• 生成後に確認せず納品する：先に Read で確認してからユーザーに渡してください