shaharsha/image-generation

Generación de Imágenes

Dos familias de modelos, tres trabajos.

Modelos cubiertos

ID del modelo	Familia	Úsalo para	Costo (1024×1536, medido 2026-10-02)
gpt-image-2.5-sunburst	OpenAI (Images 2.5, 2026-09-08)	Por defecto. Cualquier cosa que pueda enviarse. #1 en todos los rankings principales (generación, edición, renderizado de texto, retratos)	max ≈ $0.165, ~90 s · high ≈ $0.041, ~35 s
gpt-image-2.5-flare	OpenAI (Images 2.5)	Borradores rápidos — explorar direcciones, probar un prompt. Mismos prompts que Sunburst, ~2× más rápido	medium ≈ $0.01, ~15 s
gemini-3-pro-image	Google (Nano Banana Pro)	Primer plano de piel/cabello natural cuando los votos y revisores discrepan; hasta 14 referencias	$0.134 (1K/2K) · $0.24 (4K)
gemini-3.1-flash-image	Google (Nano Banana 2)	Relaciones de aspecto extremas (1:4…8:1), grounding por búsqueda de imágenes	$0.067 (1K)
gemini-3.1-flash-lite-image	Google (Nano Banana 2 Lite)	Exploración Gemini más económica; solo 1K, devuelve JPEG	$0.034

gpt-image-2 sigue funcionando (no está obsoleto) pero está un paso por debajo de ambos modelos 2.5. Los IDs *-preview de Gemini y todos los modelos Imagen están cerrados — los scripts los rechazan.

Los tres trabajos de esta habilidad

1. Elegir el modelo y la calidad para el activo. Consulta reference/model-selection.md.
2. Escribir el prompt siguiendo las reglas del modelo. Los dos proveedores quieren cosas opuestas:
   • OpenAI GPT Image 2.5 quiere secciones etiquetadas (escena / sujeto / detalles / restricciones), texto exacto entre comillas y acepta exclusiones en línea ("sin texto extra, sin marcas de agua"). Lee reference/openai-gpt-image.md.
   • Gemini quiere párrafos narrativos, las frases negativas contraatacan (reescribe "sin personas" como "calle vacía"), la relación de aspecto va en imageConfig. Lee reference/gemini-image.md.
3. Ejecutar la API mediante los scripts incluidos. Consulta scripts/README.md.

Calidad en 2.5 — la trampa

La escalera de calidad de 2.5 se redefinió. Al mismo tamaño, high de 2.5 compra aproximadamente los tokens de salida de medium de gpt-image-2; max de 2.5 compra lo que hacía high de gpt-image-2 (medido: Sunburst 1024×1536 high = 1,372 tokens de salida, max = 5,488). Copiar "quality=high" de viejos hábitos envía silenciosamente una imagen de detalle medio.

Promociona borradores con una edición, no con un regenerado. Cada nueva generación compone una imagen diferente, por lo que volver a ejecutar el prompt de un borrador aprobado en max te da una imagen distinta. En su lugar, pasa el borrador elegido como referencia a una edición Sunburst max que solo cambie la calidad de renderizado y conserve todo lo demás. Verificado 2026-10-02: un póster Flare medium promocionado de esta manera mantuvo su composición, personas, poses, colores y texto en hebreo, y ganó textura y detalle ($0.18, 85 s).

Etapa	Modelo + calidad	Por qué
Explorar direcciones, probar un prompt	Flare medium (--draft)	~1¢ y ~15 s, así que 6 direcciones cuestan menos que una final
Promocionar el borrador elegido	Edición Sunburst max con --ref <borrador> y el prompt de promoción en reference/openai-gpt-image.md	Mantiene el aspecto que el usuario eligió, añade detalle completo
Una final directa desde un prompt bloqueado	Sunburst max (el valor predeterminado del script)	Detalle completo; ~90 s, ~$0.17
Sunburst cuando el tiempo importa más que el detalle fino	Sunburst high	Un cuarto de los tokens, ~35 s

Nunca uses auto — asigna presupuestos diferentes para llamadas idénticas.

Selección de modelo por defecto — la regla de los 30 segundos

¿Explorando direcciones / "algunas opciones rápidas" / probando si un prompt funciona?
  SÍ → Flare medium (--draft). Promociona la elección del usuario con una edición Sunburst max (--ref <borrador>).
  NO  ↓

¿Primer plano fotorrealista de rostro humano donde la textura de la piel es el punto?
  SÍ → Sunburst max primero (lidera los votos de retratos); si la piel se ve sobrenitida al hacer zoom,
        compara con gemini-3-pro-image 4K y deja que el humano elija.
  NO  ↓

¿Banner ultraancho/alto más allá de 3:1 (1:4, 4:1, 1:8, 8:1)?
  SÍ → gemini-3.1-flash-image (GPT Image tiene un límite de 3:1).
  NO  ↓

Todo lo demás → Sunburst con calidad=max.
  └── ¿PNG transparente? Nativo: --background transparent (png/webp). No necesita rembg.

Árbol de decisión completo por tipo de activo: reference/model-selection.md.

Flujo de trabajo por solicitud

1. Confirmar el alcance. Tipo de activo, contexto de marca, dirección de color/estilo, relación de aspecto objetivo + tamaño, dónde guardar. Si la solicitud ya lo dice, continuar.
2. Elegir modelo y calidad. Usa la regla anterior; explica la elección en una frase.
3. Leer la referencia específica del modelo — reference/openai-gpt-image.md o reference/gemini-image.md. No escribas de memoria: los dos proveedores quieren estructuras de prompt opuestas, y la guía de 2.5 cambió varios hábitos de gpt-image-2.
4. ¿Fondo transparente? En GPT Image 2.5 es nativo. Lee reference/transparent-backgrounds.md solo para salidas de Gemini o para recortar una imagen existente.
5. Abrir la plantilla correspondiente en templates/ y llenar los marcadores de posición.
6. ¿Texto en hebreo o RTL en la imagen? Lee reference/hebrew-rtl.md primero.
7. Mostrar el prompt al usuario antes de llamar a la API a menos que diga "solo hazlo". Una revisión del prompt evita las regeneraciones más costosas.
8. Ejecutar el script. Guardar en ./generated-images/<nombre-descriptivo>.png en el directorio de trabajo actual a menos que se indique lo contrario. El script de OpenAI imprime latencia, tokens de salida y costo por llamada — mantén un total acumulado.
9. Leer la imagen guardada con la herramienta Read — Claude es multimodal y realmente verá los píxeles. Critica según el resumen: composición, texto escrito exactamente como se citó y que aparece una vez, colores, defectos (letras deformadas, dedos extra, geometría rota, grano en áreas lisas). Detecta problemas antes de que el usuario tenga que hacerlo.
10. Mostrar al usuario. open <ruta>, resume lo que ves (bueno y malo), y propone enviar / iterar con un cambio específico / reescribir.

Plantillas por tipo de activo

Activo	Plantilla
Logotipo de marca / marca / marca denominativa	templates/logo.md
Conjunto de iconos (estilo consistente entre iconos)	templates/icon-set.md
Pantalla de UI de app móvil	templates/ui-mobile.md
Panel de control web / UI SaaS	templates/ui-dashboard.md
Imagen hero de marketing / banner	templates/hero-image.md
Fotografía de producto / hero shot	templates/product-shot.md

Para ejemplos trabajados textuales, consulta examples.md.

Personajes recurrentes y paneles de historietas

Para cómics, storyboards y episodios animados donde las mismas personas aparecen en muchas imágenes:

• Personajes a partir de fotos. Nunca pases fotos completas como referencias: el endpoint de edición reestiliza la foto (copia pose, ropa y fondo, añade texto de título) en lugar de dibujar a la persona. El pipeline que funciona:

  1. Recortar los rostros primero: python3 <directorio-de-esta-habilidad>/scripts/crop_faces.py photos/ faces/ --sheet faces/_sheet.jpg.
  2. Crear un rostro anime a partir de los recortes.
  3. Editar ese rostro en una tarjeta de disfraz de medio cuerpo, indicando el tipo de cuerpo.
  4. Obtener aprobación humana, luego promocionar.

  Prompts y el bucle de revisión: reference/characters-from-photos.md.

• Escenas con 2+ personajes.

  • Borrador con Sunburst high, no Flare: Flare dibujó solo la Imagen 1, al aire libre, con subtítulos.
  • Vincular cada nombre a su tarjeta en la primera mención: "Dana (la mujer de la Imagen 1)".
  • Prohibir subtítulos en cualquier idioma.
  • Las pantallas de teléfono y tableta se renderizan desde atrás: genera el contenido de la pantalla como su propia imagen y compónlo.

  Receta: reference/multi-character-scenes.md.

• Facturación por lotes. credit_balance_exhausted significa que la cuenta de OpenAI se quedó sin crédito, no que sea una solicitud incorrecta. Detente, enumera qué tomas terminaron y, después de la recarga, vuelve a ejecutar solo las que faltan.

Claves de API y dependencias

Las claves de API provienen de variables de entorno, configuradas desde tu propio almacén de secretos en el shell que ejecuta el script (cada shell nuevo las necesita de nuevo):

• OPENAI_IMAGE_API_KEY para scripts/openai-image.sh
• GEMINI_IMAGE_API_KEY (o GEMINI_API_KEY) para scripts/gemini-image.sh; la misma clave de Google AI Studio también funciona para generar-clips-de-video

Estas claves tienen alcance de generación de imágenes. No las reutilices para chat o embeddings, y nunca las imprimas — cárgalas en una variable, no hagas echo.

Herramientas locales (solo para recortar salidas de Gemini o imágenes existentes): rembg (pip install "rembg[cli]" onnxruntime), opcionalmente ImageMagick.

Convención de salida

• Ubicación de guardado predeterminada: ./generated-images/<nombre-descriptivo>.png en el directorio de trabajo actual.
• Nombre de archivo: kebab-case descriptivo (logo-agentleh-monocromatico-v1.png); los borradores llevan -borrador-N (logo-agentleh-borrador-3.png).
• Versionado: añadir -v1, -v2, … al iterar. Nunca sobrescribir una generación anterior sin preguntar.
• Salidas transparentes: añadir -transparente después de la versión.
• open <ruta> en macOS para mostrar al usuario justo después de la generación.

Patrones de iteración — bucle autónomo "iterar hasta que sea perfecto"

El trabajo del agente es llevar la imagen a "suficientemente buena para enviar" antes de preguntar al usuario:

1. Generar (llamada al script)
2. Leer el archivo guardado con la herramienta Read — Claude VE los píxeles
3. Autocrítica según el resumen:
   - ¿La composición funcionó? (ubicación, encuadre, equilibrio, jerarquía, espacio negativo)
   - ¿El texto escrito exactamente como se citó, cada cadena aparece una vez, legible?
   - ¿Colores correctos? (coincidencia hex, adherencia a la paleta)
   - ¿Defectos? (letras deformadas, dedos extra, geometría rota, grano en cielos/fondos)
   - ¿El resumen realmente se cumplió?
4. Decidir:
   - ENVIAR    → cumple el resumen; mostrarlo al usuario
   - EDITAR    → una corrección localizada; editar con --ref <anterior> y un prompt que diga
               "cambia solo X" y REAFIRME cada corrección anterior y detalle preservado
   - REESCRIBIR → problema fundamental de prompt; reescribir desde cero, no ajustar
5. Detenerse cuando: se hayan usado 5 iteraciones, o se hayan gastado $3 en este activo (sumar las líneas de costo del script),
   o sea enviable.

El usuario es el juez final — pero Claude es el primer juez. No muestres un resultado defectuoso y preguntes "¿está bien?" Muéstralo después de que hayas verificado que cumple el resumen, o con tu crítica adjunta ("el espaciado de la marca denominativa está mal; lo arreglo en la siguiente").

Mecánica por modelo

• Ediciones GPT Image 2.5 pasan por /v1/images/edits mediante scripts/openai-image.sh --ref <imagen> (hasta 16 referencias). Sin una máscara, todo el lienzo se regenera en cada turno, por lo que la deriva se acumula — reafirma cada cambio anterior y cada detalle preservado en cada turno, no solo la nueva solicitud. Si una región debe permanecer idéntica en píxeles, compón la edición aprobada en la imagen original en lugar de esperar que el prompt la mantenga.
• Edición multiturno Gemini: scripts/gemini-image.sh --ref <salida-anterior> --prompt "cambia X, mantén Y", terminando siempre con "Mantén todo lo demás en la imagen exactamente igual — composición, iluminación, colores, todos los demás elementos."
• Disciplina de deriva. Después de 3 iteraciones fallidas en la misma imagen, cambia de estrategia: reescribe el prompt base, o cambia de modelo.

Precios

GPT Image 2, 2.5 Flare y 2.5 Sunburst comparten tarifas de tokens ($30/1M de salida de imagen, $8/1M de entrada de imagen, $5/1M de entrada de texto; Batch API los reduce a la mitad), pero los tokens por imagen difieren según calidad, tamaño y modelo — así que lee el costo que el script imprime en lugar de asumir. Gemini tiene precio por imagen. Tabla completa y escenarios trabajados: reference/pricing.md.

Hebreo / RTL

Sunburst y Flare renderizaron correctamente un titular en hebreo en una prueba del 2026-10-02 (letras correctas, orden correcto, dirección correcta, junto a inglés y una insignia). Prueba el renderizado directo primero; recurre al flujo de trabajo compuesto para líneas largas en hebreo o una tipografía con licencia requerida. El hebreo no está en la lista de idiomas de mejor rendimiento de Google para modelos de imagen Gemini — prefiere GPT Image para texto en hebreo. Consulta reference/hebrew-rtl.md.

Cuándo NO usar esta habilidad

• El usuario quiere archivos vectoriales editables (SVG con trazados). Estos modelos generan raster; usa la habilidad brand-assets, o Recraft V4.1 Vector (recraftv4_1_vector, SVG nativo, no integrado en estos scripts).
• El usuario quiere dimensiones de píxel exactas fuera de los tamaños compatibles (ej. 1200×630). Genera en la relación de aspecto compatible más cercana, luego recorta/redimensiona.
• El usuario quiere una foto del mundo real de una persona real específica. Ambos proveedores se niegan o producen parecidos inexactos, y hay problemas de política.
• El usuario quiere "arte de IA" general sin un resumen de diseño — dirígelo a ChatGPT o la aplicación Gemini; esta habilidad está ajustada para trabajo de diseño.