shijianjizhe/remotion

codex-image

Genera y edita imágenes con GPT Image a través de la suscripción ChatGPT del usuario. La salida se guarda en ./generated_images/ (o --out-dir / --out).

Cómo ejecutar

Todo pasa por un solo script. Resuelve el directorio absoluto que contiene este SKILL.md (tu harness lo anuncia cuando el skill se carga; abajo se escribe <skill-dir>), luego:

bash "<skill-dir>/scripts/generate.sh" "<prompt>" [flags]

Nunca invoques un scripts/generate.sh relativo desnudo: tu directorio de trabajo es el proyecto del usuario, no la ubicación de instalación del skill (que varía según el agente — ~/.claude/skills/, ~/.agents/skills/, ~/.opencode/skills/, un .claude/skills/ local al proyecto, …).

Requisitos que el script verifica por ti:

• python3 ≥ 3.10 en PATH (bash + stdlib Python en caso contrario).
• Pillow — solo para --format webp y --transparent-mode chroma. No instalado por defecto; esas ejecuciones fallan rápido con el comando de instalación (python3 -m pip install 'Pillow>=10'). El --transparent simple no lo necesita. Menciona este requisito antes del primer uso de cualquiera de estos.
• Codex CLI con sesión iniciada. Si no lo está, el script termina con Ejecuta: codex login — transmite eso al usuario en lugar de tocar la autenticación tú mismo.

bash "<skill-dir>/scripts/generate.sh" --help imprime la superficie completa de flags; consúltalo antes de improvisar flags. Cuando el agente anfitrión soporta comandos de barra tipados, /codex-image "<prompt>" --flags es la abreviatura para el usuario de exactamente esta llamada al script.

El script es mecánico — no hace enrutamiento semántico. El manejo de continuaciones, las decisiones de lote y el envío de eliminación de fondo son TU responsabilidad, basada en la conversación.

GPT Image 2.5

OpenAI ofrece gpt-image-2.5-sunburst para edición precisa y gpt-image-2.5-flare para generación diaria más rápida. Para solicitar uno, pasa --image-model <model-id>; omítelo para mantener la selección por defecto de Codex Responses. Este flag es experimental en el transporte de suscripción: comprobaciones en vivo al 2026-09-08 solicitaron cada variante pero ambas respuestas informaron gpt-image-2-codex. No reclames una actualización 2.5 solo por una solicitud exitosa. Un alias de respuesta heredado o una versión C2PA 2.0 tampoco prueba pesos más antiguos: una imagen publicada en el anuncio 2.5 de OpenAI lleva esa misma versión de procedencia. El script advierte cuando el modelo informado difiere o falta; inspecciona el image_model del sidecar por separado de requested_image_model. --orchestrator selecciona el modelo principal que llama a la herramienta de imagen, no Sunburst o Flare. Déjalo fuera: el script usa el modelo Sol-tier más nuevo (gpt-<version>-sol) que la cuenta lista, por lo que un modelo retirado nunca lo rompe. Las solicitudes van a donde la configuración de Codex envía a Codex: un model_provider personalizado como un proxy, un relay openai_base_url, o chatgpt.com.

Lee Compatibilidad con GPT Image 2.5 para conocer el comportamiento verificado del transporte y las fuentes oficiales. El soporte de la API pública para selección de modelo, xhigh/max y transparencia no establece el mismo comportamiento en Codex Responses.

Manejo de continuaciones

Cuando la solicitud modifica la imagen generada en el turno inmediatamente anterior ("hazlo más oscuro", "ahora añade un sombrero", "más contraste"), pasa --from-last — el script reutiliza la última generación automáticamente (rastreada en ~/.codex-image/last.json), para que no tengas que recuperar la ruta de la transcripción.

Para ediciones de un archivo explícito o una generación anterior, pasa --input <ruta|url> en su lugar (repetible; máximo 16 referencias combinadas con --from-last; el límite de referencias del skill).

Cuando la solicitud es un tema nuevo — incluso si está redactada como "ahora haz…" — no pases ninguno y genera desde cero. Si te equivocas y el usuario dice "no, quería una nueva", vuelve a ejecutar sin referencias.

Las imágenes que el usuario proporciona solo para estilo, composición o estado de ánimo son referencias para una generación, no objetivos de edición — pásalas mediante --input pero redacta el prompt como una imagen nueva ("al estilo de la Imagen 2"). Al mezclar varias entradas, etiqueta cada una por índice y rol en el prompt (Imagen 1: objetivo de edición, Imagen 2: referencia de estilo).

Después de generar: mira, luego informa

Antes de decirle al usuario que has terminado, visualiza el archivo de imagen guardado y compruébalo contra la solicitud: sujeto, composición, cualquier texto literal renderizado al pie de la letra, y cada restricción que el usuario haya indicado. Si algo no está bien, itera con UN cambio dirigido (mediante --from-last), reafirmando los invariantes que no deben desviarse. No acumules múltiples correcciones en una sola re-ejecución, y no informes de una ruta que no hayas mirado.

Disciplina de guardado: la salida por defecto va a ./generated_images/. Si la imagen está destinada al proyecto del usuario, cópiala o muévela a su lugar real (y actualiza cualquier código que la referencie) — no dejes un activo del proyecto solo en el directorio temporal. Nunca sobrescribas un activo existente que el usuario no haya pedido reemplazar; escribe un hermano versionado (hero-v2.png en su lugar).

Imágenes transparentes

Cuando el usuario quiera un fondo transparente, añade --transparent. Eso es todo — sin decisión de envío, sin Pillow, sin paso de post-procesamiento que debas orquestar.

El script le pide al modelo alfa directamente: envía background: "auto" y añade una oración al prompt, y el backend devuelve RGBA. No pases --background transparent; ese valor es rechazado por este backend (docs/adr/0001-request-transparency-in-the-prompt.md explica por qué, y por qué la "solución" obvia es incorrecta).

Si pruebas el backend tú mismo y ves "Transparent background is not supported for this model.", no concluyas que la transparencia no está disponible. Ese 400 es el parámetro siendo rechazado, no la capacidad. El modelo devuelve alfa real cuando se le pide en el prompt, que es lo que hace --transparent. El consejo de que la transparencia nativa necesita gpt-image-1.5 o una OPENAI_API_KEY es anterior a la versión 0.2.0 y es incorrecto; si lo estás leyendo, tu skill instalado está desactualizado. Comprueba metadata.version en este archivo — debería ser 0.2.0 o posterior.

Dos cosas a tener en cuenta al escribir el prompt:

• Describe el sujeto, no una escena. El prompt es más importante que el parámetro. "Una taza sobre una mesa de madera en un estudio iluminado por el sol" puede renderizar ese estudio en lugar de aislar la taza. Nombra el sujeto y su material; deja el entorno fuera.
• No añadas tus propias prohibiciones. El sufijo deliberadamente no prohíbe nada. Si el usuario pidió una sombra paralela, déjasela — vuelve renderizada en el alfa y se compone correctamente. Añadir tú mismo "sin sombra, sin fondo" anula su intención.

Después de generar, visualiza el archivo y comprueba que el alfa realmente llegó. El script advierte en stderr cuando el resultado no tiene alfa o es completamente opaco; trata eso como una señal para re-ejecutar con UN cambio dirigido, generalmente eliminando lenguaje de escena.

Escalera de respaldo, solo cuando el nativo decepciona (verificado en sujetos opacos; cabello, vidrio, humo y translucidez no han sido probados):

Escalada	Acción
Re-prompt	Elimina el lenguaje de escena/fondo, nombra el sujeto solo
Subir calidad	--quality medium para bordes finos y texto pequeño
Chroma	--transparent-mode chroma (necesita Pillow) — tú controlas la placa clave
Adobe MCP	--transparent-mode chroma --bg-tool=none, luego llama a cualquier herramienta de eliminación de fondo de Adobe que esta sesión exponga (busca una herramienta MCP cuyo nombre contenga remove_background) y sobrescribe el archivo con el resultado alfa. Mejor opción para translucidez

Reparación de bordes Chroma: franja fina → --edge-contract 1; bordes escalonados en sujetos mates → --edge-feather 0.25. Modos de fallo más profundos: references/transparent-image-tips.md.

Calidad, coste y salvaguardas de tiempo

• El valor predeterminado es --quality high; se aceptan low, medium, high, xhigh, max y auto. Empieza con low para borradores. Codex Responses puede anular la calidad; inspecciona resolved_quality en el sidecar o la salida --verbose antes de afirmar que se entregó un nivel.
• Las generaciones cuentan contra los límites del plan ChatGPT del usuario. La latencia varía según el modelo, el prompt, la calidad y la carga del servicio.
• Antes de generar más de 3 imágenes para una sola solicitud, confirma primero con el usuario.
• Nunca bucles infinitamente. "Muchas" / "un conjunto completo" → elige un valor predeterminado sensato (4) y ofrece continuar.
• HTTP 429 del backend = detente inmediatamente, no reintentes.

Flujos de trabajo comunes

# Generación única
bash "<skill-dir>/scripts/generate.sh" "un taxi amarillo de noche bajo la lluvia"

# Continuación de la generación anterior
bash "<skill-dir>/scripts/generate.sh" "ahora añade vapor ascendente" --from-last

# Editar una imagen de referencia explícita
bash "<skill-dir>/scripts/generate.sh" "hazlo azul" --input ./taza.png

# Fondo transparente (alfa nativo del modelo; sin Pillow)
bash "<skill-dir>/scripts/generate.sh" "una taza de café" --transparent

# Transparente, con una sombra que el usuario pidió (sobrevive en el alfa)
bash "<skill-dir>/scripts/generate.sh" "una taza de café con una sombra paralela suave" --transparent

# Respaldo Chroma, cuando el nativo decepciona (necesita Pillow)
bash "<skill-dir>/scripts/generate.sh" "un frasco de vidrio" --transparent --transparent-mode chroma

# Diferente tamaño / formato / calidad
bash "<skill-dir>/scripts/generate.sh" "banner hero" --size 2048x1152 --format webp --quality low

Redacción de tokens (seguridad)

NUNCA imprimas o registres el access_token, id_token, refresh_token del usuario, o cualquier cabecera Authorization: Bearer .... Los módulos Python del skill redactan automáticamente; no debes deshacer eso leyendo ~/.codex/auth.json tú mismo o haciendo eco de tokens en mensajes de error.

CUÁNDO NO invocar

• Arte vectorial, SVG, arte ASCII o diagramas LaTeX → usa una herramienta de vectores o diagramas dedicada.
• El usuario explícitamente quiere un modelo o producto diferente (DALL-E, Stable Diffusion, Midjourney) → difiere a eso.

Para trabajo de logo/marca en producción, invoca — pero establece expectativas: genera exploraciones y refina con iteraciones de un solo cambio --from-last en lugar de prometer un activo final de una sola vez (plantillas en references/prompting-cookbook.md).

Referencias

Cuando necesites más profundidad, lee desde <skill-dir>/references/:

• api-recipe.md — cuerpo de solicitud canónico, cabeceras, campos rechazados, mecanismo de transparencia, análisis SSE
• prompting-cookbook.md — fundamentos de prompting + plantillas de casos de uso (logo, foto de producto, maqueta de UI, infografía)
• transparent-image-tips.md — cómo funciona la transparencia nativa, cuándo tiene dificultades, y el respaldo chroma

Contexto a nivel de repositorio: CONTEXT.md (glosario — los tres transportes están definidos allí) y docs/adr/ (por qué la transparencia se solicita en el prompt en lugar del parámetro).