Utopai-Research/pai-pro

Forma da CLI

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

Tier Pro para mosaicos de storyboard e folhas de personagem para vídeo:

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 aceita apenas --size; sem --aspect-ratio / --image-size. Tamanhos comuns: 1024x1024, 1280x720, 720x1280, 1920x1920, 2560x1440, 1440x2560, 3840x2160, 2160x3840.

--label assume o prompt truncado (≤30 caracteres) se omitido; passe um explícito quando tiver uma legenda melhor.

Use @Image1, @Image2, … na ordem de --ref-source-id. A CLI emite uma aresta derived por referência.

Espelhe URLs externas primeiro com mirror_url.js --url <URL>, depois passe o node_id retornado via --ref-source-id.

Se uma nota criou a imagem, passe --source-node-id <note_id>.

Não tente inventar imagens com arte ASCII ou incorporação de markdown — chame a CLI.

Modo de imagem para primeiro uso

Para o fluxo de perguntar uma vez e os preços por modo, veja o arquivo PROJECT_AGENT.md do projeto, seção "First-use generation choices".

Mapeamento de modos: Standard 2K -> generate_image.js --image-size 2K; Pro 2K -> pro exato 2K; Max quality -> pro exato 4K.

Padrões

Escolha o que se encaixa. Para busca de fontes, siga o PROJECT_AGENT.md do projeto, seção "Choosing context"; este skill possui apenas a forma da CLI e o prompt específico para imagens.

Pré-verificação de personagem. Primeiro pergunte: este personagem aparecerá em vídeo posterior (video, clip, promo, 宣传片, 短片, 连续剧, film, scene, 拍片, shot, short film)?

1. Leia workflow.json para referências enviadas (subtype:"reference", metadata.source:"user_upload", não arquivadas).
2. Vinculado a vídeo -> Padrão 7, não Padrão 1. Use ≥3 referências de atores quando disponíveis; com 0-2 referências, gere uma folha de 4 painéis apenas com texto.
3. Anuncie uma linha antes de disparar; permita redirecionamento para Padrão 1.
4. Arte estática única/pôster/retrato -> Padrão 1.

Esta pré-verificação é inegociável. O retrato frontal único do Padrão 1 dá ao modelo de vídeo uma âncora muito estreita; a identidade varia de cena para cena. Pular direto para o Padrão 1 para trabalho de vídeo é o erro mais comum.

Padrões de âncora para roteiro/script. Quando script-compose ou story-to-video-workflow encaminha uma divisão aqui:

• Uma folha base de 4 painéis por personagem material.
• Folhas extras para variantes de personagem material: idade, guarda-roupa/uniforme/disfarce, ferimento/sujo/molhado/sangrento, transformação, ou looks significativos para continuidade.
• Âncoras de local detalhadas para cenários que afetam as tomadas.
• Variantes do mesmo local para mudanças de enquadramento/escala/hora/clima/iluminação/decoração/estado da história/cobertura de detalhes próximos.
• Prefira referência-para-clip após as âncoras. Storyboard apenas se solicitado, difícil de controlar, ou necessário para diagnóstico.
• Não descarte variantes materiais por orçamento/velocidade; quem chama deve ajustar a resolução/tempo de execução do vídeo primeiro.

1. Retrato de personagem (apenas para imagens estáticas únicas)

Gatilhos: retrato/headshot/hero/vilão/líder de personagem apenas para imagens estáticas únicas. Vinculado a vídeo -> Padrão 7.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 9:16 --image-size 2K --subtype character --name "Detetive Morris" --role "..." --description "..." — sem referências. Um personagem é uma âncora de identidade, não uma derivação.
• Modelo de prompt:

  [estilo] retrato de personagem de [NOME], [papel]. [idade, biotipo, guarda-roupa, características distintivas]. Close-up médio frontal, nível dos olhos, olhando diretamente para a câmera, expressão neutra. Fundo neutro simples, iluminação suave e uniforme. Sem sombras dramáticas, sem iluminação estilizada, sem perfil, sem múltiplas vistas.

• Herde o estilo do projeto ou use realista como padrão. Nomeie personagens sem nome.
• Sem arestas — personagens são raízes, portanto sem --ref-source-id.

2. Imagem de estabelecimento de local

Gatilhos: estabelecer/projetar/visualizar um local, ou aprovação de uma oferta de local de script-compose.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Calçada" --description "..." [--source-node-id <id_da_nota_script_ou_tomada>] — sem referências. Um local é uma âncora de cenário, não uma derivação.
• Modelo de prompt:

  [estilo] imagem de estabelecimento de [NOME DO LOCAL]. [breve visual — arquitetura, iluminação, atmosfera]. Plano geral, nível dos olhos, sem personagens presentes.

• Mantenha o quadro vazio de personagens. Inclua arquitetura/layout, superfícies, decoração, época, clima, hora, luz e estado da história quando relevante.
• Variantes do mesmo local preservam a identidade do local enquanto mudam escala ampla/próxima, dia/noite, clima, decoração, dano ou cobertura de detalhes.
• Sem arestas de referência por padrão. Se o local foi derivado de uma nota de script ou tomada, use --source-node-id para que a aresta de autoria seja aplicada.
• Próximo passo: após o último local roteirizado, recomende a próxima renderização de referência-para-clip. Mencione storyboard apenas se solicitado/necessário.

3. Edição / variação / giro de uma imagem existente

Gatilhos: alterar/editar/trocar/substituir/adicionar/remover/ajustar/e-se/variação em uma imagem existente.

• Identifique o nó fonte (geralmente o image_result mais recente, ou um que o usuário nomeou). Pegue source.id e source.metadata.aspect_ratio.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <proporção da fonte> --image-size <tamanho da fonte ou 2K> --subtype edit --source-node-id <id_da_fonte> --ref-source-id <id_da_fonte>.

• Prompt como uma transformação, não uma redesrição completa:

  <alteração concreta>. Preserve todo o resto.

  ✅ "Mude a chuva para neve caindo. Mantenha o detetive, guarda-roupa e enquadramento da câmera inalterados." ✅ "Renderize como uma folha de giro 3D completa do mesmo personagem. Preserve rosto, guarda-roupa e proporções." ❌ "Um detetive em um beco nevado à noite vestindo um casaco…" — superespecifica, a identidade varia.

• A CLI emite a aresta derivada de <id_da_fonte> com base em --ref-source-id.

• Cadeias de múltiplas etapas usam uma aresta/chamada por etapa; não achate A -> C.

4. Cena com personagens existentes

Gatilhos: colocar personagem em cenário / tomada de X e Y / ação de personagem em local.

• Identifique cada personagem envolvido — qualquer image_result dessa pessoa (até 16). Colete o id de cada um.
• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <ajuste à tomada> --image-size 2K --ref-source-id <id_personagem1> --ref-source-id <id_personagem2> ....
• Prompt: a descrição completa da cena. Nomeie cada personagem pelo seu papel para que o gerador vincule identidade ao papel. Refira-se a eles no prompt como @Image1, @Image2, … na ordem de --ref-source-id.
• Sem --subtype — uma cena não é nem personagem nem edição. A CLI emite uma aresta derivada por --ref-source-id.

5. Imagem estática independente

Gatilhos: uma imagem nova não relacionada ao conteúdo existente do canvas ("gere uma montanha ao entardecer", "um beco noir — apenas o cenário").

• Simples node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." com padrões sensatos (16:9, 2K a menos que o usuário peça outro). Sem subtipo, sem referências.

6. Mosaico de storyboard — um composto por clipe / nota de tomada

Gatilhos: storyboard, mosaico, grade, lista de tomadas, cobertura, folha de keyframe, planejamento de tomadas, pré-visualização de imagem. A saída é UM composto por clipe/nota de tomada de <=15s, não uma imagem por painel.

• Ferramenta/chamada: um generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Tomada <N>" --source-node-id <id_nota_tomada> por mosaico.
• Tamanho: padrão 2560x1440; a forma da grade é o layout das células, não a forma do canvas. Substitua apenas para retrato explícito/quadrado/vertical/proporção:
  • "storyboard 2x2" → 2560x1440 (padrão)
  • "storyboard quadrado 2x2" → 1920x1920
  • "storyboard retrato 2x2" → 1440x2560
  • "mosaico vertical 2x4" → 1440x2560
• Grade/referências: padrão 2×2. Passe referências relevantes de personagem/local (≤32). Aviso antes de 3×3+; recomende folhas menores.

Para a pré-verificação do canvas, lógica de iteração por nota de tomada, aviso de âncora ausente, modelo de prompt literal e cobertura de painel padrão quando não há fatia de script: veja references/storyboard-mosaic.md.

Campos de nó que a CLI define

• UM nó image_result POR mosaico.
• Defina data.subtype = "storyboard" passando --subtype storyboard.

7. Folha de referência de personagem (padrão para QUALQUER trabalho de personagem vinculado a vídeo — com ou sem referências de atores)

Use proativamente para qualquer personagem que aparecerá em vídeo posterior, independentemente de referências de atores.

Modo A — ≥3 referências de atores enviadas. Passe fotos como --ref-source-id; adicione --source-node-id <id_nota> se um script/tomada criou o design.

Modo B — 0-2 referências / do zero. Omita referências de atores; descreva idade/biótipo/guarda-roupa/características distintivas explicitamente. Adicione --source-node-id <id_nota> quando criado por uma nota.

Também dispara em pedidos explícitos: "projete uma folha de personagem / turnaround / folha de referência / design de personagem para [personagem]", "faça um design de personagem de 4 painéis", "gere uma folha de referência de produção para trabalho de vídeo posterior".

Saída: uma folha Frente-corpo inteiro / Perfil-corpo inteiro / Costas-corpo inteiro / Close-up busto, passada diretamente para o vídeo como --ref-source-id.

• Pré-verificação: identifique nós de referência enviados (subtype:"reference", idealmente ≥3 fotos). Confirme a contagem de referências em uma linha.
• node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 --subtype character --name "<nome_personagem>" --role "..." --ref-source-id <ref1> --ref-source-id <ref2> --ref-source-id <ref3> [--source-node-id <id_nota_script_ou_tomada>] — o tier Pro é o padrão para folhas de personagem porque o layout de painéis, a supressão de texto e a consistência de identidade são críticos. Não passe --aspect-ratio ou --image-size. Nunca dispare o Modo A com menos de 3 referências (o modelo se ajusta demais ao único ângulo que possui).
• Com 0-2 referências de atores, use o comando apenas com texto do Modo B de references/character-sheet.md: mesmo comando Pro, mas omita todo --ref-source-id de foto de ator; inclua --source-node-id apenas quando um script ou nota de tomada criou o design.
• Uma chamada/folha por personagem base ou variante material. Gere a base antes das variantes. Para variantes que preservam identidade, passe a folha base como referência e descreva apenas a mudança persistente de guarda-roupa/estado.
• Use a folha como --ref-source-id <id_folha> para tomadas posteriores; sem necessidade de corte normal.

Para o modelo de prompt literal de 4 painéis, cortes opcionais por ângulo, e pegadinhas (regra sem texto, prioridade de foto, contagens exatas de painéis): veja references/character-sheet.md.

Campos de nó que a CLI define

• UM nó image_result com data.subtype = "character".
• data.name, data.role, data.description das flags da CLI.
• Uma aresta derived por --ref-source-id (assim a folha tem vínculo de proveniência com cada foto de ator que triangulou).

Após a CLI retornar

Para JSON em estágio de rascunho, uma frase com o preço/status — veja o PROJECT_AGENT.md do projeto, seção "Draft gate". Para resultados finais, siga a regra de recomendação de próximo passo do manual do projeto.