Utopai-Research/pai-pro

CLIの形状

標準ティア:

node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." [--aspect-ratio 16:9] [--image-size 2K] [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

Proティア（ストーリーボードモザイクおよび映像向けキャラクターシート用）:

node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

Proは --size のみを受け付けます。 --aspect-ratio / --image-size はありません。一般的なサイズ: 1024x1024, 1280x720, 720x1280, 1920x1920, 2560x1440, 1440x2560, 3840x2160, 2160x3840。

--label は、省略された場合、デフォルトで切り詰められたプロンプト（最大30文字）になります。より適切なキャプションがある場合は、明示的に渡してください。

--ref-source-id の順序で @Image1、@Image2、…を使用します。CLIは参照ごとに1つの derived エッジを出力します。

外部URLは、最初に mirror_url.js --url <URL> でミラーリングし、その後、返された node_id を --ref-source-id 経由で渡します。

ノートが画像を作成した場合は、--source-node-id <note_id> を渡します。

ASCIIアートやマークダウンの埋め込みで画像を創作しようとしないでください。CLIを呼び出してください。

初回使用時の画像モード

1回だけの質問フローとモード別の価格については、プロジェクトの PROJECT_AGENT.md §「初回生成の選択肢」を参照してください。

モードマッピング: Standard 2K -> generate_image.js --image-size 2K; Pro 2K -> Pro の正確な2K; Max quality -> Pro の正確な4K。

パターン

適切なものを選んでください。ソースの検索については、プロジェクトの PROJECT_AGENT.md §「コンテキストの選択」に従ってください。このスキルは、画像固有のプロンプトとCLIの形状のみを担当します。

キャラクタープリフライト。 最初に尋ねます: このキャラクターは下流の映像（video, clip, promo, 宣传片, 短片, 连续剧, film, scene, 拍片, shot, short film）に登場しますか？

1. workflow.json を読み、アップロードされた参照（subtype:"reference", metadata.source:"user_upload", アーカイブされていないもの）を確認します。
2. 映像に関連する場合 -> パターン1ではなく、パターン7を使用します。可能な場合は3つ以上のアクター参照を使用します。0～2個の参照の場合は、テキストのみの4パネルシートを生成します。
3. 実行前に1行でアナウンスし、パターン1へのリダイレクトを許可します。
4. 1回限りの静的アート/ポスター/ポートレート -> パターン1。

このプリフライトは必須です。パターン1の単一の正面ポートレートでは、ビデオモデルにとってアンカーが狭すぎます。ショットごとにアイデンティティがずれます。映像作品でいきなりパターン1に進むことは、最も一般的な間違いです。

ストーリー/スクリプトアンカーのデフォルト。 script-compose または story-to-video-workflow が内訳をここにルーティングする場合:

• 主要キャラクターごとに1枚の基本4パネルシート。
• 主要キャラクターのバリエーション用の追加シート: 年齢、ワードローブ/ユニフォーム/変装、負傷/汚れ/濡れ/血まみれの状態、変身、または連続性に重要な外見。
• ショットに影響を与える設定用の詳細なロケーションアンカー。
• フレーミング/スケール/時間/天候/光/装飾/ストーリー状態/クローズアップ詳細範囲の変更に対する、同じロケーションのバリエーション。
• アンカーの後は、参照からクリップへのレンダリングを優先します。ストーリーボードは、リクエストされた場合、制御が難しい場合、または診断に必要な場合にのみ使用します。
• 予算/速度のために主要なバリエーションを削除しないでください。呼び出し元は最初にビデオ解像度/実行時間を調整する必要があります。

1. キャラクターポートレート（1回限りの静止画のみ）

トリガー: 1回限りの静止画のためのキャラクターポートレート/ヘッドショット/ヒーロー/ヴィラン/リーダー のみ。映像に関連する場合 -> パターン7。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 9:16 --image-size 2K --subtype character --name "Detective Morris" --role "..." --description "..." — 参照なし。キャラクターはアイデンティティアンカーであり、派生物ではありません。
• プロンプトテンプレート:

  [style] character portrait of [NAME], [role]. [age, build, wardrobe, distinguishing features]. Front-facing medium close-up, eye-level, looking directly at camera, neutral expression. Plain neutral background, soft even lighting. No dramatic shadows, no stylized lighting, no side profile, no multiple views.

• プロジェクトのスタイルを継承するか、デフォルトでリアルにします。名前のないキャラクターには名前を付けます。
• エッジなし — キャラクターはルートであるため、--ref-source-id はなし。

2. ロケーション establishing still

トリガー: ロケーションの確立/デザイン/描写、または script-compose のロケーション提案の承認。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Causeway" --description "..." [--source-node-id <script_or_shot_note_id>] — 参照なし。ロケーションは設定アンカーであり、派生物ではありません。
• プロンプトテンプレート:

  [style] establishing still of [LOCATION NAME]. [visual brief — architecture, lighting, atmosphere]. Wide shot, eye-level, no characters present.

• フレーム内にキャラクターを入れないでください。建築/レイアウト、表面、装飾、時代、天候、時間、光、および関連する場合はストーリーの状態を含めます。
• 同じロケーションのバリエーションは、場所のアイデンティティを維持しながら、ワイド/クローズのスケール、昼夜、天候、装飾、損傷、または詳細範囲を変更します。
• デフォルトでは参照エッジなし。ロケーションがスクリプトまたはショットノートから派生した場合は、--source-node-id を使用して、オーサーシップエッジが配置されるようにします。
• フォローアップ: 最後にスクリプト化されたロケーションの後、次の参照からクリップへのレンダリングを推奨します。ストーリーボードは、リクエストまたは必要な場合にのみ言及します。

3. 既存画像の編集/バリエーション/ターンアラウンド

トリガー: 既存画像の変更/編集/交換/置換/追加/削除/微調整/what-if/バリエーション。

• ソースノード（通常は最新の image_result、またはユーザーが指定したもの）を特定します。source.id と source.metadata.aspect_ratio を取得します。

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <source ratio> --image-size <source size or 2K> --subtype edit --source-node-id <source.id> --ref-source-id <source.id>。

• プロンプトは、完全な再説明ではなく、変換として記述します:

  <concrete change>. Preserve everything else.

  ✅ "Change the rain to falling snow. Keep the detective, wardrobe, and camera framing unchanged." ✅ "Render as a full 3D turnaround sheet of the same character. Preserve face, wardrobe, and proportions." ❌ "A detective in a snowy alley at night wearing a trench coat…" — 過剰指定、アイデンティティがずれます。

• CLIは、--ref-source-id に基づいて <source.id> から派生エッジを出力します。

• マルチステップチェーンは、ステップごとに1つのエッジ/呼び出しを使用します。A -> C に平坦化しないでください。

4. 既存キャラクターが登場するシーン

トリガー: XとYの設定/ショットにキャラクターを配置 / ロケーションでのキャラクターアクション。

• 関係する各キャラクター（その人物の image_result、最大16個まで）を特定します。それぞれの id を収集します。
• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <fit the shot> --image-size 2K --ref-source-id <char1.id> --ref-source-id <char2.id> ...。
• プロンプト: 完全なシーンの説明。各キャラクターをその役割で名前指定して、ジェネレーターがアイデンティティを役割にバインドできるようにします。--ref-source-id の順序で、プロンプト内で @Image1、@Image2、…としてそれらを参照します。
• --subtype なし — シーンはキャラクターでも編集でもありません。CLIは --ref-source-id ごとに1つの派生エッジを出力します。

5. スタンドアロン静止画

トリガー: 既存のキャンバスコンテンツに関係のない新しい画像（「夕暮れの山を生成」、「ノワールの路地 — 設定だけ」）。

• 標準の node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." （ユーザーが特に指定しない限り、16:9、2Kがデフォルト）。サブタイプなし、参照なし。

6. ストーリーボードモザイク — クリップ/ショットノートごとに1つの合成画像

トリガー: ストーリーボード、モザイク、グリッド、ショットリスト、カバレッジ、キーフレームシート、ショット計画、画像プレビス。出力は、クリップ/15秒以下のショットノートごとに1つの合成画像であり、パネルごとの画像ではありません。

• ツール/呼び出し: モザイクごとに1つの generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Shot <N>" --source-node-id <shot_note_id>。
• サイズ: デフォルトは 2560x1440。グリッド形状はセルレイアウトであり、キャンバス形状ではありません。明示的なポートレート/正方形/垂直/比率の場合のみオーバーライド:
  • "2x2 storyboard" → 2560x1440（デフォルト）
  • "2x2 square storyboard" → 1920x1920
  • "2x2 portrait storyboard" → 1440x2560
  • "vertical 2x4 mosaic" → 1440x2560
• グリッド/参照: デフォルトは2×2。関連するキャラクター/ロケーションの参照（最大32個）を渡します。3×3以上の場合は警告し、より小さいシートを推奨します。

キャンバスのプリフライト、ショットノートごとの反復ロジック、不足アンカーの促し、逐語的なプロンプトテンプレート、スクリプトスライスがない場合のデフォルトパネルカバレッジについては: references/storyboard-mosaic.md を参照してください。

CLIが設定するノードフィールド

• モザイクごとに1つの image_result ノード。
• --subtype storyboard を渡すことで data.subtype = "storyboard" を設定します。

7. キャラクター参照シート （映像に登場するキャラクター作業のデフォルト — アクター参照の有無にかかわらず）

下流の映像に登場するキャラクターには、アクター参照の有無にかかわらず、プロアクティブに使用します。

モード A — 3つ以上のアップロードされたアクター参照。 写真を --ref-source-id として渡します。スクリプト/ショットがデザインを作成した場合は、--source-node-id <note_id> を追加します。

モード B — 0～2個の参照 / スクラッチから。 アクター参照を省略します。年齢/体格/ワードローブ/識別特徴を明示的に記述します。ノートによって作成された場合は --source-node-id <note_id> を追加します。

また、明示的な要求でも発動します: 「キャラクターシート/ターンアラウンド/参照シート/キャラクターデザインを作成」、「4パネルのキャラクターデザインを作成」、「下流の映像作業のためにプロダクション参照シートを生成」。

出力: 1枚の正面全身/側面全身/背面全身/バストアップクローズアップシート。--ref-source-id として直接ビデオに渡されます。

• プリフライト: アップロードされた参照ノード（subtype:"reference"、理想的には3枚以上の写真）を特定します。1行で参照数を確認します。
• node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 --subtype character --name "<character_name>" --role "..." --ref-source-id <ref1> --ref-source-id <ref2> --ref-source-id <ref3> [--source-node-id <script_or_shot_note_id>] — キャラクターシートでは、パネルレイアウト、テキスト抑制、アイデンティティの一貫性が重要なため、Proティアがデフォルトです。--aspect-ratio や --image-size は渡さないでください。3個未満の参照でモードAを実行しないでください（モデルが持っている1つのアングルに過適合します）。
• アクター参照が0～2個の場合は、references/character-sheet.md のモードBのテキストのみのコマンドを使用します: 同じProコマンドですが、すべてのアクター写真 --ref-source-id を省略します。スクリプトまたはショットノートがデザインを作成した場合にのみ --source-node-id を含めます。
• 基本キャラクターまたはマテリアルバリアントごとに1回の呼び出し/シート。バリアントの前に基本を生成します。アイデンティティを保持するバリアントの場合は、基本シートを参照として渡し、永続的なワードローブ/状態の変更のみを記述します。
• 下流のショットのために --ref-source-id <sheet_id> としてシートを使用します。通常のトリミングは必要ありません。

逐語的な4パネルプロンプトテンプレート、オプションのアングル別トリミング、および注意点（テキスト禁止ルール、写真優先、正確なパネル数）については: references/character-sheet.md を参照してください。

CLIが設定するノードフィールド

• data.subtype = "character" を持つ1つの image_result ノード。
• data.name、data.role、data.description はCLIフラグから。
• --ref-source-id ごとに1つの derived エッジ（これにより、シートは三角測量された各アクター写真に provenance リンクされます）。

CLIの戻り値の後

ドラフト段階のJSONの場合は、価格/ステータスを含む1文 — プロジェクトの PROJECT_AGENT.md §「ドラフトゲート」を参照してください。最終結果の場合は、プロジェクトマニュアルの次のステップ推奨ルールに従ってください。