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

프로 티어 (스토리보드 모자이크 및 비디오용 캐릭터 시트):

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

프로는 --size만 허용하며, --aspect-ratio / --image-size는 없습니다. 일반적인 크기: 1024x1024, 1280x720, 720x1280, 1920x1920, 2560x1440, 1440x2560, 3840x2160, 2160x3840

--label은 생략 시 잘린 프롬프트(≤30자)로 기본 설정됩니다. 더 나은 캡션이 있으면 명시적으로 전달하세요.

--ref-source-id 순서대로 @Image1, @Image2, …를 사용하세요. CLI는 참조당 하나의 derived 엣지를 생성합니다.

외부 URL은 먼저 mirror_url.js --url <URL>로 미러링한 후, 반환된 node_id를 --ref-source-id로 전달하세요.

노트가 이미지를 생성한 경우 --source-node-id <note_id>를 전달하세요.

ASCII 아트나 마크다운 임베딩으로 이미지를 직접 만들려고 하지 말고 CLI를 호출하세요.

최초 사용 이미지 모드

한 번만 묻는 흐름 및 모드별 가격에 대해서는 프로젝트 PROJECT_AGENT.md의 "최초 사용 생성 선택 사항"을 참조하세요.

모드 매핑: Standard 2K -> generate_image.js --image-size 2K; Pro 2K -> 프로 정확한 2K; Max quality -> 프로 정확한 4K.

패턴

상황에 맞는 것을 선택하세요. 소스 조회는 프로젝트 PROJECT_AGENT.md의 "컨텍스트 선택"을 따르세요. 이 스킬은 이미지 전용 프롬프트 및 CLI 형태만 소유합니다.

캐릭터 사전 점검. 먼저 물어보세요: 이 캐릭터가 다운스트림 비디오(비디오, 클립, 프로모, 宣传片, 短片, 连续剧, 영화, 장면, 拍片, 샷, 단편 영화)에 등장합니까?

1. workflow.json에서 업로드된 참조(subtype:"reference", metadata.source:"user_upload", 보관되지 않음)를 읽습니다.
2. 비디오 연동 -> 패턴 7, 패턴 1 사용 금지. 가능하면 3개 이상의 배우 참조 사용; 0-2개 참조인 경우 텍스트 전용 4패널 시트 생성.
3. 실행 전에 한 줄로 알리고, 패턴 1로 전환할 수 있도록 허용합니다.
4. 일회성 정적 아트/포스터/초상화 -> 패턴 1.

이 사전 점검은 필수입니다. 패턴 1의 단일 정면 초상화는 비디오 모델에 너무 좁은 앵커를 제공하여 샷마다 정체성이 달라집니다. 비디오 작업에서 바로 패턴 1로 건너뛰는 것이 가장 흔한 실수입니다.

스토리/스크립트 앵커 기본값. script-compose 또는 story-to-video-workflow가 분석을 여기로 라우팅하는 경우:

• 주요 캐릭터당 하나의 기본 4패널 시트.
• 주요 캐릭터 변형에 대한 추가 시트: 나이, 의상/유니폼/변장, 부상/더러움/젖음/피 묻음 상태, 변신, 또는 연속성에 중요한 외형.
• 샷에 영향을 미치는 배경에 대한 상세 위치 앵커.
• 프레이밍/스케일/시간/날씨/조명/세트/스토리 상태/근접 디테일 범위 변경에 대한 동일 위치 변형.
• 앵커 이후 참조-클립 렌더링을 선호합니다. 스토리보드는 요청 시, 제어가 어렵거나 진단이 필요한 경우에만 사용합니다.
• 예산/속도를 이유로 주요 변형을 생략하지 마세요. 호출자는 먼저 비디오 해상도/런타임을 조정해야 합니다.

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 "..." — 참조 없음. 캐릭터는 정체성 앵커이지, 파생물이 아닙니다.
• 프롬프트 템플릿:

  [스타일] [NAME]의 캐릭터 초상화, [역할]. [나이, 체격, 의상, 특징]. 정면 중간 클로즈업, 눈높이, 카메라를 직접 응시, 중립적 표정. 평범한 중립 배경, 부드럽고 균일한 조명. 극적인 그림자, 스타일화된 조명, 측면 프로필, 여러 시점 금지.

• 프로젝트 스타일을 상속하거나 기본값을 사실적으로 설정합니다. 이름 없는 캐릭터에 이름을 지정합니다.
• 엣지 없음 — 캐릭터는 루트이므로 --ref-source-id를 사용하지 않습니다.

2. 로케이션 설정 스틸

트리거: 로케이션 설정/디자인/상상, 또는 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>] — 참조 없음. 로케이션은 설정 앵커이지, 파생물이 아닙니다.
• 프롬프트 템플릿:

  [스타일] [LOCATION NAME]의 설정 스틸. [시각적 브리핑 — 건축, 조명, 분위기]. 와이드 샷, 눈높이, 캐릭터 없음.

• 프레임에 캐릭터가 없도록 유지합니다. 건축/레이아웃, 표면, 세트, 시대, 날씨, 시간, 조명 및 관련된 스토리 상태를 포함합니다.
• 동일 위치 변형은 장소 정체성을 유지하면서 와이드/클로즈 스케일, 주야간, 날씨, 세트, 손상 또는 디테일 범위를 변경합니다.
• 기본적으로 참조 엣지가 없습니다. 로케이션이 스크립트 또는 샷 노트에서 파생된 경우 --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>.

• 프롬프트는 변환 형식으로 작성합니다. 전체 재설명이 아닙니다:

  <구체적인 변경>. 나머지는 모두 유지.

  ✅ "비를 눈으로 바꿉니다. 형사, 의상, 카메라 프레이밍은 변경하지 않습니다." ✅ "동일한 캐릭터의 전체 3D 턴어라운드 시트로 렌더링합니다. 얼굴, 의상, 비율을 유지합니다." ❌ "밤에 눈 내리는 골목에 있는 형사, 트렌치코트를 입고..." — 과도하게 지정하여 정체성이 변합니다.

• CLI는 --ref-source-id를 기반으로 <source.id>에서 파생 엣지를 생성합니다.

• 다단계 체인은 단계당 하나의 엣지/호출을 사용합니다. 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당 하나의 derived 엣지를 생성합니다.

5. 독립형 스틸

트리거: 기존 캔버스 콘텐츠와 관련 없는 새로운 이미지("해질녘 산 생성", "필름 누아르 골목 — 설정만").

• 일반 node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..."에 적절한 기본값 사용(16:9, 2K, 사용자가 달리 요청하지 않는 한). 서브타입이나 참조 없음.

6. 스토리보드 모자이크 — 클립/샷 노트당 하나의 합성 이미지

트리거: 스토리보드, 모자이크, 그리드, 샷 목록, 커버리지, 키프레임 시트, 샷 계획, 이미지 프리비즈. 출력은 패널당 하나의 이미지가 아니라 클립/≤15초 샷 노트당 하나의 합성 이미지입니다.

• 도구/호출: 모자이크당 하나의 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가 설정하는 노드 필드

• 모자이크당 하나의 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패널 캐릭터 디자인 제작", "다운스트림 비디오 작업을 위한 제작 레퍼런스 시트 생성".

출력: 정면-전신 / 측면-전신 / 후면-전신 / 클로즈업-흉상 시트 하나로, 비디오에 직접 --ref-source-id로 전달됩니다.

• 사전 점검: 업로드된 참조 노드(subtype:"reference", 가급적 3장 이상의 사진)를 식별합니다. 한 줄로 참조 개수를 확인합니다.
• 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>] — 프로 티어가 캐릭터 시트의 기본값입니다. 패널 레이아웃, 텍스트 억제, 정체성 일관성이 중요하기 때문입니다. --aspect-ratio 또는 --image-size를 전달하지 마십시오. 3개 미만의 참조로 모드 A를 절대 실행하지 마십시오(모델이 가지고 있는 한 각도에 과적합됩니다).
• 0-2개의 배우 참조가 있는 경우, references/character-sheet.md의 모드 B 텍스트 전용 명령을 사용하세요: 동일한 프로 명령이지만 모든 배우 사진 --ref-source-id를 생략합니다. --source-node-id는 스크립트나 샷 노트가 디자인을 생성한 경우에만 포함합니다.
• 기본 캐릭터 또는 재질 변형당 하나의 호출/시트. 변형 전에 기본을 생성합니다. 정체성을 유지하는 변형의 경우, 기본 시트를 참조로 전달하고 지속적인 의상/상태 변경만 설명합니다.
• 다운스트림 샷에 대해 시트를 --ref-source-id <sheet_id>로 사용합니다. 일반적인 자르기가 필요하지 않습니다.

**정확한 4패널 프롬프트 템플릿, 선택적 각도별 자르기, 주의 사항(텍스트 없음 규칙, 사진 우선 순위, 정확한 패널 수)**에 대해서는 references/character-sheet.md를 참조하세요.

CLI가 설정하는 노드 필드

• data.subtype = "character"인 하나의 image_result 노드.
• CLI 플래그의 data.name, data.role, data.description.
• --ref-source-id당 하나의 derived 엣지 (따라서 시트는 삼각 측량된 각 배우 사진과 출처 연결됩니다).

CLI 반환 후

초안 단계 JSON의 경우 가격/상태에 대한 한 문장 — 프로젝트 PROJECT_AGENT.md의 "초안 게이트"를 참조하세요. 최종 결과의 경우, 프로젝트 매뉴얼의 다음 단계 권장 규칙을 따르세요.