grahama1970/imagegen

Habilidad de Generación de Imágenes

Genera o edita imágenes para el proyecto actual (por ejemplo, activos para sitios web, activos para juegos, maquetas UI, maquetas de productos, wireframes, diseño de logotipos, imágenes fotorrealistas o infografías).

Modos y reglas principales

Esta habilidad tiene exactamente dos modos principales:

• Modo de herramienta integrada predeterminado (preferido): herramienta integrada image_gen para generación normal de imágenes, edición y solicitudes simples de imágenes transparentes. No requiere OPENAI_API_KEY.
• Modo CLI de respaldo: CLI scripts/image_gen.py. Úsalo cuando el usuario solicite explícitamente la ruta CLI/API/modelo, o después de que el usuario confirme explícitamente un respaldo de transparencia nativa del modelo con gpt-image-1.5. Requiere OPENAI_API_KEY.

Dentro del respaldo CLI, la CLI expone tres subcomandos:

• generate
• edit
• generate-batch

Reglas:

• Usa la herramienta integrada image_gen por defecto para solicitudes normales de generación y edición de imágenes.
• No cambies al respaldo CLI para control ordinario de calidad, tamaño o ruta de archivo.
• Si el usuario solicita explícitamente una imagen/fondo transparente, quédate en image_gen integrada primero: solicita un fondo de clave cromática plano y removible, luego elimínalo localmente con el ayudante instalado en $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py.
• Nunca cambies silenciosamente de image_gen integrada o CLI gpt-image-2 a CLI gpt-image-1.5. Trata esto como una degradación de modelo/ruta y pregunta al usuario antes de hacerlo, a menos que el usuario ya haya solicitado explícitamente gpt-image-1.5, scripts/image_gen.py o el respaldo CLI.
• Si una solicitud transparente parece demasiado compleja para una limpieza de clave cromática limpia, solicita transparencia verdadera/nativa, o la eliminación local falla en la validación, explica que la transparencia verdadera requiere CLI gpt-image-1.5 --background transparent --output-format png porque gpt-image-2 no soporta background=transparent, luego pregunta si se debe proceder. Ejecuta el respaldo CLI solo después de que el usuario confirme.
• La palabra batch por sí sola no significa respaldo CLI. Si el usuario solicita muchos activos o dice generar activos por lotes sin solicitar explícitamente controles CLI/API/modelo, quédate en la ruta integrada y emite una llamada integrada por activo o variante solicitada.
• Si la herramienta integrada falla o no está disponible, informa al usuario que existe el respaldo CLI y que requiere OPENAI_API_KEY. Procede solo si el usuario solicita explícitamente ese respaldo.
• Si el usuario solicita explícitamente el modo CLI, usa el flujo de trabajo scripts/image_gen.py incluido. No crees ejecutores SDK únicos.
• Nunca modifiques scripts/image_gen.py. Si falta algo, pregunta al usuario antes de hacer cualquier otra cosa.

Política de ruta de guardado integrada:

• En el modo de herramienta integrada, Codex guarda las imágenes generadas bajo $CODEX_HOME/* por defecto.
• No describas ni confíes en el temp del SO como destino integrado predeterminado.
• No describas ni confíes en un argumento de ruta de destino (si lo hay) en la herramienta integrada image_gen. Si se necesita una ubicación específica, genera primero y luego mueve o copia la salida seleccionada desde $CODEX_HOME/generated_images/....
• Precedencia de ruta de guardado en modo integrado:
  1. Si el usuario nombra un destino, mueve o copia la salida seleccionada allí.
  2. Si la imagen está destinada al proyecto actual, mueve o copia la imagen final seleccionada al espacio de trabajo antes de terminar.
  3. Si la imagen es solo para vista previa o lluvia de ideas, renderízala en línea; el archivo subyacente puede permanecer en la ruta predeterminada $CODEX_HOME/*.
• Nunca dejes un activo referenciado en el proyecto solo en la ruta predeterminada $CODEX_HOME/*.
• No sobrescribas un activo existente a menos que el usuario haya solicitado explícitamente el reemplazo; de lo contrario, crea un nombre de archivo con versión hermano, como hero-v2.png o item-icon-edited.png.

La guía de prompts compartida para ambos modos se encuentra en references/prompting.md y references/sample-prompts.md.

Documentos/recursos solo de respaldo para modo CLI:

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.py

Ayudante de posprocesamiento local:

• $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py: elimina un fondo de clave cromática plano de una imagen generada y escribe un PNG/WebP con canal alfa. Prefiere muestreo automático de clave, mate suave y despill para bordes suavizados.

Cuándo usar

• Generar una imagen nueva (arte conceptual, foto de producto, portada, héroe de sitio web)
• Generar una imagen nueva usando una o más imágenes de referencia para estilo, composición o ambiente
• Editar una imagen existente (inpainting, transformaciones de iluminación o clima, reemplazo de fondo, eliminación de objetos, composición, fondo transparente)
• Producir muchos activos o variantes para una tarea

Cuándo no usar

• Extender o igualar un conjunto de iconos/vectores SVG existente, sistema de logotipos o biblioteca de ilustraciones dentro del repositorio
• Crear formas simples, diagramas, wireframes o iconos que se producen mejor directamente en SVG, HTML/CSS o canvas
• Hacer una edición pequeña de activo local del proyecto cuando el archivo fuente ya existe en un formato nativo editable
• Cualquier tarea donde el usuario quiera claramente una salida nativa de código determinista en lugar de un mapa de bits generado

Árbol de decisión

Piensa en dos preguntas separadas:

1. Intención: ¿es una imagen nueva o una edición de una imagen existente?
2. Estrategia de ejecución: ¿es un activo o muchos activos/variantes?

Intención:

• Si el usuario quiere modificar una imagen existente preservando partes de ella, trata la solicitud como edición.
• Si el usuario proporciona imágenes solo como referencias para estilo, composición, ambiente o guía de asunto, trata la solicitud como generación.
• Si el usuario no proporciona imágenes, trata la solicitud como generación.

Semántica de edición integrada:

• El modo de edición integrado es para imágenes ya visibles en el contexto de la conversación, como imágenes adjuntas o imágenes generadas anteriormente en el hilo.
• Si el usuario quiere editar un archivo de imagen local con la herramienta integrada, cárgalo primero con la herramienta integrada view_image para que la imagen sea visible en el contexto de la conversación, luego procede con el flujo de edición integrado.
• No prometas edición de ruta de archivo arbitraria a través de la herramienta integrada.
• Si un archivo local aún necesita control directo de ruta de archivo, máscaras u otros parámetros explícitos solo de CLI, usa el respaldo CLI explícito solo cuando el usuario lo solicite.
• Para ediciones, preserva invariantes de manera agresiva y guarda de forma no destructiva por defecto.

Estrategia de ejecución:

• En la ruta integrada predeterminada, produce muchos activos o variantes emitiendo una llamada image_gen por activo o variante solicitada.
• En la ruta de respaldo CLI, usa el subcomando CLI generate-batch solo cuando el usuario haya elegido explícitamente el modo CLI y necesite muchos prompts/activos.
• Para muchos activos distintos, no uses n como sustituto de prompts separados. n es para variantes de un prompt; los activos distintos necesitan llamadas integradas distintas o trabajos CLI generate-batch distintos.

Asume que el usuario quiere una imagen nueva a menos que pida claramente cambiar una existente.

Flujo de trabajo

1. Decide el modo principal: integrado por defecto, incluyendo solicitudes simples de salida transparente; respaldo CLI solo si se solicita explícitamente o después de que el usuario confirme explícitamente un respaldo de salida transparente.
2. Decide la intención: generate o edit.
3. Decide si la salida es solo de vista previa o está destinada a ser consumida por el proyecto actual.
4. Decide la estrategia de ejecución: activo único vs llamadas integradas repetidas vs CLI generate-batch.
5. Recopila las entradas por adelantado: prompt(s), texto exacto (al pie de la letra), restricciones/lista de evitación, y cualquier imagen de entrada.
6. Para cada imagen de entrada, etiqueta su rol explícitamente:
   • imagen de referencia
   • destino de edición
   • entrada de inserción/estilo/composición de soporte
7. Si el destino de edición está solo en el sistema de archivos local y te quedas en la ruta integrada, inspecciónalo con view_image primero para que la imagen esté disponible en el contexto de la conversación.
8. Si el usuario solicitó una foto, ilustración, sprite, imagen de producto, banner u otro activo explícitamente de tipo rasterizado, usa image_gen en lugar de sustituir marcadores de posición SVG/HTML/CSS. Si la solicitud es para un icono, logotipo o gráfico UI que debe coincidir con activos SVG/vectoriales/código nativos existentes del repositorio, prefiere editar esos directamente.
9. Aumenta el prompt según la especificidad:
   • Si el prompt del usuario ya es específico y detallado, normalízalo en una especificación clara sin agregar requisitos creativos.
   • Si el prompt del usuario es genérico, agrega aumento de buen gusto solo cuando mejore materialmente la calidad de la salida.
10. Usa la herramienta integrada image_gen por defecto.
11. Para solicitudes de salida transparente, sigue la guía de imágenes transparentes a continuación: genera con image_gen integrada en un fondo de clave cromática plano, copia la salida seleccionada al espacio de trabajo o tmp/imagegen/, ejecuta el ayudante instalado $CODEX_HOME/skills/.system/imagegen/scripts/remove_chroma_key.py, y valida el resultado alfa antes de usarlo. Si esta ruta parece inadecuada o falla, pregunta antes de cambiar a CLI gpt-image-1.5.
12. Inspecciona las salidas y valida: asunto, estilo, composición, precisión del texto e invariantes/ítems de evitación.
13. Itera con un solo cambio dirigido, luego vuelve a verificar.
14. Para trabajo solo de vista previa, renderiza la imagen en línea; el archivo subyacente puede permanecer en la ruta predeterminada $CODEX_HOME/generated_images/....
15. Para trabajo vinculado al proyecto, mueve o copia el artefacto seleccionado al espacio de trabajo y actualiza cualquier código o referencias consumidoras. Nunca dejes un activo referenciado en el proyecto solo en la ruta predeterminada $CODEX_HOME/generated_images/....
16. Para lotes o solicitudes de múltiples activos, persiste cada producto final solicitado en el espacio de trabajo a menos que el usuario haya solicitado explícitamente mantener las salidas solo como vista previa. Las variantes descartadas no necesitan mantenerse a menos que se soliciten.
17. Si el usuario elige o confirma explícitamente el respaldo CLI, entonces usa la documentación solo de respaldo para modelo, calidad, tamaño, input_fidelity, máscaras, formato de salida, rutas de salida y configuración de red.
18. Siempre informa la(s) ruta(s) final(es) guardada(s) para cualquier activo vinculado al espacio de trabajo, más el prompt o conjunto de prompts final y si se usó la herramienta integrada o el modo CLI de respaldo.

Solicitudes de imágenes transparentes

Las solicitudes de imágenes transparentes aún usan image_gen integrada primero. Debido a que la herramienta integrada no expone un control de fondo transparente verdadero, crea una imagen fuente de clave cromática removible y luego convierte el color clave a alfa localmente.

Secuencia predeterminada:

1. Usa image_gen integrada para generar el asunto solicitado sobre un fondo de clave cromática sólido perfectamente plano.
2. Elige un color clave que sea poco probable que aparezca en el asunto: predeterminado #00ff00, usa #ff00ff para asuntos verdes, y evita #0000ff para asuntos azules.
3. Después de la generación, mueve o copia la imagen fuente seleccionada desde $CODEX_HOME/generated_images/... al espacio de trabajo o tmp/imagegen/.
4. Ejecuta la ruta del ayudante instalado, no una ruta de script relativa al proyecto:

   python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
     --input <source> \
     --out <final.png> \
     --auto-key border \
     --soft-matte \
     --transparent-threshold 12 \
     --opaque-threshold 220 \
     --despill
   

5. Valida que la salida tenga un canal alfa, esquinas transparentes, cobertura plausible del asunto y sin franja de color clave obvia. Si queda una franja delgada, reintenta una vez con --edge-contract 1; usa --edge-feather 0.25 solo cuando el borde esté visiblemente escalonado y el asunto no sea brillante o reflectante.
6. Guarda el PNG/WebP alfa final en el proyecto si el activo está vinculado al proyecto. Nunca dejes un activo transparente referenciado en el proyecto solo bajo $CODEX_HOME/*.

Formula las solicitudes transparentes así:

Crea el asunto solicitado sobre un fondo de clave cromática sólido perfectamente plano #00ff00 para eliminación de fondo.
El fondo debe ser de un color uniforme sin sombras, gradientes, textura, reflejos, plano de suelo o variación de iluminación.
Mantén el asunto completamente separado del fondo con bordes nítidos y relleno generoso.
No uses #00ff00 en ninguna parte del asunto.
Sin sombra proyectada, sin sombra de contacto, sin reflejo, sin marca de agua y sin texto a menos que se solicite explícitamente.

No uses automáticamente CLI gpt-image-1.5 --background transparent --output-format png en lugar de la clave cromática. Pregunta primero al usuario cuando solicite transparencia verdadera/nativa, cuando la eliminación local falle en la validación, o cuando la imagen solicitada sea compleja: cabello, pelaje, plumas, humo, vidrio, líquidos, materiales translúcidos, objetos reflectantes, sombras suaves, conexión a tierra realista del producto, o colores del asunto que entren en conflicto con todos los colores clave prácticos.

Usa una confirmación concisa como:

Esto probablemente necesita transparencia nativa verdadera. La ruta integrada predeterminada usa un fondo de clave cromática más eliminación local, pero la transparencia verdadera requiere el respaldo CLI con gpt-image-1.5 porque gpt-image-2 no soporta background=transparent. También requiere OPENAI_API_KEY. ¿Debo proceder con ese respaldo CLI?

Aumento de prompt

Reformatea los prompts del usuario en una especificación estructurada y orientada a la producción. Haz que el objetivo del usuario sea más claro y procesable, pero no agregues detalles a ciegas.

Trata esto como una guía de modelado de prompts, no un esquema cerrado. Usa solo las líneas que ayuden y agrega una línea etiquetada adicional corta cuando mejore materialmente la claridad.

Política de especificidad

Usa la especificidad del prompt del usuario para decidir cuánto aumento es apropiado:

• Si el prompt ya es específico y detallado, preserva esa especificidad y solo normalízalo/estructúralo.
• Si el prompt es genérico, puedes agregar aumento de buen gusto cuando mejore materialmente el resultado.

Aumentos permitidos:

• sugerencias de composición o encuadre
• sugerencias de nivel de pulido o uso previsto
• guía práctica de diseño
• concreción razonable de escena que respalde la solicitud declarada

Aumentos no permitidos:

• personajes u objetos adicionales que no estén implícitos en la solicitud
• nombres de marca, lemas, paletas o ritmos narrativos que no estén implícitos
• colocación arbitraria en un lado específico a menos que el diseño circundante lo respalde

Uso-ca

…

[truncado para traducción]