zenmux-image-generation

zenmux-image-generation

ユーザーのビジュアルイメージを最適化されたプロンプトに変換し、プロンプトと パラメーターを確認してから、ZenMux を通じて画像を生成または編集し、保存された ファイルを報告します。

モデルの選択、プロンプトの最適化、またはソースの更新を行う前に、現在のプロジェクトの設定を読み込みます。同梱の config.json.example には移植可能な初期設定が含まれています。ユーザー設定はプロジェクトのランタイムディレクトリにのみ保存されます。

すべてのランタイムファイルは、現在のプロジェクト内の .context/zenmux-image-generation/ に保存されます。

.context/zenmux-image-generation/
  .gitignore    # Ignores generated files; allows .gitignore and config.json in Git
  config.json   # User settings, copied from config.json.example only if absent
  refresh-state.json # Per-resource refresh attempts and successful updates
  output/       # Generated images
  prompts/      # Optimized prompts and generation parameters
  assets/       # Reference images copied/downloaded for this task, if needed
  references/   # Refreshed documentation, cookbooks, and model cache

ヘルパーは、元の実行ディレクトリ（npm --prefix の場合は INIT_CWD）から Git ルートを解決します。Git 管理下にない場合は、その実行ディレクトリを使用します。 ユーザーのプロジェクトからコマンドを実行してください。このスキルは別の場所にインストールされている場合があります。必要に応じて、スクリプトや --prefix の引数には絶対パスを指定してください。 既存のユーザー参照画像はそのままの場所に置いておけます。スキルのコード、固定された依存関係、 同梱のオフライン参照資料はスキルのディレクトリに置かれます。

プロンプトを書いたり、アセットをダウンロードしたりする前に、ワークスペースを初期化します。

node skills/zenmux-image-generation/scripts/workspace.mjs

これにより、ランタイムディレクトリの絶対パスが表示され、そのサブディレクトリと .gitignore が作成されます。また、config.json が存在しない場合に限り、config.json.example がコピーされます。 既存のユーザー設定と無視ルールは保持されます。参照資料の更新と生成も、自動的にワークスペースを初期化します。プロジェクトのサブディレクトリから実行する場合は、表示されたルートを基準にプロンプトやキャッシュのパスを解決してください。

config.json はプロジェクトと一緒にコミットできます。生成画像、プロンプトファイル、 参照キャッシュ、refresh-state.json は引き続き無視されます。

設定とプロンプトモード

有効な設定を読み込みます（存在しないフィールドは、ユーザー設定を書き換えずにサンプルの値を引き継ぎます）。

node skills/zenmux-image-generation/scripts/workspace.mjs --config

設定	初期設定	意味
generation.model	openai/gpt-image-2.5-flare	デフォルトのモデル
generation.count	4	出力数。1～10
generation.size	1024x1024	サイズ。モデル固有の検証も適用されます
generation.quality	medium	low、medium、high、または auto
generation.outputFormat	png	png、jpeg、または webp
prompt.mode	direct	direct または reference。手順 5 で説明します
refresh.autoUpdate	true	自動的なネットワーク更新を許可します
refresh.referencesIntervalHours	168	ドキュメント／クックブック：7 日に 1 回
refresh.modelsIntervalHours	24	モデルカタログ：1 日に 1 回
refresh.retryIntervalMinutes	60	ローカルコピーがある場合、更新失敗後の再試行まで待機する時間

優先順位：明示的なユーザーのリクエスト／CLI フラグ ＞ プロジェクト設定 ＞ サンプルの初期設定。 モデルやプロンプトモードに対する一時的なリクエストは今回の実行に適用します。保存済みの設定を変更したいというユーザーの希望がある場合にのみ、プロジェクト設定を編集します。ユーザー設定を共有サンプルやスキルのソースに書き込んではいけません。API キーは設定ファイルの外部にある ZENMUX_API_KEY に保持します。不正な形式または無効な設定がある場合は、そのパスを報告して処理を失敗させ、ファイルを上書きしません。デフォルトを暗黙に使うのではなく、設定を修正してください。

refresh.autoUpdate を false に設定すると、自動的なネットワークリクエストを行わずに、ローカル／同梱のソースを使用します。間隔には 0 以上の数値を指定できます。0 は呼び出しのたびに更新することを意味します（リクエストに失敗した場合も再試行の待機時間は適用されます）。--force は、明示的にリクエストされた更新に対して、両方の間隔と autoUpdate の設定を無視します。

1. ランタイムを準備し、ソースを更新する

Node.js 22 以降が必要です。参照用コマンドでは curl と jq も必要です。 クローンごとに、または依存関係を変更した後に、ロックされた依存関係を一度インストールします。

npm ci --prefix skills/zenmux-image-generation

生成には ZENMUX_API_KEY が必要です。このキーを CLI 引数として受け取ったり、出力したりしないでください。

export ZENMUX_API_KEY=...

呼び出しの開始時に、更新チェックを実行します。更新間隔が経過したリソースだけをダウンロードし、更新履歴がない場合は一度だけ実行します。新しいキャッシュはネットワークリクエストなしで再利用されます。direct モードでは、プロンプトのクックブックはコピーもダウンロードもされません。API ドキュメントは引き続き更新できます。

bash skills/zenmux-image-generation/scripts/refresh_references.sh --quiet
# Only when the user requests an immediate update:
bash skills/zenmux-image-generation/scripts/refresh_references.sh --force
# One-off prompt-mode override, without editing config:
bash skills/zenmux-image-generation/scripts/refresh_references.sh --prompt-mode reference --quiet

ダウンロードに成功した参照には、それぞれ refresh-state.json にタイムスタンプが記録されます。別のファイルで失敗しても、変更されていないファイルはスキップされます。失敗した場合は前回のローカルコピーを維持し、再試行までの時間を延ばします。モデルカタログの更新が一部だけ成功した場合は、完全に成功したものとして記録されません。

ユーザーがモデルを指定した場合は、そのモデルを維持します。それ以外の場合、明らかに単純なデフォルトが適用されない限り、現在の画像モデルを一覧表示します。

bash skills/zenmux-image-generation/scripts/list_models.sh
# Machine-readable alternatives:
bash skills/zenmux-image-generation/scripts/list_models.sh --names-only
bash skills/zenmux-image-generation/scripts/list_models.sh --json

モデルコマンドには、設定済みのキャッシュ間隔が適用されます。更新時期になったら、https://zenmux.ai/api/v1/models と https://zenmux.ai/api/vertex-ai/v1beta/models の両方から画像モデルを統合し、ID が完全一致するものを重複排除して、プロジェクトローカルのキャッシュを更新します。2 つのカタログには異なるモデルが含まれる場合があります。一部の取得に失敗した場合は、警告を出してキャッシュ済みの追加モデルを保持します。オフラインの場合は、プロジェクトのキャッシュを使用し、次に同梱されている references/zenmux-image-models.json を使用します。--snapshot を指定すると、出力モダリティを含む、正規化済みの完全なモデルレコードが返されます。明示的に最新の情報を照会する場合、またはモデルが利用できないというエラーが発生した場合は、list_models.sh --force を使用します。記憶を頼りにモデル ID を作り出してはいけません。

まず .context/zenmux-image-generation/references/ 内の更新済みファイルを読みます。キャッシュされたコピーがない場合は、同名の references/ 同梱ファイルを使用します。以下の参照パスは、選択したディレクトリからの相対パスです。

ソースは次の順序で使用します。

1. ZenMux OpenAI Images のプロトコルと TypeScript の例には、references/zenmux-openai-image-generation.md を使用します。
2. 編集用フィールド、マスク、制限、リクエスト形式には、references/zenmux-create-image-edit.md を使用します。
3. 現行の OpenAI SDK シグネチャには、references/openai-typescript-images-generate.md または references/openai-typescript-images-edit.md を使用します。
4. Gemini／Vertex 互換プロトコルには、references/zenmux-image-generation.md を使用します。
5. Vertex AI の generateImages／editImage の完全なパラメーターマップには、references/zenmux-generate-images.md を使用します。
6. Google の最新のネイティブ Interactions API と、ZenMux との互換性の明確な境界には、references/google-gemini-image-generation.md を使用します。
7. reference モードでは、プロンプトの参考に限り awesome-* ファイルを使用します。API の正確な情報源としては使用しないでください。

2. 意図を把握する

以下の情報を抽出します。結果に大きく影響する情報が欠けている場合に限り、質問してください。質問は要点を絞り、最大 3 つまでにします。

項目	デフォルト
被写体と希望する変更	必須
スタイル、構図、ライティング、雰囲気	リクエストから推測
参照画像	なし
モデル	generation.model
サイズ	generation.size
品質	generation.quality
枚数	generation.count
出力形式	generation.outputFormat
画像内の正確なテキスト	なし
意味を表すファイル名のプレフィックス	短い英語のケバブケース要約

アスペクト比の指定：

• ポートレート、竖版、スマートフォンの壁紙、ストーリー：1024x1536
• ランドスケープ、横版、バナー、ワイドスクリーン：1536x1024
• 正方形、方形、ロゴ、アイコン、ソーシャル投稿：1024x1024
• gpt-image-2 の 4K：3840x2160
• gpt-image-2 の 2K／QHD：2560x1440

ユーザーが指定した参照パスまたは URL を、指定された順序ですべて記録します。ローカルパス、file://、http(s)://、Base64 形式の画像データ URL を受け付けます。プロンプトのメタデータとプロンプト本文の両方で、参照画像に [Image #1]、[Image #2] のように番号を付けます。フラグの順序は、この番号と一致させてください。

3. 現在のモデルとプロトコルを選択する

稼働中のモデルカタログが正式な情報源です。同梱のスナップショットは 2026-09-12に両方のエンドポイントから更新されました。以下は有用な選択肢です。

用途	推奨モデル
デフォルト	プロジェクト設定のgeneration.model
以前のOpenAIの代替モデル	openai/gpt-image-1.5
その他の新しいカタログ項目	openai/gpt-image-2.5-sunburst、meta/muse-image-1.0、x-ai/grok-imagine-image-2.0
汎用Nano Bananaのデフォルト	google/gemini-3.1-flash-image
最低レイテンシーのNano Banana	google/gemini-3.1-flash-lite-image
複雑なプロ向けアセット	google/gemini-3-pro-image
中国語のポスター／製品デザイン	qwen/qwen-image-3.0-pro、bytedance/doubao-seedream-5.0-pro
写実的な表現や柔軟なクリエイティブ制作	bfl/flux-2-max、bfl/flux-2-flex、bfl/flux-2-pro
その他の現行オプション	klingai/kling-v3、sapiens-ai/agnes-image-2.1-flash、tencent/hy-image-v3.0、z-ai/glm-image

カタログへの掲載によって確認できるのはモデルIDであり、すべてのプロトコルやパラメーターではありません。 新しいモデルでは、選択したプロトコルをZenMuxの最新ドキュメントで確認してください。 gpt-image-2.5-flareのカスタムサイズの上限が明確にドキュメント化されるまでは、プリセットサイズを 使用してください。以下のgpt-image-2の上限は、前のモデルについての説明です。

プロトコルに応じて振り分けます。

• openai/gpt-image-*、単独のgpt-image-*、およびchatgpt-image-latestでは、 デフォルトでscripts/generate-openai.tsとhttps://zenmux.ai/api/v1を使用します。
• それ以外のすべてのモデルでは、scripts/generate-gemini.tsと https://zenmux.ai/api/vertex-aiを使用します。
• ユーザーがOpenAIモデルでGeminiプロトコルを明示的に要求した場合は、 generate-gemini.tsを使用してその要求に従います。

GoogleのGemini APIでは、現在、ネイティブな画像生成機能としてclient.interactions.createが ドキュメント化されています。ZenMuxでは、このルートはドキュメント化されていません。 ZenMux経由では、Google Gemini画像モデルには引き続きgenerateContentを使用し、それ以外のすべての画像モデルには generateImages／editImageを使用してください。ZenMuxが対応を明示的に発表するまでは、 Interactions APIのペイロードをZenMuxに送信しないでください。現在の@google/genai SDKでは、 generateImagesは非推奨であり、早くとも2027-01-01の次のメジャーリリースで削除されると警告されています。 このメソッドはZenMuxとの互換性を保つためのブリッジとして扱い、SDKをメジャーアップグレードする前に ZenMuxのドキュメントを再確認してください。

gpt-image-2のカスタムWIDTHxHEIGHT値では、幅と高さの両方が16で割り切れ、 アスペクト比が1:3から3:1の範囲内で、総ピクセル数が655,360～8,294,400である必要があります。 2560x1440を超える解像度は実験的な扱いです。最大値は3840x2160です。 その他のOpenAI画像モデルでは、auto、1024x1024、1536x1024、または 1024x1536を使用してください。

4. OpenAI の作成・編集に関するベストプラクティスに従う

一度限りの生成や編集には Images API を使用します。ユーザーの実際の製品で会話形式の複数ターンにわたる画像状態が必要な場合にのみ Responses API を使用してください。付属のヘルパーは意図的に Images API を使用します。

生成の場合：

• TypeScript SDK を通じて client.images.generate を呼び出します。
• GPT Image は b64_json を返します。トランスコードせずにデコードしてバイト列を保存します。
• モデルで許可されている場合は、1 回のリクエストで複数の出力を得るために n を使用します。
• transparent 背景には PNG または WebP が必要です。
• gpt-image-2 の透過 PNG／WebP 出力は、現在プレビュー機能です。background=transparent を指定してください。PNG を指定するだけではアルファチャンネルは作成されません。
• output_compression は JPEG または WebP にのみ適用されます。

編集の場合：

• client.images.edit を呼び出し、ローカル、リモート、データ URL のバイト列を SDK の toFile ヘルパーで変換します。
• 入力画像は最大 16 枚までとし、順序を維持します。
• gpt-image-2 は画像入力を常に高忠実度で処理するため、input_fidelity は省略します。アイデンティティの保持が重要な場合は、以前の対応 GPT Image モデルでのみ input_fidelity=high を使用します。
• マスクは最初の入力画像に適用されます。PNG 形式で 4 MB 未満にし、最初の画像と同じ寸法にする必要があります。完全に透明なマスク領域が編集対象を示します。
• 最初に変更内容を記述し、その後、変更せず維持するすべての項目を明示的に列挙します。

スクリプトは防御的なフォールバックとして URL 出力を受け付け、返された画像のマジックバイトを検証し、タイムアウトと再試行を使用し、既存のファイルを上書きしません。

5. プロンプトを最適化して保存する

ユーザーの一度限りのリクエストがあればそのモードを使用し、なければ prompt.mode を使用します。呼び出し元のモデルがプロンプトを最適化します。この設定は画像 API に送信されず、別途有料のモデル呼び出しを発生させることもありません。

• direct（デフォルト）： ユーザーのリクエスト、提供された画像、呼び出し元モデル自身の判断に基づいて最適化します。クックブックやウェブからプロンプト例を検索、閲覧、流用しないでください。以下のクックブック検索は省略します。有効なパラメーターを確認する必要がある場合に限り API ドキュメントを参照してください。これらはプロンプトの着想元とは別のものです。
• reference： 既存のプロンプトクックブックから関連する例をいくつか探し、ユーザーの意図に合わせて調整します。使用したクックブックと項目をプロンプトのメタデータに記録します。役立つ例がない場合は、参照を使用したと主張せず、直接最適化に切り替えたことを明示します。

どちらのモードでも、ユーザーが提供した参照画像を受け付け、編集時の不変条件を維持し、同じ確認・生成フローを使用します。プロンプト参照モードで制御するのは、例となるプロンプトの調査のみです。

reference モードでは、どちらのクックブックも最初から最後まで読むことなく、関連する項目を検索します：

rg -n '^### No\..*(poster|portrait|product|infographic)' \
  .context/zenmux-image-generation/references/awesome-gpt-image-2.md

OpenAI 向けの例には awesome-gpt-image-2.md を、Gemini 向けの例には awesome-nano-banana-pro-prompts.md を使用します。題材ではなく、構成を調整して使います。

プロンプトの順序：

1. シーン／背景と構図
2. 主な被写体と動作
3. 素材、照明、配色、レンズ／レンダリングスタイル
4. 必要な場合は、正確な引用テキスト
5. [Image #N] 入力画像間の編集上の関係
6. 制約と不変条件

編集では、次のような的確な指示を書きます：「X のみを変更してください。アイデンティティ、ポーズ、形状、カメラアングル、照明、フレーミング、背景、および言及していないすべての詳細を維持してください。」編集を追加で行うたびに、不変条件を繰り返します。

次の場所にプロンプトを保存します：

.context/zenmux-image-generation/prompts/<YYYYMMDD-HHMMSS>-<short-slug>.md

以下の形式を使用し、今回の実行で有効な設定を記入します：

# Optimized prompt — <summary>

- **Prompt mode:** direct
- **Cookbook sources:** none
- **Model:** openai/gpt-image-2.5-flare
- **Size:** 1024x1536
- **Quality:** medium
- **Count:** 4
- **Output format:** png
- **Filename prefix:** launch-poster
- **References:** none
- **Created:** 2026-08-31 14:30 (Asia/Singapore)

---

<optimized prompt body>

最適化したプロンプトとパラメーターをユーザーに提示します。ユーザーが確認するまで、有料の生成 API を呼び出さないでください。小さな変更を求められた場合は、同じプロンプトファイルを編集します。

6. TypeScript で生成する

設定で OpenAI 画像モデルが選択されている場合は、設定済みのデフォルト値で生成します （この実行の設定を意図的に上書きする場合を除き、フラグは省略します）。

npm --prefix skills/zenmux-image-generation run generate:openai -- \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "launch-poster"

順序付きの参照画像とサイズ／品質の明示的な上書きを使った OpenAI の編集：

npm --prefix skills/zenmux-image-generation run generate:openai -- \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "outfit-edit" \
  --size "1024x1536" --quality "high" \
  --reference-image "/absolute/path/person.png" \
  --reference-image "https://example.com/jacket.webp"

マスク編集では --mask-image "/absolute/path/mask.png" を追加します。以前の GPT Image モデルでは、サポートされている場合に --input-fidelity high を追加します。ロスレスの透過アセットには --background transparent --output-format png を追加するか、より小さい透過アセットには WebP と --compression 85 を使用します。

Gemini／Vertex 互換モデル：

npm --prefix skills/zenmux-image-generation run generate:gemini -- \
  --model "google/gemini-3.1-flash-image" \
  --prompt-file ".context/zenmux-image-generation/prompts/<file>.md" \
  --filename-prefix "campaign-poster" \
  --aspect-ratio "2:3" --image-size "1K"

TypeScript の Gemini ヘルパーは、ZenMux の両方のプロトコル形式に対応しています。

• Google Gemini の画像モデルでは、generateContent または --stream による generateContentStream を使用します。常に TEXT と IMAGE をリクエストし、最大 14 個の参照画像を順序付きでサポートします。また、--aspect-ratio／--image-size を使用して imageConfig を構築します。
• Google 以外のモデルでは、generateImages を使用し、参照画像がある場合は editImage を使用します。サポートされている CLI のマッピングには、--negative-prompt、--aspect-ratio、--image-size、--seed、--enhance-prompt、--person-generation、--safety-filter-level、--include-rai-reason、--add-watermark、--guidance-scale があります。
• OpenAI モデルを意図的に Gemini プロトコル経由で呼び出す場合、--size と --quality は OpenAI にそのまま渡されるフィールドです。他の generateImages プロバイダーでサポートされている場合、--image-size は sampleImageSize になります。
• ZenMux Vertex プロトコルは、GPT Image の background フィールドに対応していません。GPT Image の透過出力には generate-openai.ts を使用してください。
• --aspect-ratio と --image-size を省略した場合、プロバイダーごとにデフォルト値が異なります。また、リクエストしたものとは異なる MIME タイプが返されるプロバイダーもあります。ヘルパーは PNG／JPEG／WebP のマジックバイトを検出し、一致する拡張子で保存します。

--output-dir は省略可能で、デフォルトはプロジェクトの .context/zenmux-image-generation/output/ です。相対パスで上書きした場合は、元の呼び出しディレクトリを基準に解決されます。ユーザーが別の場所を指定した場合にのみ上書きを渡してください。自動の ignore ルールで、実行時のワークスペースはカバーされています。

7. オブジェクトストレージで安全なファイル名

保存される画像には、すべて次の決定的な形式のファイル名が付けられます。

<semantic-prefix>-<model-slug>-<utc-millisecond-timestamp>-<8-hex-run-id>-<index>.<ext>

例：

launch-poster-openai-gpt-image-2-5-flare-20260912t143012345z-a1b2c3d4-01.png

これは、Supabase Storage、S3 互換 API、CDN、署名付き URL で安全に使用できるよう、意図的に制限を設けています。

• ファイル名の本体には小文字の ASCII 文字のみを使用します：a-z、0-9、-
• png、jpg、webp の前に付けられる最後の . は 1 つのみです
• 空白、Unicode、スラッシュ、バックスラッシュ、制御文字、URL で予約されている句読点、先頭のドット、.. セグメントは使用しません
• 辞書順に並べ替えられる UTC ミリ秒タイムスタンプ
• 同時実行時の衝突を防ぐランダムな実行 ID と出力インデックス
• 衝突によって既存のオブジェクトが上書きされないよう、排他的にファイルを作成します

簡潔で意味の分かる --filename-prefix を必ず指定してください。省略した場合、スクリプトはプロンプトのファイル名からプレフィックスを生成し、同じルールに従ってサニタイズします。

8. 結果を報告して反復する

成功すると、スクリプトは SUCCESS、OUTPUT_DIR、IMAGE_PATHS、単一行の RESULT_JSON を出力します。別のツールで安定した機械可読出力が必要な場合は、RESULT_JSON を解析してください。ユーザーにはクリック可能な絶対パスを返します。

追加の編集では、選択済みの画像を [Image #1] として保持し、不変条件を再記述した新しいプロンプトを保存して、その内容を確認してから、適切な編集方法を実行してください。

生成に失敗した場合：

• 依存関係が不足している場合：npm ci --prefix skills/zenmux-image-generation を実行します。
• モデルを利用できない場合：list_models.sh --force を再実行し、現在有効な ID をそのまま使用します。
• サイズが無効な場合：アスペクト比を維持する最も近い有効な寸法を選択します。
• 参照画像が拒否された場合：PNG／JPEG／WebP に変換し、モデルの入力上限内に収めます。
• プロバイダーが複数出力を拒否する場合：--n 1 を指定して呼び出しを繰り返し、同じ意味的なプレフィックスを保持します。ファイル名は実行 ID によって一意になります。