Utopai-Research/pai-pro

Structure CLI

Niveau standard :

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> ...]

Niveau Pro pour les mosaïques de storyboard et les fiches de personnages liées à la vidéo :

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> ...]

Le niveau Pro n'accepte que --size ; pas de --aspect-ratio / --image-size. Tailles courantes : 1024x1024, 1280x720, 720x1280, 1920x1920, 2560x1440, 1440x2560, 3840x2160, 2160x3840.

--label prend par défaut le prompt tronqué (≤30 caractères) s'il est omis ; passez-en un explicite lorsque vous avez une meilleure légende.

Utilisez @Image1, @Image2, … dans l'ordre de --ref-source-id. Le CLI émet une arête derived par référence.

Miroitiez d'abord les URLs externes avec mirror_url.js --url <URL>, puis passez le node_id retourné via --ref-source-id.

Si une note a créé l'image, passez --source-node-id <note_id>.

N'essayez pas d'inventer des images via de l'art ASCII ou du markdown intégré — appelez le CLI.

Mode d'image de première utilisation

Pour le flux de demande unique et les prix par mode, voir le PROJECT_AGENT.md du projet § « Choix de génération de première utilisation ».

Correspondance des modes : Standard 2K -> generate_image.js --image-size 2K ; Pro 2K -> pro exact 2K ; Max quality -> pro exact 4K.

Modèles

Choisissez celui qui convient. Pour la recherche de source, suivez le PROJECT_AGENT.md du projet § « Choix du contexte » ; ce skill ne possède que la forme spécifique du prompt et la structure CLI.

Pré-vol du personnage. Demandez d'abord : ce personnage apparaîtra-t-il dans une vidéo en aval (vidéo, clip, promo, 宣传片, 短片, 连续剧, film, scène, 拍片, plan, court métrage) ?

1. Lisez workflow.json pour les références téléchargées (subtype:"reference", metadata.source:"user_upload", non archivées).
2. Lié à la vidéo -> Modèle 7, pas le Modèle 1. Utilisez ≥3 références d'acteur si disponibles ; avec 0-2 références, générez une fiche texte à 4 panneaux.
3. Annoncez une ligne avant de lancer ; autorisez la redirection vers le Modèle 1.
4. Image/art/affiche/portrait statique unique -> Modèle 1.

Ce pré-vol est non négociable. Le portrait frontal unique du Modèle 1 donne au modèle vidéo une ancre trop étroite ; l'identité dérive d'un plan à l'autre. Passer directement au Modèle 1 pour un travail vidéo est l'erreur la plus courante.

Ancrage par défaut du scénario/script. Lorsque script-compose ou story-to-video-workflow achemine une décomposition ici :

• Une fiche de base à 4 panneaux par personnage matériel.
• Fiches supplémentaires pour les variantes de personnage matériel : âge, garde-robe/uniforme/déguisement, état blessé/sale/mouillé/sanglant, transformation, ou apparences importantes pour la continuité.
• Ancres de lieu détaillées pour les décors qui affectent les plans.
• Variantes de même lieu pour les changements de cadre/échelle/temps/météo/lumière/habillage/état de l'histoire/couverture de détail rapproché.
• Préférez la référence au clip après les ancres. Storyboard uniquement si demandé, difficile à contrôler, ou nécessaire pour le diagnostic.
• Ne supprimez pas les variantes matérielles pour des raisons de budget/vitesse ; l'appelant doit d'abord ajuster la résolution/la durée de la vidéo.

1. Portrait de personnage (images fixes uniques uniquement)

Déclencheurs : portrait/photo/hero/méchant/lead de personnage uniquement pour des images fixes uniques. Lié à la vidéo -> Modèle 7.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 9:16 --image-size 2K --subtype character --name "Détective Morris" --role "..." --description "..." — pas de références. Un personnage est une ancre d'identité, pas un dérivé.
• Modèle de prompt :

  [style] portrait de personnage de [NOM], [rôle]. [âge, silhouette, garde-robe, traits distinctifs]. Gros plan frontal, niveau des yeux, regardant directement la caméra, expression neutre. Fond neutre uni, éclairage doux et uniforme. Pas d'ombres dramatiques, pas d'éclairage stylisé, pas de profil, pas de vues multiples.

• Héritez du style du projet ou par défaut réaliste. Nommez les personnages sans nom.
• Pas d'arêtes — les personnages sont des racines, donc pas de --ref-source-id.

2. Plan d'établissement du lieu

Déclencheurs : établir/concevoir/imager un lieu, ou approbation d'une offre de lieu de script-compose.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Chaussée" --description "..." [--source-node-id <script_or_shot_note_id>] — pas de références. Un lieu est une ancre de décor, pas un dérivé.
• Modèle de prompt :

  [style] plan d'établissement de [NOM DU LIEU]. [descriptif visuel — architecture, éclairage, atmosphère]. Plan large, niveau des yeux, aucun personnage présent.

• Gardez le cadre vide de personnages. Incluez l'architecture/l'agencement, les surfaces, l'habillage, l'époque, la météo, l'heure, la lumière et l'état de l'histoire lorsque cela est pertinent.
• Les variantes de même lieu préservent l'identité du lieu tout en modifiant l'échelle large/rapprochée, le jour/nuit, la météo, l'habillage, les dégâts ou la couverture des détails.
• Pas d'arêtes de référence par défaut. Si le lieu est dérivé d'une note de script ou de plan, utilisez --source-node-id pour que l'arête de paternité atterrisse.
• Suite : après le dernier lieu scénarisé, recommandez le prochain rendu de référence vers clip. Mentionnez le storyboard uniquement si demandé/nécessaire.

3. Édition / variation / rotation d'une image existante

Déclencheurs : modifier/échanger/remplacer/ajouter/supprimer/retoucher/et-si/variation sur une image existante.

• Identifiez le nœud source (généralement le image_result le plus récent, ou celui que l'utilisateur a nommé). Récupérez source.id et source.metadata.aspect_ratio.

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

• Le prompt décrit une transformation, pas une re-description complète :

  <changement concret>. Préservez tout le reste.

  ✅ « Remplacez la pluie par de la neige tombante. Gardez le détective, la garde-robe et le cadrage de la caméra inchangés. » ✅ « Rendez-le sous forme d'une fiche de rotation 3D complète du même personnage. Préservez le visage, la garde-robe et les proportions. » ❌ « Un détective dans une ruelle enneigée la nuit portant un trench-coat… » — trop spécifique, l'identité dérive.

• Le CLI émet l'arête dérivée de <source.id> basée sur --ref-source-id.

• Les chaînes en plusieurs étapes utilisent une arête/appel par étape ; n'aplatissez pas A -> C.

4. Scène mettant en scène des personnages existants

Déclencheurs : placer le personnage dans un décor/plan de X et Y / action du personnage dans un lieu.

• Identifiez chaque personnage impliqué — tout image_result de cette personne (jusqu'à 16). Collectez l'id de chacun.
• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <adapter au plan> --image-size 2K --ref-source-id <char1.id> --ref-source-id <char2.id> ....
• Prompt : la description complète de la scène. Nommez chaque personnage par son rôle pour que le générateur lie l'identité au rôle. Référez-vous à eux dans le prompt comme @Image1, @Image2, … dans l'ordre de --ref-source-id.
• Pas de --subtype — une scène n'est ni un personnage ni une édition. Le CLI émet une arête dérivée par --ref-source-id.

5. Image fixe autonome

Déclencheurs : une image nouvelle sans rapport avec le contenu existant du canvas (« générez une montagne au crépuscule », « une ruelle noire — juste le décor »).

• Simple node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." avec des valeurs par défaut raisonnables (16:9, 2K sauf si l'utilisateur demande autre chose). Pas de subtype, pas de refs.

6. Mosaïque de storyboard — un composite par clip / note de plan

Déclencheurs : storyboard, mosaïque, grille, liste de plans, couverture, feuille de keyframes, planification de plans, prévisualisation d'image. La sortie est UN composite par clip/note de plan <=15s, pas une image par panneau.

• Outil/appel : un generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Plan <N>" --source-node-id <shot_note_id> par mosaïque.
• Taille : par défaut 2560x1440 ; la forme de la grille est la disposition des cellules, pas la forme du canvas. Remplacez uniquement pour un portrait/carré/vertical/ratio explicite :
  • « storyboard 2x2 » → 2560x1440 (par défaut)
  • « storyboard carré 2x2 » → 1920x1920
  • « storyboard portrait 2x2 » → 1440x2560
  • « mosaïque verticale 2x4 » → 1440x2560
• Grille/réf. : par défaut 2×2. Passez les références de personnage/lieu pertinentes (≤32). Avertissez avant 3×3+ ; recommandez des feuilles plus petites.

Pour le pré-vol du canvas, la logique d'itération par note de plan, l'incitation à l'ancre manquante, le modèle de prompt textuel, et la couverture par défaut des panneaux lorsqu'aucune tranche de script n'existe : voir references/storyboard-mosaic.md.

Champs de nœud définis par le CLI

• Un nœud image_result PAR mosaïque.
• Définissez data.subtype = "storyboard" en passant --subtype storyboard.

7. Fiche de référence de personnage (par défaut pour TOUT travail de personnage lié à la vidéo — avec ou sans références d'acteur)

À utiliser de manière proactive pour tout personnage qui apparaîtra dans une vidéo en aval, quelle que soit la disponibilité des références d'acteur.

Mode A — ≥3 références d'acteur téléchargées. Passez les photos comme --ref-source-id ; ajoutez --source-node-id <note_id> si un script/plan a créé le design.

Mode B — 0-2 références / à partir de zéro. Omettez les références d'acteur ; décrivez explicitement l'âge/la silhouette/la garde-robe/les traits distinctifs. Ajoutez --source-node-id <note_id> lorsqu'il est créé par une note.

Se déclenche également sur les demandes explicites : « designer une fiche de personnage / rotation / fiche de référence / design de personnage pour [personnage] », « faire un design de personnage en 4 panneaux », « générer une fiche de référence de production pour un travail vidéo en aval ».

Sortie : une fiche Face-entière / Profil-entière / Dos-entière / Buste-gros plan, passée directement à la vidéo comme --ref-source-id.

• Pré-vol : identifiez les nœuds de référence téléchargés (subtype:"reference", idéalement ≥3 photos). Confirmez le nombre de références en une ligne.
• node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 --subtype character --name "<nom_personnage>" --role "..." --ref-source-id <ref1> --ref-source-id <ref2> --ref-source-id <ref3> [--source-node-id <script_or_shot_note_id>] — le niveau Pro est la valeur par défaut pour les fiches de personnage car la disposition des panneaux, la suppression du texte et la cohérence de l'identité sont cruciales. Ne passez pas --aspect-ratio ou --image-size. Ne lancez jamais le Mode A avec moins de 3 références (le modèle se surajuste au seul angle qu'il a).
• Avec 0-2 références d'acteur, utilisez la commande textuelle du Mode B de references/character-sheet.md : même commande Pro, mais omettez tout --ref-source-id de photo d'acteur ; incluez --source-node-id uniquement lorsqu'un script ou une note de plan a créé le design.
• Un appel/fiche par personnage de base ou variante matérielle. Générez la base avant les variantes. Pour les variantes préservant l'identité, passez la fiche de base comme référence et décrivez uniquement le changement persistant de garde-robe/d'état.
• Utilisez la fiche comme --ref-source-id <sheet_id> pour les plans en aval ; aucun recadrage normal n'est nécessaire.

Pour le modèle de prompt textuel exact à 4 panneaux, les recadrages optionnels par angle, et les pièges (règle sans texte, priorité photo, nombre exact de panneaux) : voir references/character-sheet.md.

Champs de nœud définis par le CLI

• Un nœud image_result avec data.subtype = "character".
• data.name, data.role, data.description à partir des indicateurs CLI.
• Une arête derived par --ref-source-id (de sorte que la fiche soit liée par provenance à chaque photo d'acteur à partir de laquelle elle a été triangulée).

Après le retour du CLI

Pour le JSON de phase d'ébauche, une phrase avec le prix/statut — voir le PROJECT_AGENT.md du projet § « Porte d'ébauche ». Pour les résultats terminaux, suivez la règle de recommandation de l'étape suivante du manuel du projet.