generate2dmedia

2D メディアを生成する

ルート層です。生のメディアを生成し、担当スキルがアセットを事前に計画し、生成後に確認します。

次の場合に使用します

• Forge スキル（またはそのパイプラインスクリプト）が、生成画像、参照画像の編集、または画像から動画へのクリップを必要とする場合。
• この環境で利用できるルートを確認する場合（forge_doctor.py）。セッションごとに一度実行します。
• ユーザーが API キーの設定や特定のルートの使用を求める場合、または費用について質問する場合。

次の場合は使用しないでください

• 計画、キー設定、登録、パッケージ化の場合：generate2dsprite、video2dsprite、generate2dmap。
• ユーザーが依頼したコード描画アートの場合：codeart2d。

ルートの優先順位（担当者の決定：2026-10-06）

1. API：キーが設定されているすべてのプロバイダーを使用します。順序は、ユーザーの providers.order を最初にします。画像：OpenAI（gpt-image-2.5-sunburst）、Google Gemini（gemini-3.1-flash-image。--tier hero ではヒーロー用マスターに gemini-3-pro-image を使用）、xAI（grok-imagine-image-2.0）、BytePlus ModelArk（Seedream 5.0）、fal.ai（参照画像の編集）。動画：xAI（grok-imagine-video-1.5。--tier draft では 1.5 Lite を使用）、BytePlus ModelArk（Seedance 2.0）、fal.ai（Kling v3、Veo 3.1、Luma、MiniMax、Wan、Vidu、LTX）。キーの設定はユーザーの同意を意味するため、呼び出しごとの確認は不要です。
2. ローカル：利用できる場合は独自の画像ツール（Codex の image_gen、Grok のネイティブツール）を使用します。ない場合は、ユーザーがサインイン済みの CLI を使用します。Codex（ローカル CLI）の image_gen に参照画像を添付し、次に Grok（ローカル CLI）のワンショット画像生成または編集を使用します。動画には Grok（ローカル CLI）を ACP モードで使用します。インストール済みの CLI はそのまま使用し、初回の実行が成功すると VERIFIED の証明が記録されます。
3. codeart2d：ユーザーがコード描画アートを明示的に依頼した場合、または route_media.py が no-route（終了コード 3）を出力した場合に限ります。

実際に使用したルートを必ず明記してください（「OpenAI API」「Google Gemini API」「xAI API」「BytePlus ModelArk API」「fal.ai API」「Codex (local CLI)」「Grok (local CLI)」）。詳細：route-media.md。

機能チェック（セッションごとに一度）

python "<skill-dir>/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json を実行します。<tools> には、使用中のツール一覧にあるメディアツール（image_gen、image_edit、image_to_video）を列挙するか、none を指定してください。ROUTES ブロックには、設定されている API キー（有無のみ。キー自体は表示されません）、各 CLI のローカルでの準備状況、および解決された順序（routeOrder）が表示されます。encoding.stdout が失敗する場合は、PYTHONUTF8=1 を設定してください。

生成（route_media.py）

必要なもの	コマンド
実行されるルートの確認	python "<skill-dir>/scripts/route_media.py" resolve --kind image（または video。--references N）
画像を1枚生成、または編集	python "<skill-dir>/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>（--reference は繰り返し指定でき、プロンプトで言及する順に並べます）
承認済みの静止画をアニメーション化	python "<skill-dir>/scripts/route_media.py" video --prompt-file <txt> --reference <still.png> --last-frame <still.png> --duration 6 --resolution 720p --out-dir <new>
ルートまたはモデルをユーザーが選択	--route api、local、openai、gemini、xai、byteplus、fal、fal:<endpoint-id>、codex-cli、grok-cli、または grok-acp を追加します。--model <id>、--tier draft または hero、--provider-option [PROVIDER:]KEY=VALUE も指定できます
先にプランと見積もりを確認	--dry-run を追加します（キーは使用されず、何も送信または書き込みされません）

成功すると ASCII JSON の1行が出力され、終了コード 0 で終了します：{"status":"ok","route":"api:openai","artifact":"<out-dir>/generated.png","sha256":...,"estimateUsd":...}。さらに model、job が含まれ、動画の場合は lastFrameUsed、durationRequested、durationUsed（尺はモデルが生成する最も近い長さに調整されます。Grok（ローカル CLI）は6秒または10秒で生成し、ラストフレームは固定しません）、また、モデルが1:1に対応していないためフレームを16:9にパディングした場合は crop も含まれます。すべてのクリップは音声なしで公開されます。ルートがない場合は {"status":"no-route","fallback":"codeart2d"} が出力され、終了コード 3 で終了します。失敗すると error: <route>: <code>: <message> の1行が出力され、終了コード 1 で終了します。アカウントがリクエストに対応できないルート（クレジット不足、アクセス権なし、未サインイン）は次のルートに引き継がれます。モデレーションなどによる拒否の場合は停止します。プロンプトは自分で UTF-8 ファイルに書き込んでください。ローカルルートでは、サイズもすべての指示もプロンプトから取得します。

キー

各プロバイダーは、環境変数またはユーザー設定ファイルから、自身のキーのみを読み取ります。プロジェクトから読み取ることはありません。対象となるキーは OPENAI_API_KEY、GOOGLE_API_KEY または GEMINI_API_KEY（GOOGLE_API_KEY が優先）、XAI_API_KEY、ARK_API_KEY（BytePlus ModelArk）、FAL_KEY（fal.ai）です。設定ファイルの場所は、Windows では %APPDATA%\agent-sprite-forge\config.json、それ以外では ~/.config/agent-sprite-forge/config.json（$XDG_CONFIG_HOME が設定されている場合はその値）で、形式は {"OPENAI_API_KEY": "...", "FAL_KEY": "..."} です。任意で "models" と "providers": {"order": [...]} も設定できます。キーを出力、ログ記録、コミット、貼り付けしたり、プロンプトに含めたりしないでください。Codex または Grok のサインイン情報は API キーではありません。

支出と台帳

有料かローカルかを問わず、すべての呼び出しは見積もり額とともに <project>/.forge/ledger.jsonl に1行で記録されます（確認済みの料金がない場合、estimateUsd は null です。その場合は「価格不明」と伝えてください）。デフォルトでは上限はありません。ユーザーが希望した場合は、--budget-usd、--max-calls、FORGE_MAX_PAID_REQUESTS、FORGE_SESSION_IMAGES / FORGE_SESSION_VIDEOS で上限を設定できます。python "<skill-dir>/scripts/media_ledger.py" summary で支出を確認できます。結果が不明な呼び出しは media_ledger.py settle <id> --status ... で締めてください。

低レベルツール

必要なもの	コマンド
API リクエストを手動で1回実行（--execute まではドライラン）	generate_media.py image または video に --provider、--model、--prompt-file、--out-dir を指定します（api-usage.md）
動画または fal.ai ジョブの再課金なしでのポーリングまたはダウンロード	generate_media.py resume --job <out>/job.json
ローカル CLI を手動で1回実行	cli_media.py image --route codex-cli --prompt-file <txt> --output-dir <new> --execute（cli-routes.md）
ローカル実行がタイムアウトまたは中断した場合	cli_media.py resume --run <id>、続けて --adopt を指定します（CLI は再実行されません）
Codex が生成した画像がプロジェクト内にない場合	cli_media.py adopt --codex-thread <thread-id> --output-dir <new>
多数のジョブ	generate_media.py batch または cli_media.py batch
ローカルルートを事前に検証（任意）	forge_doctor.py --verify-route <route> --execute（クォータを1回消費）

ホストに関する注意事項

• Codex： image_gen は独自のツールです。キーが設定されていない場合はこれを使い、結果を取り込みます（cli_media.py adopt）。スクリプトは route_media.py を介して Codex（ローカル CLI）にアクセスします。このスキルは Codex では明示的に指定した場合のみ使用されます。
• Claude Code： メディアツールはありません。route_media.py は API またはローカル CLI を使用します。<skill-dir> は ${CLAUDE_SKILL_DIR} です。結果は Read で確認してください。
• Grok： ネイティブのメディアツールは独自のツールです。同じ grok 実行ファイルが、ほかのホスト向けの「Grok（ローカル CLI）」ルートになります。エージェントの設定については、agent-profiles/README.md を参照してください。

コマンドと出力

各ツールは、ユーザーのプロジェクトのルートから1行のコマンドとして実行します：python "<skill-dir>/scripts/<tool>.py" ...。出力はプロジェクト内の新しい --out-dir に保存されます。結果は未加工のメディアです。アイデンティティ、サイズ、アルファ、動き、継ぎ目の確認を行う担当スキルに渡してください。プロンプト、入力ハッシュ、ジョブ ID、結果ハッシュを保持し、リクエストしたモデルと返されたモデルを別々に報告してください。プロバイダーについては provider-survey.md（最終確認日：2026-10-06、サービス終了日を記載）を参照してください。機能については references/capabilities.json（python "<skill-dir>/scripts/media_providers.py" list）、価格については references/prices.json、データ契約については references/schemas/media.schema.json を参照してください。