Utopai-Research/pai-pro

Forma de la CLI

Nivel estándar:

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

Nivel Pro para mosaicos de storyboard y hojas de personaje vinculadas a video:

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 acepta solo --size; no --aspect-ratio / --image-size. Tamaños comunes: 1024x1024, 1280x720, 720x1280, 1920x1920, 2560x1440, 1440x2560, 3840x2160, 2160x3840.

--label por defecto es el prompt truncado (≤30 caracteres) si se omite; pasa uno explícito cuando tengas un mejor título.

Usa @Image1, @Image2, … en el orden de --ref-source-id. La CLI emite un borde derived por referencia.

Primero refleja URLs externas con mirror_url.js --url <URL>, luego pasa el node_id devuelto a través de --ref-source-id.

Si una nota creó la imagen, pasa --source-node-id <note_id>.

No intentes inventar imágenes con arte ASCII o incrustación de markdown — llama a la CLI.

Modo de imagen para primer uso

Para el flujo de preguntar una vez y los precios por modo, consulta el proyecto PROJECT_AGENT.md § "First-use generation choices".

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

Patrones

Elige el que se ajuste. Para la búsqueda de fuentes, sigue el proyecto PROJECT_AGENT.md § "Choosing context"; este skill solo posee la forma de la CLI y el prompt específico de imagen.

Verificación previa del personaje. Primero pregunta: ¿aparecerá este personaje en un video posterior (video, clip, promo, 宣传片, 短片, 连续剧, film, scene, 拍片, shot, short film)?

1. Lee workflow.json para buscar referencias subidas (subtype:"reference", metadata.source:"user_upload", no archivadas).
2. Vinculado a video -> Patrón 7, no Patrón 1. Usa ≥3 referencias de actor cuando estén disponibles; con 0-2 referencias, genera una hoja de 4 paneles solo con texto.
3. Anuncia una línea antes de ejecutar; permite redirigir al Patrón 1.
4. Arte estático/póster/retrato de una sola vez -> Patrón 1.

Esta verificación previa no es negociable. El retrato frontal único del Patrón 1 le da al modelo de video un anclaje demasiado estrecho; la identidad se desvía de toma en toma. Saltar directamente al Patrón 1 para trabajo de video es el error más común.

Valores predeterminados de anclaje para historia/guion. Cuando script-compose o story-to-video-workflow enruta un desglose aquí:

• Una hoja base de 4 paneles por personaje significativo.
• Hojas adicionales para variantes del personaje significativo: edad, vestuario/uniforme/disfraz, lesión/sucio/mojado/sangriento, transformación o apariencias significativas para la continuidad.
• Anclajes de ubicación detallados para escenarios que afectan las tomas.
• Variantes de la misma ubicación para cambios de encuadre/escala/hora/clima/iluminación/decoración/estado de la historia/cobertura de detalles cercanos.
• Prefiere referencia a clip después de los anclajes. Storyboard solo si se solicita, es difícil de controlar o se necesita para diagnóstico.
• No elimines variantes significativas por presupuesto/velocidad; la persona que llama debe ajustar primero la resolución/duración del video.

1. Retrato de personaje (solo imágenes fijas estáticas de una sola vez)

Disparadores: retrato/retrato heroico/villano/protagonista de personaje solo para imágenes fijas estáticas de una sola vez. Vinculado a video -> Patrón 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 "..." — sin referencias. Un personaje es un ancla de identidad, no un derivado.
• Plantilla de prompt:

  [estilo] retrato de personaje de [NOMBRE], [rol]. [edad, complexión, vestuario, características distintivas]. Plano medio frontal, a la altura de los ojos, mirando directamente a la cámara, expresión neutral. Fondo neutro simple, iluminación suave y uniforme. Sin sombras dramáticas, sin iluminación estilizada, sin perfil, sin múltiples vistas.

• Hereda el estilo del proyecto o usa realista por defecto. Nombra a los personajes sin nombre.
• Sin bordes — los personajes son raíces, por lo tanto sin --ref-source-id.

2. Imagen fija de establecimiento de ubicación

Disparadores: establecer/diseñar/visualizar una ubicación, o aprobar una oferta de ubicación de script-compose.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Calzada" --description "..." [--source-node-id <id_nota_guion_o_toma>] — sin referencias. Una ubicación es un ancla de escenario, no un derivado.
• Plantilla de prompt:

  [estilo] imagen fija de establecimiento de [NOMBRE_UBICACIÓN]. [resumen visual — arquitectura, iluminación, atmósfera]. Plano general, a la altura de los ojos, sin personajes presentes.

• Mantén el encuadre vacío de personajes. Incluye arquitectura/distribución, superficies, decoración, época, clima, hora, luz y estado de la historia cuando sea relevante.
• Las variantes de la misma ubicación preservan la identidad del lugar mientras cambian la escala general/cerrada, día/noche, clima, decoración, daño o cobertura de detalles.
• Sin bordes de referencia por defecto. Si la ubicación se derivó de una nota de guion o toma, usa --source-node-id para que el borde de autoría se coloque.
• Continuación: después de la última ubicación guionizada, recomienda el siguiente renderizado de referencia a clip. Menciona storyboard solo si se solicita/necesita.

3. Edición / variación / cambio de imagen existente

Disparadores: cambiar/editar/intercambiar/reemplazar/añadir/eliminar/ajustar/qué-pasaría-si/variación en una imagen existente.

• Identifica el nodo fuente (generalmente el image_result más reciente, o uno nombrado por el usuario). Obtén source.id y source.metadata.aspect_ratio.

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <relación fuente> --image-size <tamaño fuente o 2K> --subtype edit --source-node-id <source.id> --ref-source-id <source.id>.

• Prompt como una transformación, no una descripción completa:

  <cambio concreto>. Preserva todo lo demás.

  ✅ "Cambia la lluvia por nieve que cae. Mantén al detective, el vestuario y el encuadre de la cámara sin cambios." ✅ "Renderiza como una hoja de variación 3D completa del mismo personaje. Preserva el rostro, el vestuario y las proporciones." ❌ "Un detective en un callejón nevado por la noche con un abrigo…" — demasiado específico, la identidad se desvía.

• La CLI emite el borde derivado desde <source.id> basado en --ref-source-id.

• Las cadenas de múltiples pasos usan un borde/llamada por paso; no aplastes A -> C.

4. Escena con personajes existentes

Disparadores: poner personaje en escenario / toma de X e Y / acción de personaje en ubicación.

• Identifica cada personaje involucrado — cualquier image_result de esa persona (hasta 16). Recolecta el id de cada uno.
• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <ajustar a la toma> --image-size 2K --ref-source-id <char1.id> --ref-source-id <char2.id> ....
• Prompt: la descripción completa de la escena. Nombra a cada personaje por su rol para que el generador vincule la identidad al rol. Refiérete a ellos en el prompt como @Image1, @Image2, … en el orden de --ref-source-id.
• Sin --subtype — una escena no es ni un personaje ni una edición. La CLI emite un borde derivado por cada --ref-source-id.

5. Imagen fija independiente

Disparadores: una imagen nueva no relacionada con el contenido existente del lienzo ("genera una montaña al atardecer", "un callejón noir — solo el escenario").

• node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." simple con valores predeterminados sensatos (16:9, 2K a menos que el usuario indique lo contrario). Sin subtipo, sin referencias.

6. Mosaico de storyboard — un compuesto por clip / nota de toma

Disparadores: storyboard, mosaico, cuadrícula, lista de tomas, cobertura, hoja de fotogramas clave, planificación de tomas, previsualización de imágenes. La salida es UN compuesto por nota de clip/toma ≤15s, no una imagen por panel.

• Herramienta/llamada: un generate_image_pro.js --size 2560x1440 --subtype storyboard --label "Storyboard — Toma <N>" --source-node-id <id_nota_toma> por mosaico.
• Tamaño: por defecto 2560x1440; la forma de la cuadrícula es la disposición de celdas, no la forma del lienzo. Sobrescribe solo para relación explícita de retrato/cuadrado/vertical/ratio:
  • "storyboard 2x2" → 2560x1440 (por defecto)
  • "storyboard cuadrado 2x2" → 1920x1920
  • "storyboard retrato 2x2" → 1440x2560
  • "mosaico vertical 2x4" → 1440x2560
• Cuadrícula/referencias: por defecto 2×2. Pasa referencias relevantes de personajes/ubicaciones (≤32). Advierte antes de 3×3+; recomienda hojas más pequeñas.

Para la verificación previa del lienzo, la lógica de iteración por nota de toma, el aviso de anclaje faltante, la plantilla de prompt textual y la cobertura de panel predeterminada cuando no hay un fragmento de guion: consulta references/storyboard-mosaic.md.

Campos de nodo que establece la CLI

• UN nodo image_result POR mosaico.
• Establece data.subtype = "storyboard" pasando --subtype storyboard.

7. Hoja de referencia de personaje (predeterminada para CUALQUIER trabajo de personaje vinculado a video — con o sin referencias de actor)

Úsala de manera proactiva para cualquier personaje que aparecerá en un video posterior, independientemente de las referencias de actor.

Modo A — ≥3 referencias de actor subidas. Pasa fotos como --ref-source-id; añade --source-node-id <id_nota> si una nota de guion/toma creó el diseño.

Modo B — 0-2 referencias / desde cero. Omite las referencias de actor; describe edad/complexión/vestuario/características distintivas explícitamente. Añade --source-node-id <id_nota> cuando una nota haya creado el diseño.

También se dispara con solicitudes explícitas: "diseña una hoja de personaje / variación / hoja de referencia / diseño de personaje para [personaje]", "haz un diseño de personaje de 4 paneles", "genera una hoja de referencia de producción para trabajo de video posterior".

Salida: una hoja Frente-cuerpo completo / Perfil-cuerpo completo / Espalda-cuerpo completo / Primer plano-busto, pasada directamente al video como --ref-source-id.

• Verificación previa: identifica los nodos de referencia subidos (subtype:"reference", idealmente ≥3 fotos). Confirma el número de referencias en una línea.
• node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 --subtype character --name "<nombre_personaje>" --role "..." --ref-source-id <ref1> --ref-source-id <ref2> --ref-source-id <ref3> [--source-node-id <id_nota_guion_o_toma>] — el nivel pro es el predeterminado para hojas de personaje porque la disposición de paneles, la supresión de texto y la consistencia de identidad son fundamentales. No pases --aspect-ratio ni --image-size. Nunca actives el Modo A con menos de 3 referencias (el modelo se sobreajusta al único ángulo que tiene).
• Con 0-2 referencias de actor, usa el comando solo de texto del Modo B de references/character-sheet.md: mismo comando pro, pero omite cada --ref-source-id de foto de actor; incluye --source-node-id solo cuando una nota de guion o toma haya creado el diseño.
• Una llamada/hoja por personaje base o variante significativa. Genera la base antes que las variantes. Para variantes que preservan la identidad, pasa la hoja base como referencia y describe solo el cambio persistente de vestuario/estado.
• Usa la hoja como --ref-source-id <id_hoja> para tomas posteriores; no es necesario recortar normalmente.

Para la plantilla de prompt textual de 4 paneles, recortes opcionales por ángulo y advertencias (regla de sin texto, prioridad de foto, conteo exacto de paneles): consulta references/character-sheet.md.

Campos de nodo que establece la CLI

• UN nodo image_result con data.subtype = "character".
• data.name, data.role, data.description de los indicadores de la CLI.
• Un borde derived por cada --ref-source-id (para que la hoja esté vinculada por procedencia a cada foto de actor de la que se trianguló).

Después de que la CLI devuelve

Para JSON en etapa de borrador, una oración con el precio/estado — consulta el proyecto PROJECT_AGENT.md § "Draft gate". Para resultados finales, sigue la regla de recomendación del siguiente paso del manual del proyecto.