baoyu-imagine

画像生成（AI SDK）

公式の API ベースの画像生成です。OpenAI GPT Image 2、Azure OpenAI、Google、OpenRouter、DashScope（阿里通义万象）、Z.AI GLM-Image、MiniMax、Jimeng（即梦）、Seedream（豆包）、Replicate に対応しています。

ユーザー入力ツール

このスキルがユーザーに入力を求める場合は、次の優先順位に従ってツールを選択します。

1. 現在のエージェントランタイムが公開している組み込みのユーザー入力ツールを優先します。例：AskUserQuestion、request_user_input、clarify、ask_user、または同等のツール。
2. フォールバック：そのようなツールがない場合は、番号付きのプレーンテキストメッセージを出力し、各質問について選択した番号または回答を返すようユーザーに依頼します。
3. まとめて質問：ツールが1回の呼び出しで複数の質問に対応している場合は、該当する質問をすべてまとめます。1回につき1つの質問のみ対応している場合は、優先順位に従って1つずつ質問します。

以下の具体的な AskUserQuestion の例は参考例です。他のランタイムでは、ローカルの同等機能に置き換えてください。

スクリプトディレクトリ

{baseDir} = この SKILL.md があるディレクトリです。メインスクリプト：{baseDir}/scripts/main.ts。${BUN_X} の解決では、bun を優先します。なければ npx -y bun を使用し、それもなければ brew install oven-sh/bun/bun を提案します。

ステップ 0：設定の読み込み ⛔ BLOCKING

画像を生成する前に、このステップを必ず完了する必要があります。EXTEND.md が存在するまで、生成はブロックされます。

次のパスを上から順に確認します。最初に見つかったものを使用します。

パス	スコープ
.baoyu-skills/baoyu-imagine/EXTEND.md	プロジェクト
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-imagine/EXTEND.md	XDG
$HOME/.baoyu-skills/baoyu-imagine/EXTEND.md	ユーザーホーム

• 見つかった場合 → 読み込み、解析して適用します。default_model.[provider] が null の場合は、モデルのみを尋ねます。
• 見つからない場合 → references/config/first-time-setup.md を使って初回セットアップを実行し、AskUserQuestion でプロバイダー、モデル、品質、保存先を確認します。EXTEND.md を保存してから続行します。この手順が完了する前に画像を生成しないでください。

旧バージョンとの互換性：.baoyu-skills/baoyu-image-gen/EXTEND.md が存在し、新しいパスにファイルがない場合、ランタイムはそのファイルの名前を baoyu-imagine に変更します。両方が存在する場合、ランタイムはどちらも変更せず、新しいパスを使用します。

EXTEND.md のキー：デフォルトのプロバイダー、デフォルトの品質、デフォルトのアスペクト比、デフォルトの画像サイズ、OpenAI 画像 API の方言、デフォルトのモデル、バッチワーカーの上限、プロバイダーごとのバッチ制限。スキーマ：references/config/preferences-schema.md。

使い方

最小限の動作例については、プロバイダーごとの呼び出しやバッチモードを含む全例を references/usage-examples.md で確認してください。

アイデンティティを維持する参照プロンプト

参照画像に写っている実在の人物、キャラクター、物体をそのまま維持したい場合、参照画像の内容を長い一般的な説明に置き換えないでください。短く、アイデンティティの維持を強く指示する表現を使ってください。

• 「参照画像の人物／物体と同一のアイデンティティを維持してください。デザインを変更したり、似た見た目の別の対象を作成したりしないでください。」
• 「変更するのはシーン、服装、ポーズ、照明、レンダリングスタイル、構図のみです。参照画像にある顔、プロポーション、髪、特徴的なアクセサリー、全体的なアイデンティティは維持してください。」
• 複数の参照画像を使う場合は、すべて同一の対象であり、それらを合わせてアイデンティティを定義することを明記してください。

注意点：「若い東アジア人女性、卵形の顔、澄んだ瞳……」のような長い説明を使うと、参照された人物を維持するのではなく、説明に合う新しい人物をモデルが生成する可能性があります。

# Basic
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio and high quality
${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9 --quality 2k

# Prompt from files
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

# With reference image
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# Specific provider
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider dashscope --model qwen-image-2.0-pro

# OpenAI GPT Image 2
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --model gpt-image-2

# Batch mode
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4

参照画像のアイデンティティを維持する

ユーザーが参照画像に写っている人物や物体を維持したい場合：

• 多数の画像より、厳選した既存の参照画像（通常は2～4枚）を優先してください。サイズが数メガバイトの大きな参照画像は、ストリーミングプロバイダーを不安定にすることがあります。
• 参照画像が同一の対象を示しており、出力でもそのアイデンティティを使用する必要があることをプロンプトに明記してください。モデルが似ている別人を生成してしまう原因となる、顔の特徴に関する長い一般的な説明は避けてください。
• ユーザーから明示的に求められない限り、新たに生成した出力を参照画像として使用しないでください。生成画像を参照画像に使うと、ずれが積み重なります。
• 結果が過度に洗練されていたり、インフルエンサーのようになったりする場合は、スタイリッシュな参照画像を減らし、美化を防ぐ制約（顔を細くしない、目を大きくしない、濃いメイクをしない、商業的な旅行写真風にしない、過度に滑らかにしない）を明示的に追加してください。
• 対象を若く、または年上に見せたい場合も、顔はそのまま維持し、衣服、姿勢、場面、スタイリングで年齢を表現してください。モデルに顔のアイデンティティを変えるよう求めないでください。

オプション

オプション	説明
--prompt <text>, -p	プロンプトのテキスト
--promptfiles <files...>	ファイルからプロンプトを読み込みます（連結されます）
--image <path>	出力画像のパス（単一画像モードでは必須）
--batchfile <path>	複数画像を生成するための JSON バッチファイル
--jobs <count>	バッチモードのワーカー数（デフォルト：自動、設定の最大値、組み込みのデフォルトは10）
--provider google|openai|azure|openrouter|dashscope|zai|minimax|jimeng|seedream|replicate	プロバイダーを指定します（デフォルト：自動検出）
--model <id>, -m	モデル ID — デフォルト値と使用可能な値については、プロバイダーのリファレンスを参照してください
--ar <ratio>	アスペクト比（16:9、1:1、4:3、…）
--size <WxH>	サイズを明示的に指定します（例：1024x1024。gpt-image-2 では、幅と高さは16の倍数である必要があります。最大辺は3840px、比率は3:1より横長にできません）
--quality normal|2k	品質プリセット（デフォルト：2k）
--imageSize 1K|2K|4K	Google/OpenRouter 用の画像サイズ（デフォルト：品質設定に基づきます）
--imageApiDialect openai-native|ratio-metadata	OpenAI 互換エンドポイントの形式 — アスペクト比を表す size と metadata.resolution を求めるゲートウェイでは ratio-metadata を使用してください
--ref <files...>	参照画像。Google のマルチモーダル、OpenAI GPT Image edits、Azure OpenAI edits（PNG/JPG のみ）、OpenRouter のマルチモーダルモデル、Replicate の対応ファミリー、MiniMax の subject-reference、Seedream 5.0/4.5/4.0、DashScope wan2.7-image-pro/wan2.7-image がサポートしています。Jimeng、Seedream 3.0、SeedEdit 3.0、および wan2.7-image* ファミリー以外の DashScope モデルではサポートされていません
--n <count>	画像の枚数。Replicate では --n 1 が必要です（単一出力の保存方式）
--json	JSON 出力

環境変数

変数	説明
OPENAI_API_KEY	OpenAI API キー
AZURE_OPENAI_API_KEY	Azure OpenAI API キー
OPENROUTER_API_KEY	OpenRouter API キー
GOOGLE_API_KEY	Google API キー
DASHSCOPE_API_KEY	DashScope API キー
ZAI_API_KEY（別名 BIGMODEL_API_KEY）	Z.AI API キー
MINIMAX_API_KEY	MiniMax API キー
REPLICATE_API_TOKEN	Replicate API トークン
JIMENG_ACCESS_KEY_ID、JIMENG_SECRET_ACCESS_KEY	Jimeng（即梦）のVolcengine認証情報
ARK_API_KEY	Seedream（豆包）のVolcengine ARK API キー
<PROVIDER>_IMAGE_MODEL	プロバイダーごとのモデルの上書き（OPENAI_IMAGE_MODEL、GOOGLE_IMAGE_MODEL、DASHSCOPE_IMAGE_MODEL、ZAI_IMAGE_MODEL／BIGMODEL_IMAGE_MODEL、MINIMAX_IMAGE_MODEL、OPENROUTER_IMAGE_MODEL、REPLICATE_IMAGE_MODEL、JIMENG_IMAGE_MODEL、SEEDREAM_IMAGE_MODEL）
AZURE_OPENAI_DEPLOYMENT（別名 AZURE_OPENAI_IMAGE_MODEL）	Azure のデフォルトデプロイ
<PROVIDER>_BASE_URL	プロバイダーごとのエンドポイントの上書き
AZURE_API_VERSION	Azure 画像 API のバージョン（デフォルトは 2025-04-01-preview）
JIMENG_REGION	Jimeng のリージョン（デフォルトは cn-north-1）
OPENAI_IMAGE_API_DIALECT	openai-native | ratio-metadata
OPENROUTER_HTTP_REFERER、OPENROUTER_TITLE	任意の OpenRouter 帰属情報
BAOYU_IMAGE_GEN_MAX_WORKERS	バッチワーカーの上限を上書き
BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY	プロバイダーごとの同時実行数（例：BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY）
BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS	プロバイダーごとの開始間隔

読み込みの優先順位：CLI 引数 > EXTEND.md > 環境変数 > <cwd>/.baoyu-skills/.env > ~/.baoyu-skills/.env

Codex/ChatGPT OAuth は OpenAI API キーではありません

--provider openai --model gpt-image-2 は標準の OpenAI Images API（/v1/images/generations または /v1/images/edits）を使用し、OPENAI_API_KEY が必要です。Codex または ChatGPT のデスクトップログインは別の利用権限であり、OPENAI_API_KEY の代わりにはなりません。Codex OAuth トークンを OPENAI_API_KEY に貼り付けたり、OPENAI_BASE_URL に Codex バックエンドを設定するだけにしたりしないでください。

OpenAI API キーを使わずに Codex サブスクリプション／GPT Image 2 の利用権限を使いたい場合は、このスキルの openai プロバイダーではなく、Codex ネイティブのバックエンドを経由してください。

• Codex ランタイムでは、ネイティブの imagegen スキル／ツールを使用します。
• codex CLI がインストールされ、ログイン済みの非 Codex ランタイムでは、呼び出し元のスキルが対応している場合（例：baoyu-cover-image）、リポジトリレベルの scripts/codex-imagegen.sh ラッパーを使用します。プラグイン／リポジトリのルートからこのラッパーを解決し、プロンプト／出力／参照パスには絶対パスを渡してください。
• ネイティブの image_generate ツールがある Hermes ランタイムでは、フォールバックとしてそのツールを使用し、参照画像を直接渡したか、抽出した特徴から再構成したかを明記してください。

既存の openai プロバイダーを変更して、Codex OAuth を暗黙的に使用させないでください。baoyu-imagine に Codex OAuth の正式なサポートを追加する場合は、独自の認証、ルート、リクエスト形式、ドキュメント、テストを備えた別のプロバイダー（例：openai-codex）として実装してください。references/codex-oauth-vs-openai-api-key.md を参照してください。

モデルの解決

優先順位（高い順）は、すべてのプロバイダーに適用されます。

1. CLI フラグ --model <id>
2. EXTEND.md default_model.[provider]
3. 環境変数 <PROVIDER>_IMAGE_MODEL
4. 組み込みのデフォルト

OpenAI の組み込みのデフォルトは gpt-image-2 です。gpt-image-1.5、gpt-image-1、および GPT Image のスナップショットは、--model または OPENAI_IMAGE_MODEL で引き続き選択できます。

Azure では、--model／default_model.azure に Azure のデプロイ名を指定します。推奨される環境変数は AZURE_OPENAI_DEPLOYMENT です。AZURE_OPENAI_IMAGE_MODEL は、後方互換性のためのエイリアスとして維持されています。Azure のデプロイ名が基盤となるモデル名と同じ場合は gpt-image-2 を使用し、異なる場合は正確なカスタムデプロイ名を使用してください。

EXTEND.md は環境変数より優先されます。EXTEND.md に default_model.google: "gemini-3-pro-image-preview" が設定され、環境変数に GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview が設定されている場合は、EXTEND.md の設定が優先されます。

生成の前にモデル情報を表示します：

• Using [provider] / [model]
• Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

OpenAI 互換ゲートウェイの方言

provider=openai は、認証とルーティングのエントリーポイントが OpenAI 互換であることを意味します。アップストリームの画像 API が OpenAI ネイティブの仕様を使用するとは限りません。ゲートウェイが異なるワイヤ形式を必要とする場合は、EXTEND.md の default_image_api_dialect、OPENAI_IMAGE_API_DIALECT、または --imageApiDialect を設定してください。

• openai-native：ピクセル単位の size（1536x1024）と、OpenAI ネイティブの品質フィールド
• ratio-metadata：アスペクト比の size（16:9）に加え、metadata.resolution（1K|2K|4K）と metadata.orientation

OpenAI ネイティブ API または厳密なクローンでは openai-native を使用してください。Gemini などのモデルを利用する互換ゲートウェイでは、ratio-metadata をお試しください。現時点での制限：ratio-metadata が適用されるのはテキストから画像への生成のみです。参照画像の編集には、引き続き openai-native または編集を第一級でサポートするプロバイダーが必要です。

プロバイダー別ガイド

各プロバイダーには独自の仕様があります（モデルファミリー、サイズのルール、参照画像のサポート、制限など）。ユーザーがそのプロバイダーを選択した場合や、デフォルト以外の動作を求めた場合は、該当するガイドを参照してください。

プロバイダー	参照先
DashScope（Qwen-Image ファミリー、カスタムサイズ）	references/providers/dashscope.md
Z.AI（GLM-Image、cogview-4）	references/providers/zai.md
MiniMax（image-01、被写体参照）	references/providers/minimax.md
OpenRouter（マルチモーダルモデル、/chat/completions のフロー）	references/providers/openrouter.md
Replicate（nano-banana、Seedream、Wan）	references/providers/replicate.md

プロバイダーの選択

1. --ref が指定され、--provider が指定されていない場合 → Google → OpenAI → Azure → OpenRouter → Replicate → Seedream → MiniMax の順に自動選択します（MiniMax の被写体参照は、キャラクターやポートレートの一貫性により特化しています）
2. --provider が指定されている場合 → そのプロバイダーを使用します（--ref を指定する場合は、google／openai／azure／openrouter／replicate／seedream／minimax のいずれかである必要があります）
3. API キーが1つだけ存在する場合 → そのプロバイダーを使用します
4. 複数のキーがある場合 → デフォルトの優先順位：Google → OpenAI → Azure → OpenRouter → DashScope → Z.AI → MiniMax → Replicate → Jimeng → Seedream

品質プリセット

プリセット	Google imageSize	OpenAI size	OpenRouter size	Replicate resolution	用途
normal	1K	1024px を目標	1K	1K	すばやいプレビュー
2k（デフォルト）	2K	2048px を目標	2K	2K	カバー、イラスト、インフォグラフィック

Google／OpenRouter の imageSize は、--imageSize 1K|2K|4K で上書きできます。

OpenAI ネイティブの gpt-image-2 では、normal は quality=medium と、要求されたアスペクト比に近い低レイテンシーの有効なサイズに対応します。2k は quality=high と、2048x2048、2048x1152、1152x2048 などの2048pxクラスのサイズに対応します。有効なカスタムサイズや4K出力には、3840x2160 のように --size を明示的に指定してください。

アスペクト比

対応：1:1、16:9、9:16、4:3、3:4、2.35:1。

• Google マルチモーダル：imageConfig.aspectRatio
• OpenAI：gpt-image-2 は、指定された比率に最も近い有効なカスタムサイズを使用します。旧世代の GPT Image モデルと DALL·E モデルは、最も近い対応固定サイズを使用します
• OpenRouter：imageGenerationOptions.aspect_ratio。--size <WxH> だけが指定された場合は、比率が推定されます
• Replicate：挙動はモデルによって異なります。google/nano-banana* は aspect_ratio を使用し、bytedance/seedream-* は Replicate で文書化された比率を使用します。Wan 2.7 は --ar を具体的な size に変換します
• MiniMax：公式の aspect_ratio 値を使用します。--ar を指定せずに --size <WxH> が指定された場合、image-01 には width／height が送信されます

生成モード

デフォルト：順次実行。バッチ並列：--batchfile に処理待ちのタスクが2件以上含まれている場合に自動的に有効になります。

状況	推奨	理由
画像が1枚、またはシンプルな画像が1～2枚	順次実行	調整のオーバーヘッドが少なく、デバッグも容易です
保存済みのプロンプトファイルを使って複数の画像を生成	バッチ（--batchfile）	確定済みのプロンプトを再利用し、共通のスロットリング／再試行を適用でき、スループットも予測しやすくなります
各画像について個別の推論／プロンプト作成／スタイルの検討が必要	サブエージェント	まだ探索的な作業であり、それぞれに独立した分析が必要です
入力が outline.md + prompts/（例：baoyu-article-illustrator によるもの）	バッチ — scripts/build-batch.ts を使ってペイロードを組み立てます	アウトラインとプロンプトファイルに必要な情報がすべて含まれています

目安として、プロンプトファイルを保存済みで、タスクが「これらをすべて生成する」場合は、サブエージェントよりバッチを優先してください。生成に画像ごとの思考や創作内容の異なる探索が伴う場合にのみ、サブエージェントを使用してください。

並列処理の動作：

• ワーカー数はデフォルトで自動設定され、設定値を上限とします。組み込みのデフォルトは10です
• プロバイダー固有のスロットリングはバッチモードでのみ適用されます。デフォルト値は、RPM の急増を避けながらスループットを高められるよう調整されています
• --jobs <count> で上書きできます
• 各画像は最大3回試行されます
• 最終出力には成功数、失敗数、画像ごとの失敗理由が含まれます

エラー処理

• API キーがない → セットアップ手順を含むエラーを表示します
• 生成に失敗 → 画像ごとに最大3回自動で再試行します
• アスペクト比が無効 → 警告を表示し、デフォルト値で続行します
• 対応していないプロバイダー／モデルで参照画像を指定 → 修正のヒントを含むエラーを表示します

Codex image2 のフォールバック

OPENAI_API_KEY が設定されていないために --provider openai --model gpt-image-2 が失敗し、現在のランタイムでネイティブの画像生成バックエンドを利用できるか、リポジトリレベルの codex-imagegen ラッパーが利用できる場合は、ユーザーを待たせたままにせず、その方法を使用してください。フォールバックが参照画像を使った実際の画像生成なのか、抽出した視覚的特徴に基づくテキストプロンプトからの再構成にすぎないのかを明示してください。references/codex-image2-fallback.md を参照してください。

参考資料

ファイル	内容
references/usage-examples.md	プロバイダーとバッチモードにまたがる CLI の詳しい例
references/codex-oauth-vs-openai-api-key.md	Codex／ChatGPT OAuth の image2 利用権限を baoyu-imagine の標準 OpenAI API キープロバイダー経由では使用できない理由
references/codex-image2-fallback.md	OpenAI API 認証情報がない場合に、Codex／ネイティブ画像生成が利用できるときの実用的なフォールバック動作
references/providers/dashscope.md	DashScope のファミリー、サイズ、制限
references/providers/zai.md	Z.AI GLM-image／cogview-4
references/providers/minimax.md	MiniMax image-01 + 被写体参照
references/providers/openrouter.md	OpenRouter のマルチモーダルフロー
references/providers/replicate.md	Replicate の対応ファミリーとガードレール
references/config/preferences-schema.md	EXTEND.md のスキーマ
references/config/first-time-setup.md	初回セットアップの手順

拡張機能のサポート

EXTEND.md によるカスタム設定に対応しています。パスとスキーマについてはステップ0を参照してください。