tuzi-image-gen

画像生成（AI SDK）

複数プロバイダーに対応した画像生成です。デフォルトのプロバイダー：Tuzi（兔子API、api.tu-zi.com）。

スクリプトディレクトリ

エージェントの実行：

1. SKILL_DIR = この SKILL.md ファイルのディレクトリ
2. スクリプトのパス = ${SKILL_DIR}/scripts/main.ts

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

重要：画像を生成する前に、このステップを必ず完了してください。省略したり、後回しにしたりしないでください。

0.1 API キーの確認

選択したプロバイダーの API キーが使用可能か確認します。デフォルトの Tuzi の場合：

# Check env, then .tuzi-skills/.env files
echo "${TUZI_API_KEY:-not_set}"
grep -s TUZI_API_KEY .tuzi-skills/.env "$HOME/.tuzi-skills/.env"

結果	アクション
キーが見つかった	ステップ 0.2 に進む
キーが見つからない	⛔ API キーを設定する（references/config/first-time-setup.md → 「API Key Setup」を参照）→ キーを保存 → 続行

重要：API キーがない場合は、生成する前にユーザーにキーの取得と保存を案内する必要があります。キーが設定されるまで、生成はブロックされます。

0.2 EXTEND.md の確認

EXTEND.md の有無を確認します（優先順位：プロジェクト → ユーザー）：

test -f .tuzi-skills/tuzi-image-gen/EXTEND.md && echo "project"
test -f "$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.md" && echo "user"

結果	アクション
見つかった	読み込み、解析し、設定を適用する。default_model.[provider] が null の場合は、モデルのみを質問する（フロー 2）
見つからない	⛔ 初回セットアップを実行する（references/config/first-time-setup.md）→ EXTEND.md を保存 → 続行

重要：見つからない場合は、画像を生成する前に AskUserQuestion を使用して、プロバイダー、モデル、品質、保存先を含むセットアップ全体を完了してください。EXTEND.md が作成されるまで、生成はブロックされます。

パス	場所
.tuzi-skills/tuzi-image-gen/EXTEND.md	プロジェクトディレクトリ
$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.md	ユーザーのホームディレクトリ

EXTEND.md がサポートする項目：デフォルトのプロバイダー | デフォルトの品質 | デフォルトのアスペクト比 | デフォルトの画像サイズ | OpenAI 画像 API の方言 | デフォルトモデル

スキーマ：references/config/preferences-schema.md

使い方

# Basic (uses Tuzi provider by default)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9

# With quality (Tuzi: 1k/2k/4k)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

# 4K VIP model
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --model gemini-3-pro-image-preview-4k-vip

# With reference images
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make it blue" --image out.png --ref source.png

# From prompt files
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

# Async model (auto-polls)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --model gemini-3-pro-image-preview-2k-async

# Other providers
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider google
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# OpenAI-compatible gateway dialect
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --imageApiDialect ratio-metadata

オプション

オプション	説明
--prompt <text>, -p	プロンプトテキスト
--promptfiles <files...>	ファイルからプロンプトを読み込む（連結）
--image <path>	出力画像のパス（必須）
--provider tuzi|google|openai|dashscope|replicate	プロバイダーを指定（デフォルト：自動検出、Tuzi を優先）
--model <id>, -m	モデル ID（全モデルの一覧は「Tuzi Models」セクションを参照）
--ar <ratio>	アスペクト比（例：16:9、1:1、4:3）。Tuzi は NxN 形式に変換します
--size <WxH>	サイズを上書き（例：1024x1024、16x9）
--quality normal|2k	品質プリセット。Tuzi：1k/2k に対応。Google：1K/2K に対応
--imageSize 1K|2K|4K	画像サイズ（Tuzi と Google）。--quality を上書きします
--imageApiDialect openai-native|ratio-metadata	OpenAI 互換エンドポイントの方言。ratio-metadata は、アスペクト比を size に、解像度を metadata.resolution に指定するゲートウェイ向けです
--ref <files...>	参照画像。Tuzi：JSON 本文に base64 で格納。Google：マルチモーダル。OpenAI：編集 API
--n <count>	画像の枚数
--json	JSON 出力

Tuzi のモデル

Tuzi API（api.tu-zi.com）はデフォルトのプロバイダーです。モデルごとに品質、速度、サポートされるパラメーターが異なります。

おすすめ

モデル ID	エイリアス	品質	備考
gemini-3-pro-image-preview	nano-banana-pro	--quality 1k/2k/4k	デフォルト。高品質で、品質パラメーターに対応
gemini-3.1-flash-image-preview	nano-banana-2	--quality 1k/2k/4k	高速で、拡張アスペクト比に対応
gemini-3-pro-image-preview-vip	nano-banana-pro-vip	1k 内蔵	高品質、VIP
gemini-3-pro-image-preview-2k-vip	nano-banana-pro-2k-vip	2k 内蔵	高品質 2K、VIP
gemini-3-pro-image-preview-4k-vip	nano-banana-pro-4k-vip	4k 内蔵	高品質 4K、VIP
gemini-2.5-flash-image-vip	nano-banana-vip	1k 内蔵	最速、VIP

その他のモデル

モデル ID	エイリアス	備考
gemini-3-pro-image-preview	nano-banana-pro	--quality 1k/2k/4k
gemini-2.5-flash-image	nano-banana	高速
gemini-3-pro-image-preview-hd	nano-banana-pro-hd	HD が組み込み済み
gemini-3-pro-image-preview-2k	nano-banana-pro-2k	2K が組み込み済み
gemini-3-pro-image-preview-4k	nano-banana-pro-4k	4K が組み込み済み
gpt-image-2	—	OpenAI の最新画像モデル。最新のサイズ規則に対応
gpt-image-1.5	—	サイズ：1:1、3:2、2:3 のみ
bfl-flux-2-pro	flux-2-pro	Flux
bfl-flux-2-max	flux-2-max	Flux の最高品質
flux-kontext-pro	kontext-pro	複数の参照画像を使った編集
flux-kontext-max	kontext-max	複数の参照画像を使った編集（最大）
doubao-seedream-4-0-250828	Seedream 4.0	2K/4K
doubao-seedream-4-5-251128	Seedream 4.5	2K/4K
doubao-seedream-5-0-260128	Seedream 5.0 lite	2K/3K

非同期モデル

自動検出されます。スクリプトはタスクを送信し、完了するまでポーリングします（5 秒間隔、最大 30 分）。

モデル ID	備考
gemini-3-pro-image-preview-async	1K 非同期
gemini-3-pro-image-preview-2k-async	2K 非同期
gemini-3-pro-image-preview-4k-async	4K 非同期
mj-imagine	Midjourney。プロンプト内で MJ パラメーターを指定

モデル固有のパラメーター

品質（--quality または --imageSize 1K|2K|4K）：

対象	値	備考
gemini-3.1-flash-image-preview	1k / 2k / 4k	デフォルトモデル。品質を調整可能
gemini-3-pro-image-preview	1k / 2k / 4k	品質を調整可能
*-2k-vip、*-4k-vip、*-hd	—	品質はモデル名に組み込み済み。パラメーターは無視されます
その他のモデル	—	パラメーターは無視されます

アスペクト比（--ar）：

対象	対応する比率
Gemini モデル（デフォルト）	1:1、16:9、9:16、3:2、2:3、4:3、3:4、5:4、4:5、21:9
gemini-3.1-flash-image-preview	上記に加え、1:4、4:1、1:8、8:1（極端な比率）
gpt-image-2	生成される有効なピクセルサイズを介して比率を柔軟に指定できます。カスタムの --size は OpenAI の制約を満たす必要があります
gpt-image-1.5	1:1、3:2、2:3
doubao-seedream-*	--size / --imageSize を明示的に指定してください。--ar のみの指定には対応していません
省略時	モデルが自動的に決定します

参照画像（--ref）：

• gpt-image-*：OpenAI スタイルの /images/edits マルチパートアップロード
• その他の同期モデル：JSON の image フィールドに base64 データ URL を指定
• 非同期モデル：FormData の input_reference
• ほとんどの Tuzi 同期モデルは参照画像に対応しています。doubao-seedream-3-0-* は対応していません

Seedream（doubao-seedream-*）：

対象	サイズ規則	参照画像
doubao-seedream-5-0-*	2K、3K、または明示的な WxH	最大 14 枚
doubao-seedream-4-5-*	2K、4K、または明示的な WxH	最大 14 枚
doubao-seedream-4-0-*	1K、2K、4K、または明示的な WxH	最大 14 枚
doubao-seedream-3-0-*	明示的な WxH のみ	非対応

環境変数

変数	説明
TUZI_API_KEY	Tuzi API キー（https://api.tu-zi.com）
TUZI_IMAGE_MODEL	Tuzi のデフォルトモデル（デフォルト：gemini-3-pro-image-preview）
TUZI_BASE_URL	Tuzi のカスタムエンドポイント（デフォルト：https://api.tu-zi.com/v1）
GOOGLE_API_KEY	Google API キー
OPENAI_API_KEY	OpenAI API キー
DASHSCOPE_API_KEY	DashScope API キー（阿里云）
REPLICATE_API_TOKEN	Replicate API トークン
GOOGLE_IMAGE_MODEL	Google モデルの上書き
OPENAI_IMAGE_MODEL	OpenAI モデルの上書き（デフォルト：gpt-image-2）
DASHSCOPE_IMAGE_MODEL	DashScope モデルの上書き
REPLICATE_IMAGE_MODEL	Replicate モデルの上書き
GOOGLE_BASE_URL	Google のカスタムエンドポイント
OPENAI_BASE_URL	OpenAI のカスタムエンドポイント
OPENAI_IMAGE_API_DIALECT	OpenAI 互換エンドポイントの方言（openai-native または ratio-metadata）
DASHSCOPE_BASE_URL	DashScope のカスタムエンドポイント
REPLICATE_BASE_URL	Replicate のカスタムエンドポイント

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

モデルの解決

すべてのプロバイダーにおける優先順位（高い順）：

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

エージェントは、生成のたびにモデル情報を表示する必要があります：

• 表示：Using [provider] / [model]
• 切り替え方法を表示：Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

プロバイダーの選択

1. --provider が指定されている → そのプロバイダーを使用
2. --ref が指定され、--provider が指定されていない → Tuzi > Google > OpenAI > Replicate
3. API キーが1つだけ利用可能 → そのプロバイダーを使用
4. 複数利用可能 → まず Tuzi を使用

OpenAI 互換の方言

provider=openai の場合でも、エンドポイントは OpenAI ネイティブのインフラではなく、OpenAI 互換のゲートウェイである可能性があります。

• openai-native：標準の OpenAI Images API リクエストボディ
• ratio-metadata：アスペクト比の size と metadata.resolution を送信します。非ネイティブの画像バックエンドの前段にある互換ゲートウェイで役立ちます

現在の制限：ratio-metadata はテキストから画像を生成する場合のみ使用できます。--ref を使用する場合は、openai-native を使用してください。

品質プリセット

プリセット	Tuzi	Google	OpenAI
normal	1k	1K	1024px
2k（デフォルト）	2k	2K	2048px

--imageSize 1K|2K|4K は、Tuzi と Google の品質設定を上書きします。

生成モード

デフォルト：順次（1回に1つ）。

並列：ユーザーが明示的にリクエストした場合のみ使用します。run_in_background=true を指定した Task ツールを使用し、サブエージェントは4つ（最大8つ）を推奨します。

エラー処理

• API キーがない → ⛔ Step 0.1 の API キー設定を必ず実行します（https://api.tu-zi.com/token に案内し、キーを .tuzi-skills/.env に保存します）。ユーザーが別のプロバイダーを明示的に選択していない限り、GOOGLE_API_KEY や他のプロバイダーのキーを提案しないでください。
• 生成に失敗 → 1回自動で再試行
• Tuzi の PROHIBITED_CONTENT → コンテンツ拒否エラー
• Tuzi の NO_IMAGE → プロンプトが曖昧すぎます。より具体的なプロンプトを提案してください
• 非同期タイムアウト → 30分後にエラー
• アスペクト比が無効 → 警告を表示し、デフォルトで続行

Replicate モデル

形式：owner/name または owner/name:version

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana-2 --ar 16:9
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A fashion photo" --image out.png --provider replicate --model bytedance/seedream-4.5 --size 4K
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cinematic scene" --image out.png --provider replicate --model wan-video/wan-2.7-image-pro --size 4K

対応ファミリー

ファミリー	モデルの例	参照画像	アスペクト比	サイズの処理	備考
Nano Banana	google/nano-banana、google/nano-banana-pro、google/nano-banana-2	最大14枚	標準の文書化済み比率	--quality は1K／2Kに対応し、--size から比率と1K／2Kを推測できます	デフォルトで最も高い互換性
Seedream 4.5	bytedance/seedream-4.5	最大14枚	標準の文書化済み比率	--size は 2K、4K、またはカスタムの WxH に対応	高解像度の出力に適しています
Seedream 5 Lite	bytedance/seedream-5-lite	最大14枚	標準の文書化済み比率	--size は 2K または 3K に対応	シンプルなサイズプリセット
Wan 2.7 Image	wan-video/wan-2.7-image	最大9枚	W:H の比率をサイズに変換	--size は 1K、2K、またはカスタムの WxH に対応	参照画像には images フィールドを使用
Wan 2.7 Image Pro	wan-video/wan-2.7-image-pro	最大9枚	W:H の比率をサイズに変換	--size は 1K、2K、4K、またはカスタムの WxH に対応	4K はテキストから画像への生成でのみ使用できます（--ref は使用不可）

Replicate に関する注意事項

• 現在のツールはリクエストごとに画像を1枚だけ保存するため、Replicate では --n 1 のみ使用できます。
• Replicate では --imageSize は使用されません。代わりに --quality、--ar、または --size を使用してください。
• 不明な Replicate モデルでもプロンプトのみの生成はできますが、--ref、--ar、--size が確実にサポートされるのは上記のファミリーのみです。
• このツールで Nano Banana と Seedream の両方に共通する文書化済みのアスペクト比は、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 です。

拡張機能のサポート

EXTEND.md を使ってカスタム設定ができます。パスとサポートされるオプションについては、Step 0 を参照してください。