Kamui i2v共通基盤

概要

Kamui MCPによるi2v生成の共通部分だけを扱う。用途固有の入力画像作成、プロンプト設計、ループ補修、テロップ焼き込み、品質判断は呼び出し側スキルに残す。

役割

• references/models.jsonを唯一のモデルカタログにする。
• プロジェクトに.mcp.jsonがない場合はカレントワークスペースまたはスキルの親プロジェクトにある.mcp.jsonを初期配置元にし、必要なKamui MCPサーバーを安全にマージする。
• KAMUI_CODE_PASS_KEYを環境変数または.env.localから読み、キー本体を.mcp.jsonへ保存しない。
• i2vジョブをモデルごとに直列実行する。
• 送信済みrequest_idがある場合は再課金せずポーリングから再開する。
• ダウンロードした動画から音声ストリームを除去する。
• inspection.json、コンタクトシート、比較HTMLを作成する。

直接実行

モデル一覧を表示する:

python3 <core-skill>/scripts/generate.py --list-models

ループ用i2vジョブを実行する:

python3 <core-skill>/scripts/generate.py INPUT_IMAGE \
  --project PROJECT_ROOT \
  --task TASK_NAME \
  --mode loop \
  --prompt-file PROMPT_FILE \
  --comparison

リポジトリがoutput/<generation_type>/<model_name>/を要求する場合は、そのモデルディレクトリ配下を明示的な出力先として渡す:

python3 <core-skill>/scripts/generate.py INPUT_IMAGE \
  --project PROJECT_ROOT \
  --task TASK_NAME \
  --output-root PROJECT_ROOT/output/i2v/MODEL_SLUG \
  --model MODEL_SLUG

--output-dirを使うと、タスク名ディレクトリを含む完全な出力先を直接指定できる。

人物メッセージ用i2vジョブを実行する:

python3 <core-skill>/scripts/generate.py INPUT_IMAGE \
  --project PROJECT_ROOT \
  --task TASK_NAME \
  --mode message \
  --prompt-file PROMPT_FILE \
  --comparison

明示的にモデル比較する場合は--modelを複数回渡す。--modelがない場合、スクリプトはreferences/models.jsonから有効な最安モデルを1つ選ぶ。--mode loopではsupports_loopも必須条件にする。

課金される生成前にモデル、秒数、解像度、概算費用を確認したい場合は--dry-runを使う。

MCP設定

generate.pyは--no-setup-mcpが指定されていない限りsetup_mcp.pyを自動実行する。設定だけ行う場合:

python3 <core-skill>/scripts/setup_mcp.py \
  --project PROJECT_ROOT \
  --model MODEL_SLUG

MCP設定の挙動を変更する前にmcp-setup.mdを読む。

出力契約

generate.pyは既定でPROJECT_ROOT/output/<task>/へ次を出力する。--output-rootを指定するとOUTPUT_ROOT/<task>/へ出力し、--output-dirを指定するとそのディレクトリをそのまま出力先にする。

<task-output-dir>/
├── <model>.mp4
├── manifest.json
├── inspection.json
├── index.html
├── _assets/
│   └── source-image.<ext>
├── _inspection/
│   └── <model>-contact-sheet.jpg
└── _metadata/
    └── <model>/
        ├── request.json
        ├── submit-response.json
        └── result.json

_delivery/、_telop/、準備済み入力画像などの追加出力フォルダは呼び出し側スキルで作成する。

他スキルからの再利用

上位のi2vスキルでは、このSKILL.mdを読んだうえで、このスキルのスクリプトを直接実行する:

python3 .codex/skills/dev/media-gen/kamui-i2v-core/scripts/generate.py ...

後方互換のコマンドが必要な場合は、呼び出し側スキルに薄いラッパーだけを残し、../kamui-i2v-core/scripts/<script>.pyを解決して引数を転送する。モデルカタログ、MCP設定コード、ポーリング処理、検査コード、比較テンプレートを呼び出し側スキルへコピーしない。

保守

• モデル名、MCP URL、ツール名、価格、秒数、解像度、パラメータフィールドはmodels.jsonだけで更新する。
• Kamui MCP全体の初期設定を更新する場合は、ツールキットルートの.mcp.jsonを正本として更新する。キー本体などの秘密情報は含めない。
• scripts/kamui_i2v.pyには外部Python依存を追加しない。
• すべてのi2v用途に安全でない限り、用途固有のプロンプトルールをここへ追加しない。
• カタログ変更後はpython3 <core-skill>/scripts/generate.py --list-modelsとpython3 <core-skill>/scripts/setup_mcp.py --list-modelsを実行する。