A 29 de marzo de 2026, el safest default para OpenAI mask edits sigue siendo sencillo: empieza con direct images.edit() sobre gpt-image-1.5, sube un alpha mask del mismo tamaño y escribe el prompt como descripción de la imagen final completa, no solo del hueco. Ese pequeño cambio de route evita muchos errores que parecen “problemas del modelo” pero en realidad nacen de una expectativa equivocada.
Este keyword sigue siendo más confuso de lo que debería porque la respuesta actual de OpenAI está repartida. El image generation guide explica los requisitos mecánicos del mask, la sección de input fidelity cubre la preservation, y la guía de tool options en Responses añade la rama action=auto|generate|edit. Si lees solo una de esas páginas, te quedas con media respuesta.
Además, OpenAI ya deja por escrito el caveat importante: el masking de GPT Image es prompt-based guidance y no garantiza un parche local estricto pixel por pixel. De ahí sale la queja clásica de “whole-image rewrite”. El mask guía dónde mirar; no convierte a GPT Image en un editor de capas determinista.
Resumen rápido
- Para one-shot mask edits, empieza por direct
client.images.edit()oPOST /v1/images/edits. - Antes de tocar el prompt, revisa el mask: mismo formato, mismas dimensiones, menos de
50 MBy alpha channel real. - El prompt debe describir la imagen final completa, no solo el objeto que quieres meter en el hueco.
- Añade
input_fidelity="high"solo cuando la preservation de faces, logos o detalles de producto sea realmente importante. - La mental model correcta aquí es constrained semantic rewrite, no strict local patch.
Empieza por la ruta mask-first más segura
Si tu trabajo real es “editar esta zona de esta imagen”, no hace falta empezar con una conversation wrapper. Lo que current docs siguen mostrando como la ruta más corta y más fácil de depurar es el direct Images API: imagen base, mask, final-image prompt, base64 output y guardar el archivo.
La forma actual en JavaScript es esta:
jsimport fs from "fs"; import OpenAI, { toFile } from "openai"; const client = new OpenAI(); const result = await client.images.edit({ model: "gpt-image-1.5", image: await toFile(fs.createReadStream("sunlit_lounge.png"), null, { type: "image/png", }), mask: await toFile(fs.createReadStream("mask.png"), null, { type: "image/png", }), prompt: "A sunlit indoor lounge area with a pool containing a flamingo. Preserve the room, lighting, reflections, and camera angle.", input_fidelity: "high", size: "1024x1024", quality: "medium", }); const imageBase64 = result.data[0].b64_json; const imageBytes = Buffer.from(imageBase64, "base64"); fs.writeFileSync("lounge.png", imageBytes);
En Python, el route no cambia:
pythonfrom openai import OpenAI import base64 client = OpenAI() result = client.images.edit( model="gpt-image-1.5", image=open("sunlit_lounge.png", "rb"), mask=open("mask.png", "rb"), prompt=( "A sunlit indoor lounge area with a pool containing a flamingo. " "Preserve the room, lighting, reflections, and camera angle." ), input_fidelity="high", size="1024x1024", quality="medium", ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("lounge.png", "wb") as f: f.write(image_bytes)
Si quieres ver el contrato raw HTTP, el current multipart path sigue siendo:
bashcurl -s -X POST "https://api.openai.com/v1/images/edits" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "model=gpt-image-1.5" \ -F "mask=@mask.png" \ -F "image[]=@sunlit_lounge.png" \ -F 'prompt=A sunlit indoor lounge area with a pool containing a flamingo'
Lo valioso de empezar aquí es que reduce el failure surface. Puedes aislar si el problema está en access, mask validity, prompt scope o output handling. En este keyword, un primer request aburrido y corto vale más que una primera integración “completa”.
Y hay un matiz current que también importa: /v1/images/edits ya no es solo multipart. Ahora también puede recibir JSON con image_url o file_id, así que incluso si tus assets ya están subidos, direct Images API puede seguir siendo la surface correcta.
Primero construye un mask que la API de verdad acepte
La hora más desperdiciada en este topic suele venir de depurar prompts cuando el mask era invalid desde el principio. Los current mask requirements son pocos, pero son duros:
- la imagen base y el mask deben tener el mismo formato
- deben tener las mismas dimensiones
- el payload debe ser menor de
50 MB - el mask debe incluir alpha channel
El cuarto punto es el que más se pasa por alto. Hay masks que “parecen” correctos porque son blanco y negro, pero en realidad son bitmaps opacos sin alpha. No por casualidad OpenAI incluye un ejemplo para añadir alpha a una máscara black-and-white.
Ahora bien, mechanical validity no equivale a strict behavioral obedience. Los docs dicen a la vez que la parte transparente es la que se reemplaza y que GPT Image no sigue la forma del mask con precisión total. Esas dos frases juntas describen la realidad operacional: el mask restringe el área semántica del cambio, pero no congela el resto de la imagen como lo haría un editor clásico.
El preflight más útil en producción es este:
- iguala base image y mask a la misma resolución final
- guarda el mask como RGBA PNG real
- verifica que la zona a cambiar sea transparente de verdad
- mantén el área del mask lo más pequeña posible
Y si usas varias imágenes de entrada, recuerda otra current rule importante: el mask se aplica a la primera input image. La primera imagen debe ser la escena base; las demás son referencias complementarias.
Escribe el prompt para la imagen final completa, no para el hueco
La frase más importante en los docs actuales para este query no habla del endpoint, sino del prompt: describe the full new image, not only the erased area. Si se te escapa, puedes tener un mask perfecto y aun así obtener un resultado inestable.
GPT Image no “rellena un agujero” de manera mecánica. Produce una nueva final image coherente. Por eso el prompt debe hacer tres trabajos a la vez:
- decir qué cambia
- decir qué se conserva
- describir cómo debe verse la escena final
Prompt flojo:
textPut a flamingo in the pool.
Prompt mejor:
textA sunlit indoor lounge area with a pool containing a flamingo. Preserve the pink room walls, the pool tile pattern, the reflections, the furniture, and the camera angle. Do not redesign the rest of the room.
Si el trabajo es de logo, packaging o producto, la lista de conservación debe ser todavía más explícita:
textReplace only the blank label area on the bottle with a clean gold logo. Preserve the bottle shape, cap, glass reflections, lighting, shadows, background, and camera framing. Do not change any other packaging detail.
Por eso el GPT Image 1.5 prompting guide suele ser más útil que muchas tutorials genéricas. La clave no es escribir un prompt enorme, sino separar change list y preserve list, y luego iterar con cambios pequeños.
Si el output ya está cerca, no rehagas todo el prompt. Una corrección del tipo “keep everything the same, but enlarge the logo slightly” suele ser más estable que una reescritura completa.
Cuándo input_fidelity=high sí cambia el resultado
Mask e input_fidelity no hacen el mismo trabajo. Mask controla location; input_fidelity controla la fuerza de preservation sobre los detalles de entrada. Si mezclas ambos conceptos, terminas culpando al mask por problemas que en realidad vienen de una preservation demasiado débil.
La current input fidelity section dice claramente que high ayuda sobre todo con faces y logos. También especifica que gpt-image-1.5 preserva con mayor fidelity las primeras 5 imágenes de entrada; en gpt-image-1 y gpt-image-1-mini, la primera imagen recibe la preservación más fuerte. El valor por defecto es low.
El split práctico se resume así:
| Situación | ¿Suele bastar el mask? | ¿Conviene añadir input_fidelity="high"? | Por qué |
|---|---|---|---|
| Reemplazo simple en una escena casual | A menudo sí | Normalmente no | La localización pesa más que la preservation de detalle |
| Edit cerca de una face | No siempre | Casi siempre sí | El drift de identidad es caro |
| Poner un logo en packaging, ropa o signage | Rara vez | Sí | El mask da posición, pero no garantiza recognizability |
| Product hero shot con geometría importante | Rara vez | Sí | Geometría, reflejos y consistencia visual pesan más que la latencia |
| Esperar un parche estrictamente local | No | Ni siquiera high basta del todo | Fidelity ayuda, pero no vuelve determinista al modelo |
En la práctica, si “el mask está bien pero el logo o la cara se mueven”, casi siempre estás ante un preservation problem, no un mask problem. high cuesta más image input tokens, así que no hay que activarlo por costumbre, pero en workflows sensibles suele merecer la pena antes que seguir retocando el wording del prompt.
Si quieres el contexto más amplio de modelos, OpenAI image generation API models es el siguiente paso. Para este query basta recordar: mask = dónde cambiar, fidelity = cuánto conservar.
Por qué los masked edits reescriben más de lo esperado
Los docs son bastante honestos aquí. La sección de mask explica que GPT Image usa el mask como guidance y que puede no seguir su forma con precisión completa. Traducido a una regla operacional, eso significa que el current masked edit se comporta más como constrained semantic rewrite que como strict local patch.
La comunidad lleva señalando esto al menos desde el 27 de abril de 2025: puedes tener un mask válido y aun así sentir que la escena entera se reinterpretó. Eso no implica que el endpoint esté roto; suele implicar que la expectativa era más rígida que el comportamiento actual del modelo.
Las causas más frecuentes del overreach son:
- el prompt describe solo el objeto nuevo y deja infradescrita la escena que debería seguir igual
- el edit toca faces, logos, packaging o layout sensibles sin
input_fidelity="high" - el área del mask es demasiado grande y obliga al modelo a reinterpretar contexto cercano
- el equipo sigue pensando en términos de inpainting clásico
La corrección no es dejar de usar mask. La corrección es cambiar el marco mental y el workflow:
- reducir el scope del edit cuando sea posible
- explicitar la preserve list
- usar high fidelity solo donde el drift sea caro
- añadir crop o segmentation antes si se necesita un control local extremo
Si el requirement real del producto es “cambia estos píxeles y absolutamente nada más”, entonces el problema ya no es solo de prompt. Es un problema de compatibilidad entre la exigencia del workflow y el comportamiento actual del modelo.
Images API vs Responses para un workflow mask-heavy
Responses es útil, pero para muchos mask-first workflows llega demasiado pronto. Al leer juntos el current image generation guide y la página de tool options, el split es bastante claro: con gpt-image-1.5 o chatgpt-image-latest en Responses, puedes fijar action en auto, generate o edit, y OpenAI recomienda dejar auto salvo que realmente necesites forzar el comportamiento.
Eso deja una regla útil:
- direct Images API para single edits claros
- Responses cuando el edit vive dentro de una assistant chain mayor
- JSON
/v1/images/editssi solo necesitas reutilizar uploaded assets sin subir de surface
En otras palabras, “ya tenemos los files subidos” ya no es una razón fuerte para cambiar de surface. La pregunta correcta es si tu producto necesita orchestration más amplia o no.
Si necesitas una comparación más amplia entre surfaces, sigue con el tutorial de OpenAI Image API. Pero para este exact query, la respuesta sigue siendo: empieza por la route directa más corta.
Troubleshooting: por qué el mask sigue fallando o se pasa de largo
El orden de diagnóstico que menos tiempo desperdicia es este:
-
La API rechaza el mask o parece ignorarlo.
Revisa primero format, dimensions, payload size y alpha. Mientras eso no esté bien, no tiene sentido tocar el prompt. -
La región cambiada es más o menos correcta, pero la escena completa cambia.
Lo habitual es que el prompt describa el cambio pero no la escena que debe permanecer igual. Reescríbelo como full final-image description y añade una preserve list explícita. -
El cambio se derrama fuera del mask.
En GPT Image no es raro. Reduce el área del mask, baja la cantidad de cambio por intento y vuelve más concretas las instrucciones de preservation. -
Faces, logos o branded objects siguen derivando.
Eso suele ser un problema de preservation, no de location. Activainput_fidelity="high"y especifica qué detalles no pueden cambiar. -
Necesitas iteraciones múltiples y referencias persistentes.
Ahí sí tiene sentido evaluar Responses o JSON/v1/images/edits. -
Tu requirement exige verdadera fiabilidad pixel-local.
Comprueba si la expectativa supera el comportamiento actual del modelo. Si la supera, el fix real está en crop, segmentation o preprocessing.
Ese orden de troubleshooting es precisamente lo que aún falta en buena parte del page one. Muchas páginas explican una pieza, pero pocas conectan file validity, prompt scope, preservation pressure y route choice en una sola secuencia accionable.
FAQ
Si la zona del mask es transparente, ¿cambian solo esos píxeles exactos?
No. Los current docs dicen que la región transparente es la parte a reemplazar, pero también que GPT Image masking sigue siendo prompt-based y no garantiza exact shape following. Conviene pensarlo como constrained rewrite, no como cirugía local estricta.
¿Conviene usar Responses por defecto para mask edits en lugar de images.edit()?
No por defecto. Para one-shot edits, empieza con direct Images API. Pasa a Responses cuando el edit forme parte de una conversación multi-turn o de un workflow multimodal más amplio.
Si el mask está bien, ¿por qué deriva el logo o la face?
Porque el mask controla la localización, no la fuerza de preservation. Ese es justamente el caso típico para input_fidelity="high" más una preserve list clara en el prompt.
Recomendación final
El default actual para OpenAI mask edits sigue siendo muy práctico: usa gpt-image-1.5 con direct Images API, valida primero el mask en lo mecánico, escribe el prompt como descripción de la imagen final completa y añade input_fidelity="high" solo cuando la preservation lo justifique. Esa combinación resuelve más problemas reales que empezar por un framework mayor.
Si aun así el resultado reescribe más de la cuenta, no asumas primero que el upload falló. Comprueba antes si la expectativa del producto es más estricta que el comportamiento actual de GPT Image masking. Para el route general de edición, la siguiente lectura útil es la guía de OpenAI image editing API; para access y capability checks antes del rollout, la siguiente pieza práctica es la guía de OpenAI image generation API verification.