La API de edición de imágenes OpenAI modifica una imagen existente a partir de una indicación. La ruta nativa es POST /v1/images/edits; admite una imagen, una indicación y controles de edición opcionales, como una máscara o imágenes de referencia. Utiliza la API de Imágenes para una solicitud específica y la API de Respuestas cuando el producto requiera un flujo de trabajo de imágenes de varios pasos.
Una edición fiable es un pequeño proceso: congelar el archivo de origen, indicar qué debe mantenerse, indicar qué puede cambiar, revisar los bytes devueltos y guardar el recurso aprobado. Si prefieres alternar entre modelos de imagen y otras herramientas multimedia en un mismo espacio de trabajo, Crear y editar imágenes con GPT Image 2 en GlobalGPT; su API pública utiliza un contrato de tareas asíncronas diferente, que esta guía distingue del punto final nativo de OpenAI.
Respuesta rápida: elige la estrategia antes de escribir el código
| Necesita | Ruta | Solicitar forma | Resultado que hay que gestionar |
|---|---|---|---|
| Una generación o edición de imagen | API de imagen de OpenAI | POST /v1/images/edits, formulario de varias hojas | data[0].b64_json; descodificarlo y guardarlo |
| Varias vueltas con contexto de imagen | API de respuestas OpenAI | POST /v1/responses con una herramienta de generación de imágenes | Extraer el elemento de salida correspondiente a la generación de imágenes |
| Varios modelos de medios detrás de una misma cuenta | API pública GlobalGPT | POST /tasks, y luego realizar una consulta GET /tasks/{id} | output.url; guárdalo antes de que finalice el plazo de 30 días |
Los nombres de los puntos finales parecen similares, pero los cuerpos de las solicitudes y el tratamiento de los resultados no son intercambiables.
¿Para qué sirve la API de edición de imágenes OpenAI?
El proceso de edición parte de una imagen ya existente. Tu solicitud describe el cambio, mientras que la imagen de entrada proporciona el contexto visual que debe conservarse tras la edición. Puedes sustituir un fondo, añadir o eliminar un elemento, realizar un cambio de estilo más amplio o pasar más de una imagen como referencia. El modelo sigue interpretando la solicitud; la API no es un editor de píxeles con un límite de selección garantizado.
El documento OpenAI describe dos flujos de trabajo útiles. El API de imágenes es la opción más adecuada cuando una solicitud debe devolver una sola imagen. El API de respuestas es la opción más adecuada cuando el usuario va a revisar el resultado, solicitar otro cambio y mantener el contexto de la imagen a lo largo de las rondas. Esa elección afecta tanto a la estructura de la solicitud como al código que extrae el resultado.
API de imágenes frente a API de respuestas
| Pregunta | API de imágenes | API de respuestas |
|---|---|---|
| Lo mejor para | Una única acción de creación o edición | Una experiencia de edición en varias fases |
| Entrada típica | Imagen de varias partes, indicación, máscara opcional | Herramienta de generación de imágenes y de entrada de texto para conversaciones |
| Gestión de la producción | data[0].b64_json | Busca el elemento de salida de generación de imágenes |
| Desglose de costes | La edición directa utiliza las velocidades de entrada y salida actuales | Las normas de entrada almacenadas en caché pueden variar; consulta las tarifas actuales |
Realiza una primera edición con la API nativa OpenAI
Guarda la clave API en tu servidor y cárgala desde una variable de entorno. El ejemplo siguiente envía una imagen y una indicación al punto final de ediciones documentado. El imagen[] El campo se puede repetir cuando el modelo seleccionado admite varias entradas. El canal de comandos del shell descodifica la primera imagen en formato Base64 devuelta y la convierte en un archivo PNG local.
Edición con Native Curl: guardar el resultado de b64_json
curl -s \
-X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-2.5-sunburst" \
-F "image[]=@source.png" \
-F "prompt=Sustituye únicamente el fondo por una escena de estudio en tonos beige cálidos; mantén el producto y la etiqueta sin cambios." \
| jq -r '.data[0].b64_json' \
| base64 --decode > edited.pngEdición del SDK de Python: descodificar los bytes devueltos
from openai import OpenAI
import base64
client = OpenAI()
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("source.png", "rb"),
prompt="Sustituye únicamente el fondo por una escena de estudio en tono beige cálido; mantén el producto y la etiqueta sin cambios.",
)
image_bytes = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as output:
output.write(image_bytes)Antes de dar por lista esta producción, comprueba el archivo descodificado: verifica su tipo MIME, sus dimensiones, el número de bytes y si los detalles visuales importantes siguen estando presentes. Una respuesta 200 solo indica que la solicitud ha sido aceptada; no te garantiza que la etiqueta, el logotipo o la geometría del producto se hayan conservado.
Utiliza las máscaras y las imágenes de referencia de forma segura
Una máscara indica al modelo qué zona quieres modificar, pero el enmascaramiento de imágenes de GPT sigue basándose en las instrucciones. La guía de OpenAI advierte explícitamente de que el modelo utiliza la máscara como orientación y no como un límite absoluto de píxeles. Asegúrate de que las instrucciones sean específicas en cuanto al sujeto que deseas proteger y revisa la imagen completa tras la generación.
Comprobación previa de la máscara
- La imagen y la máscara tienen el mismo formato.
- La imagen y la máscara tienen las mismas dimensiones.
- El archivo de la máscara ocupa menos de 50 MB.
- La máscara contiene un canal alfa.
- Las instrucciones indican qué debe permanecer sin cambios y qué debe sustituirse.
Comprueba la máscara antes de subirla
from PIL import Image
source = Image.open("source.png")
mask = Image.open("mask.png")
assert source.format == mask.format, (source.format, mask.format)
assert source.size == mask.size, (source.size, mask.size)
assert mask.width * mask.height > 0
assert mask.mode in {"RGBA", "LA"}, mask.mode
assert mask.fp is None or True # comprueba por separado el tamaño del archivo en el disco
print("source:", source.size, source.format)
imprimir("máscara:", máscara.tamaño, máscara.modo)Si se pasan varias imágenes con una máscara, según la guía actual, la máscara se aplica a la primera imagen. Este es un criterio útil a la hora de diseñar un flujo de trabajo de referencia: haz que la primera entrada sea el recurso cuya zona pretendes editar y trata las imágenes restantes como referencias, en lugar de dar por hecho que la máscara se aplica a todas ellas.
Las imágenes de referencia resuelven un problema diferente. Pueden aportar una identidad al producto, una familia de iluminación, una paleta de colores o una referencia compositiva. No obligan al modelo a conservar cada contorno. Si es necesario mantener sin cambios la forma exacta de un envase o una etiqueta, utiliza una fase de revisión visual o un paso de edición convencional tras la generación del modelo.
Elige el modelo y los parámetros
La guía de imágenes actual del OpenAI incluye gpt-image-2.5-sunburst, gpt-image-2.5-flare, y gpt-imagen-2. Considera los nombres de los modelos y las opciones compatibles como documentación en constante evolución: consulta la página del modelo justo antes de integrarlos y marca como fija una versión con fecha si la reproducibilidad es importante.
Decisiones sobre los parámetros que evitan fallos evitables
| Decisión | Regla práctica | Por qué es importante |
|---|---|---|
| Fidelidad de entrada | Omitir fidelidad_de_entrada para gpt-imagen-2; sus entradas de imagen se procesan con alta fidelidad. | El envío de un campo no admitido puede convertir una modificación válida en una solicitud rechazada. |
| Calidad | El documento sobre las rutas «2.5 Sunburst» y «Flare» bajo, medio, alto, xalto, y máx.. | Un valor más alto supone una elección entre coste y latencia, no una garantía de una mejor conservación. |
| Formato | Pide el formato de salida que documenta el punto final actual y, a continuación, revisa el archivo descodificado. | Tu canal de almacenamiento debería basarse en los bytes y el tipo MIME, y no solo en la opción solicitada. |
| Antecedentes | Indica el fondo deseado en la instrucción y utiliza la opción de fondo documentada cuando sea compatible. | El modelo sigue interpretando la escena; mantén explícitas las restricciones del sujeto. |
| Referencias | Utiliza una imagen de referencia para orientarte en cuanto a la identidad, el color o la iluminación, y define la función de cada elemento. | La ambigüedad en las funciones de las imágenes dificulta el diagnóstico de la deriva. |
¿Cuánto cuesta la API de edición de imágenes OpenAI?
OpenAI tarifica el uso de GPT Image por categorías de tokens, en lugar de aplicar una tarifa plana universal por edición. La página de tarifas actual muestra tarifas distintas para entradas de imagen, entradas en caché y salidas de imagen. Las ediciones directas de la API de imágenes no se someten al tratamiento de «entrada en caché» documentado para la herramienta de generación de imágenes en la API de respuestas, por lo que no se debe copiar una estimación de la API de respuestas en una solicitud directa /v1/imágenes/modificaciones presupuesto.
Tarifas de los tokens de imagen publicadas, verificadas el 28 de septiembre de 2026
| Modelo | Entrada de imágenes / 1 millón de tokens | Entrada de imagen almacenada en caché / 1 millón de tokens | Generación de imágenes / 1 millón de tokens |
|---|---|---|---|
| GPT Image 2.5 | $8 | $2* | $30 |
| GPT Imagen 2 | $4 | $1* | $15 |
*La columna «cached-input» se muestra para el contexto de precios publicado. La guía de precios indica que «cached-input» se aplica a la herramienta de generación de imágenes de la API de Respuestas, no a las solicitudes directas a la API de Imágenes, como por ejemplo /v1/imágenes/modificaciones. Las tarifas pueden variar; haz el cálculo basándote en el consumo indicado en tu propia solicitud.
Elabora un presupuesto transparente basado en el consumo
def estimate_image_cost(image_input_tokens, image_output_tokens,
input_rate, output_rate):
return (image_input_tokens / 1_000_000) * input_rate + \
(image_output_tokens / 1_000_000) * output_rate
# Solo a modo de ejemplo: sustitúyelo por el uso que le des en tu respuesta.
estimate = estimate_image_cost(
image_input_tokens=250_000,
image_output_tokens=120_000,
input_rate=4.00,
output_rate=15.00,
)
print(f"${estimate:.4f}")Esta fórmula es un ejemplo orientativo, no una garantía de que la factura por imagen sea fija. Incluye en tu propio presupuesto los reintentos, el almacenamiento de archivos y cualquier uso adicional de texto o herramientas. Cuando el resultado sea importante, mantén juntos la solicitud, el uso de la respuesta, el hash del archivo descodificado y la decisión de aprobación.
GlobalGPT utiliza un contrato de API de edición de imágenes diferente
En Documentación de la API de GlobalGPT describe la generación de imágenes, vídeos y audio como tareas multimedia asíncronas. Su URL base pública es https://api2.glbgpt.com/ai-api/open/v1. Envía el JSON a /tareas, encuesta /tareas/{id}, y leer output.url tras completar una tarea con éxito. El catálogo de modelos recoge gpt-imagen-2 y gpt-image-2.5 como rutas de edición de imágenes o de referencia con hasta cuatro imágenes de entrada y relación de aspecto.
Documentación de la API pública de S05: Documentación pública sobre el contrato de tareas asíncronas; este artículo lo distingue del punto final nativo de ediciones multiparte de OpenAI.
Catálogo de modelos públicos de la temporada 6: Pruebas públicas del catálogo de modelos para las rutas de GPT Image y sus límites documentados en cuanto a tareas relacionadas con imágenes; comprueba los créditos y los campos dinámicos antes de publicar.
Forma de la tarea pública GlobalGPT
BASE="https://api2.glbgpt.com/ai-api/open/v1"
# Opcional: obtener un presupuesto sin crear una tarea ni reservar créditos.
curl "$BASE/tasks/estimate" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantén la botella y la etiqueta sin cambios. Sustituye únicamente el fondo por una iluminación de estudio en tono beige cálido.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Enviá solo después de comprobar el presupuesto.
curl "$BASE/tasks" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image-edit-example-001" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantén la botella y la etiqueta sin cambios. Sustituye solo el fondo por una iluminación de estudio en tono beige cálido.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Consulta el ID de la tarea devuelta hasta que se complete con éxito o falle.
curl "$BASE/tasks/TASK_ID" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY"No pegues el archivo multiparte de OpenAI máscara, fidelidad_de_entrada, talla, o calidad campos en este JSON y dar por hecho que funcionan. La documentación pública actual de GlobalGPT no incluye esos campos para esta ruta de imagen. Los campos no compatibles pueden omitirse y reflejarse en parámetros_ignorados, así que comprueba esa respuesta antes de dar por hecho que un ajuste ha surtido efecto.
Según la documentación pública, GlobalGPT reserva créditos cuando se envía una tarea multimedia, los libera cuando la tarea falla y mantiene disponibles los archivos multimedia que se han procesado correctamente durante 30 días. Guarda el recurso devuelto en un almacenamiento que controles si necesitas que la URL permanezca activa durante más tiempo. Utiliza el punto final de estimación antes de un lote, una clave de idempotencia al reintentar una solicitud de red y el ID de tarea original cuando una consulta simplemente sea lenta.
Lo que reveló la prueba del modelo GlobalGPT
Para concretar esta distinción, el 28 de septiembre de 2026 realicé una prueba de la API del modelo GlobalGPT con límites, utilizando dos indicaciones de entrada ficticias y sin marcas, y dos indicaciones de edición. En cada tarea se utilizó GPT Image 2, una solicitud 3:2 y la primera salida válida. Las imágenes que se muestran a continuación son pruebas del modelo, no una sesión del espacio de trabajo del navegador, ni una prueba de rendimiento, ni una garantía de que cada edición conserve todos los contornos.
Entrada P00: La imagen original congelada: una botella ficticia sin marca, con un tapón blanco corto y una etiqueta pequeña.
Referencia P01: La imagen de referencia «congelada»: se utiliza únicamente para la iluminación y el color, no como una segunda identidad del producto.
T01: edición del fondo de una imagen
Mostrar el mensaje completo
Mantén sin cambios la botella de cerámica, el tapón blanco corto, el texto ficticio de la etiqueta "NORTH" y "250 ml", los colores, el ángulo de la cámara y las proporciones de la imagen original. Sustituye únicamente el fondo blanco puro por un entorno de estudio interior en tonos beige cálidos, inspirado en la suave luz que entra por la ventana y en las sombras tenues. No añadas ningún objeto, logotipo, palabra, marca de agua, persona ni etiqueta nuevos. Mantén la botella como único motivo en una composición horizontal de 3:2.
Lo que esto demuestra: La botella sigue siendo reconocible, se ve la etiqueta «NORTH / 250 ml» y el fondo blanco da paso a una cálida escena interior en tonos beige con suaves sombras que parecen procedentes de una ventana.
Límite: Este es un primer resultado válido. No garantiza la conservación exacta de los píxeles ni la fidelidad general de las etiquetas.
T02: referencia de iluminación y color con dos imágenes
Mostrar el mensaje completo
Utiliza la imagen de entrada 1 como referencia exacta del producto y la imagen de entrada 2 únicamente como referencia para la iluminación beige cálida, la temperatura de color y las sombras suaves del interior. Mantén sin cambios la forma de la botella de cerámica, el tapón blanco corto, el texto ficticio de la etiqueta "NORTH" y "250 ml", los colores, el ángulo de la cámara y las proporciones de la imagen de entrada 1. Sustituye el fondo blanco por una escena tranquila de estudio interior en tonos beige cálidos. No copies ningún objeto, texto, logotipo, marca de agua, persona o etiqueta adicionales de la imagen de entrada 2. Mantén la botella como único sujeto en una composición apaisada de 3:2.
Lo que esto demuestra: El producto y la etiqueta NORTH / 250 ml siguen siendo reconocibles, mientras que la escena retoma el ambiente cálido en tonos beige de la habitación, la mesa y la luz que entra por la ventana del modelo P01.
Límite: La proporción de la tapa de la botella, el contorno de la botella y su ubicación han cambiado de forma visible. No se debe considerar que esto supone una conservación perfecta o exacta de la identidad; recurre a la comparación manual cuando las dimensiones de la mercancía deban coincidir.
Cómo utilizar estos datos: El resultado útil es un proceso de revisión repetible. Se bloquea la URL de entrada, se nombra el tema protegido, se describe la función de referencia, se inspeccionan los bytes devueltos y se compara el producto aprobado con la fuente antes de su publicación. La transferencia de estilo puede tener éxito aunque la geometría siga variando.
Gestionar los errores y las respuestas lentas
Síntoma → comprobación → acción
| Síntoma | Compruébalo primero | El siguiente paso seguro |
|---|---|---|
| 401 / error de autenticación | Clave del lado del servidor, permisos de la cuenta, host del punto final | Detén el proceso y corrige la autenticación; no evalúes la calidad de la imagen. |
| 400 / 422: solicitud incorrecta | ID del modelo, nombres de campos compuestos, tipo de archivo, opciones no admitidas | Modifica únicamente el campo indicado en el error y conserva la solicitud original que ha dado error. |
| 429 / 5xx / capacidad | Si se ha creado un ID de tarea | Si no existe ningún ID de tarea, vuelve a intentarlo una vez según tu política; si existe una tarea, consulta ese ID. |
| La tarea permanece en cola o en proceso | Estado, hora de la última consulta, estimación del proveedor | Realiza una consulta a intervalos fijos; no crees un duplicado mientras se desconozca el estado. |
| El resultado es un objeto JSON guardado como imagen | Tipo de contenido, primeros bytes, formato descodificado | Analizar la respuesta, descodificar b64_json o descargar output.url, y luego valídalo. |
| Parece que el parámetro no tiene ningún efecto | GlobalGPT parámetros_ignorados y ficha del modelo | Elimina los campos no compatibles y utiliza el contrato específico del modelo. |
Distingue entre las pruebas de transporte y las pruebas de calidad. Un tiempo de espera agotado, un error de DNS o una respuesta de capacidad del proveedor significan que no dispones de una imagen válida para evaluar. Por el contrario, una imagen válida con un límite o una etiqueta modificados es un resultado visual que debe comunicarse tal cual, aunque la composición resulte atractiva.
Lista de comprobación para la edición de imágenes en un entorno de producción seguro
- Congelar la fuente: guardar el archivo de entrada, las dimensiones, el formato y el hash.
- Asignar funciones a las imágenes: Identifica la imagen en cuestión y cualquier referencia en cuanto a iluminación, paleta de colores o composición.
- Señales protegidas contra escritura: Enumera la marca, la silueta, los colores y las proporciones que hay que revisar.
- Elige el contrato: Utiliza «OpenAI multipart» para el punto final de ediciones nativas o «GlobalGPT JSON tasks» para su API de medios pública.
- Calcular y enviar: utilizar las tarifas actuales OpenAI o GlobalGPT
/tareas/presupuesto; añade una clave de idempotencia para que los envíos se puedan repetir sin problemas. - Solicitar y descodificar: Conservar un identificador de tarea, validar el archivo devuelto y guardar los bytes o la URL en un almacenamiento autorizado.
- Aprobar visualmente: Compara el resultado con el original antes de que se incluya en un catálogo de productos, un anuncio o una página dirigida a los clientes.
Si quieres ejecutar el mismo proceso sin tener que unir distintos paneles de control de modelos, prueba a Imagen GPT 2 en GlobalGPT. Para consultar la versión del flujo de trabajo diseñada para navegadores, véase editar imágenes en el espacio de trabajo GlobalGPT; para obtener más información sobre la configuración y los precios, consulta Configuración y tarifas de la API de imágenes de GPT.
Preguntas frecuentes
¿Qué es la API de edición de imágenes OpenAI?
Se trata de la ruta de edición de imágenes en POST /v1/images/edits. Se envía una imagen de entrada y una indicación, opcionalmente con una máscara o imágenes de referencia, y a continuación se descodifican los datos de la imagen devueltos. Utiliza la API de imágenes para una única edición y la API de respuestas cuando el producto requiera una conversación en varias rondas sobre imágenes.
¿Devuelve la API de edición de imágenes OpenAI una URL pública de la imagen?
Los ejemplos documentados de la API de imágenes devuelven b64_json. Decodifica esos bytes, comprueba la validez del archivo y guárdalo en un almacenamiento que controles. No des por sentado que una respuesta satisfactoria es una URL alojada en una CDN.
¿La máscara de imagen OpenAI permite una selección exacta de píxeles?
No. Una máscara sirve de guía para una edición basada en indicaciones. El modelo puede modificar los píxeles que rodean el área solicitada, por lo que debes revisar las etiquetas, los detalles del producto, las marcas de seguridad y otros elementos que deben mantenerse correctos.
¿Cuántas imágenes de entrada puede utilizar un programa de edición de imágenes?
La guía de imágenes actual admite varias imágenes de entrada para flujos de trabajo de referencia. Para conocer el límite exacto y el comportamiento específico de cada modelo, consulta la documentación del modelo en cuestión; el número máximo admitido no garantiza una conservación perfecta en todas las composiciones.
¿Puedo enviar la solicitud OpenAI /v1/images/edits a GlobalGPT cambiando el valor de base_url?
El contrato de medios públicos del n.º GlobalGPT utiliza JSON POST /tasks y, a continuación, GET /tasks/{id}, con imágenes y aspecto_ratio cuando el modelo seleccionado los acepta. La documentación pública no incluye la máscara multiparte, el parámetro `input_fidelity`, el tamaño ni el contrato de calidad de OpenAI para esa ruta.
¿Cómo debo calcular el tiempo necesario para una tarea de imagen antes de enviarla?
Para GlobalGPT, envía primero el mismo cuerpo JSON a /tasks/estimate. Esto no crea ninguna tarea ni reserva créditos. Para OpenAI, realiza el cálculo con las tarifas actuales por millón de tokens y, a continuación, comprueba el uso real en la respuesta o en el registro de facturación.
