happy-image-gen

happy-image-gen

1 つの CLI bun scripts/main.ts ... を通じて、8 つのプロバイダーで静止画を生成します。同じ CLI で、テキストから画像への生成と、画像から画像への編集（参照画像を使用）の両方に対応します。

クイック使用方法

bun scripts/main.ts --prompt "A calico cat on green grass, cinematic light" --ar 16:9 --image ./out.png

このスキルを呼び出すタイミング

ユーザーが次のいずれかを依頼した場合は、このスキルを呼び出します。

• テキストから画像を生成、作成、描画、レンダリング、イラスト化、または合成するよう依頼した場合。
• パスを指定した既存画像のスタイル変更や変換を依頼した場合。
• 即梦／Dreamina／Jimeng を指定せずに、画像生成モデル（DALL·E、gpt-image、Flux、SDXL、Gemini Image、Imagen、Seedream、Kolors、Wanx、Stable Diffusion）を指定した場合。

ユーザーが即梦、Jimeng、または dreamina CLI を明示的に指定した場合は、代わりに happy-dreamina に振り分けます。

ステップ 0：事前確認（必須 — 生成前に実行）

次の確認を実行します。

1. EXTEND.md の設定を探します。 次の順に確認します。

   • ./.happy-skills/happy-image-gen/EXTEND.md（プロジェクト）
   • $XDG_CONFIG_HOME/happy-skills/happy-image-gen/EXTEND.md
   • ~/.happy-skills/happy-image-gen/EXTEND.md（ユーザー）

   いずれも存在しない場合は、bun scripts/main.ts --setup を実行し、references/config/first-time-setup.md の手順に従って作成します。ユーザーが少なくとも 1 つのプロバイダーを設定するまで、生成に進まないでください。

2. 使用可能なプロバイダーがあることを確認します。 環境変数が設定されている（例：OPENAI_API_KEY）か、EXTEND.md に解決可能な api_key_env／api_key_source が記載されていることを確認します。何も解決できない場合は、セットアップに戻ります。

3. Bun が利用可能であることを確認します。 command -v bun を実行します。見つからない場合は、npx -y bun scripts/main.ts ... に切り替えます。

ステップ 1：プロバイダーを選択する

次の優先順位で選択します。

1. ユーザーが明示的に指定した --provider <id>。
2. EXTEND.md の default_provider。
3. API キーが環境変数に存在する最初のプロバイダー。自動検出時の優先順位は openai → google → replicate → stability → fal → ark → bailian → siliconflow です。

各プロバイダーに必要な環境変数、デフォルトモデル、強み（例：画像内テキストには google、Flux ファミリーのフォトリアリズムには replicate、中国語テキストの忠実な再現には ark）については、references/providers.md を参照してください。

ステップ 2：パラメーターを設定する

• --prompt：ユーザーの依頼全文を整えて指定します。必ず二重引用符で囲みます。
• --ar：アスペクト比 — 1:1／16:9／9:16／3:4／4:3。各プロバイダーでの解釈については、references/aspect_ratio_map.md を参照してください。
• --quality：draft（最速かつ最安）、hd（デフォルト）、または ultra（4K クラス、低速）。
• --ref <path>：複数の参照画像を指定する場合は繰り返します。すべてのプロバイダーが対応しているわけではありません。providers.md を参照してください。
• --model：選択したプロバイダーのデフォルトモデルを上書きします。ユーザーが特定のモデルを指定した場合を除き、省略します。
• --image <path>：必須 — 出力ファイルのパスです。内容がわかる名前を使用します（例：./out/hero-landscape.png）。

ステップ 3：実行する

bun scripts/main.ts \
  --prompt "..." \
  --image ./out.png \
  --provider openai \
  --ar 1:1 \
  --quality hd

成功すると、CLI は解決済みの絶対パスとバイト数を出力します。--json モードでは、次を出力します。

{ "success": true, "provider": "openai", "model": "gpt-image-1", "image": "/abs/path.png", "size_bytes": 1416341, "format": "png" }

パスをユーザーに伝えます。

ステップ 4：エラーに対処する

• config: No provider selected ... — 環境変数に API キーがなく、EXTEND.md もありません。ステップ 0 に戻ります。
• [openai] OpenAI images API 401 ... — キーが無効か、期限切れです。ユーザーに更新を依頼します。
• [openai] ... 400 ... content_policy_violation — プロンプトがブロックされました。生のエラーをユーザーに表示し、言い換えないでください。
• タイムアウト／ネットワークエラー — 1 回再試行します。それでも失敗する場合は、生のメッセージと provider を表示し、ユーザーが確認すべき内容がわかるようにします。

プロバイダーごとのエラー表については、references/error_codes.md を参照してください。

参考資料

必要に応じて読みます。

• references/providers.md — 8 つすべてのプロバイダー、必要な環境変数、デフォルトモデル、強み。
• references/aspect_ratio_map.md — 各プロバイダーによる --ar の解釈。
• references/error_codes.md — プロバイダーごとの一般的なエラーと対処法。
• references/config/first-time-setup.md — --setup の手順。
• references/config/extend-schema.md — EXTEND.md のスキーマリファレンス。

EXTEND.md のテンプレート：assets/EXTEND.template.md。