Muchos desarrolladores que integran la interfaz de edición de imágenes de gpt-image-2 se topan con el mismo problema: al revisar la página de Referencia de la API de images/edit, solo encuentran la mención de que "los modelos de imagen GPT permiten hasta 16 imágenes", pero no logran hallar el límite de tamaño por archivo. ¿Es que no hay límite? ¿O es que la documentación está incompleta?
La respuesta es: el límite existe y es muy claro: cada imagen debe ser menor a 50 MB, y se admiten los formatos PNG, WebP y JPG. El problema es que esta regla no aparece en la tabla de parámetros de la página de Referencia, sino en otra guía de uso de Generación de Imágenes. Esta fragmentación de la información hace que muchos pierdan tiempo innecesariamente.
En este artículo, desglosaremos por completo las restricciones de carga de imágenes de la API de gpt-image-2: cantidad, tamaño, formato, reglas de máscara, restricciones de resolución y un tema práctico mucho más importante que el límite de 50 MB: por qué no te recomendamos enviar imágenes de ese tamaño.
Restricciones de carga de imágenes en la API de gpt-image-2: especificaciones oficiales completas
Primero, pongamos la conclusión sobre la mesa. gpt-image-2 recibe imágenes de entrada a través del endpoint v1/images/edits. Las restricciones oficiales completas se muestran en la siguiente tabla.
Tabla de referencia rápida de restricciones de carga de imágenes en gpt-image-2
| Restricción | Especificación oficial | Fuente de documentación |
|---|---|---|
| Máximo de imágenes por solicitud | 16 (modelos de la serie GPT image) | Referencia de API: images/edit |
| Tamaño por imagen | < 50 MB | Guía de uso de Generación de Imágenes |
| Formatos admitidos | PNG, WebP, JPG | Guía de uso de Generación de Imágenes |
| Método de carga | image_url o file_id (uno de los dos) |
Referencia de API: images/edit |
| Máscara (mask) | Mismo formato y tamaño que la original, < 50 MB, debe incluir canal alfa | Guía de uso de Generación de Imágenes |
| Cantidad de generación n | 1-10 imágenes | Referencia de API: images/edit |
En otras palabras, teóricamente una solicitud de edición puede contener hasta 16 imágenes de casi 50 MB cada una. Sin embargo, el "límite teórico" y la "implementación en ingeniería" son cosas distintas, algo que detallaremos más adelante.
Aquí hay un detalle importante que suele causar problemas: el parámetro images de la nueva API recibe un arreglo de objetos, donde cada objeto proporciona image_url o file_id. El file_id proviene de una carga previa mediante la API de Files, ideal para bibliotecas de materiales reutilizables; image_url admite direcciones públicas o URL de datos en base64, ideal para solicitudes únicas. El límite de 50 MB se aplica de la misma manera en ambos casos.
🎯 Consejo para pruebas rápidas: Si no estás seguro de si tus imágenes activarán una restricción, la forma más directa es realizar una solicitud real y observar el mensaje de error. Recomendamos realizar este tipo de pruebas de límites a través de la interfaz compatible con OpenAI de APIYI (apiyi.com), donde el panel de registros permite ver el tamaño del cuerpo de la solicitud y los detalles del error de forma mucho más clara que al llamar directamente a la API oficial.
¿Por qué no encuentro el tamaño de carga de gpt-image-2 en la documentación?
Volviendo a la pregunta inicial: ¿por qué la página de referencia solo menciona 16 imágenes y no el tamaño? En realidad, esto es una decisión de diseño en la estructura de la documentación de OpenAI. La página de referencia de images/edit está organizada según el "Esquema de parámetros"; el parámetro images es simplemente un arreglo de objetos a nivel de esquema, por lo que el límite de cantidad se incluye allí. Sin embargo, el tamaño y el formato del archivo pertenecen a la "validación en tiempo de ejecución", por lo que se clasifican dentro del texto narrativo de la guía de generación de imágenes.
Existen otras reglas "ocultas en la guía" que es mejor confirmar antes de desarrollar funciones de edición de imágenes:
- Tres requisitos para la máscara (mask): Debe tener el mismo formato y dimensiones que la imagen editada, el archivo también debe ser menor a 50 MB y debe incluir un canal alfa. Usar un JPG como máscara es la causa más común de errores, ya que el formato JPG no admite canal alfa.
- La resolución no es arbitraria: El parámetro
sizede gpt-image-2 admite resoluciones personalizadas, pero tiene restricciones estrictas: el lado más largo no debe exceder los 3840 px, tanto el ancho como el alto deben ser múltiplos de 16 px, la relación de aspecto no debe superar los 3:1 y el total de píxeles debe estar entre 655,360 y 8,294,400. - Las imágenes de entrada se facturan: Las imágenes de referencia en una solicitud de edición se facturan según los tokens de entrada de imagen; cuando se usa
input_fidelity: high, el consumo de tokens de entrada aumenta significativamente.
Restricciones de resolución y parámetros de tamaño de gpt-image-2
| Dimensión de restricción | Regla | Ejemplo |
|---|---|---|
| Lado más largo | ≤ 3840 px | 3840×2160 (4K horizontal) disponible |
| Alineación de lados | Ancho y alto múltiplos de 16 px | 1024, 1536, 2048 son válidos |
| Relación de aspecto | ≤ 3:1 | 2048×1152 válido, 3072×1024 válido |
| Total de píxeles | 655,360 – 8,294,400 | Menos de 768×854 será rechazado |
| Ajustes preestablecidos | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | Igual para formato vertical |
Si tu negocio requiere cambiar frecuentemente entre diferentes resoluciones, te sugerimos crear una validación local antes de la solicitud, interceptando tamaños ilegales en el cliente; esto ahorra un viaje de ida y vuelta en comparación con esperar a que la API devuelva un error 400. En el centro de documentación de APIYI (apiyi.com) también hemos recopilado una lista de verificación de parámetros para gpt-image-2 que puedes usar directamente para tu implementación.
gpt-image-2 en la práctica: 50 MB es el límite, 1.5 MB es el punto ideal
Conociendo el límite estricto de 50 MB, la pregunta más importante es: ¿qué tamaño de imagen deberíamos enviar en un entorno de ingeniería real? Nuestra recomendación es controlar cada imagen en torno a 1.5 MB, tratando de no superar los 5 MB. Esto no es una suposición al azar, se basa en tres razones principales:
Primero, la expansión de base64. Si utilizas el método de URL de datos (data URL) para incrustar imágenes, la codificación base64 aumentará el volumen en aproximadamente un 33%: una imagen original de 40 MB se acerca a los 53 MB después de la codificación, y al añadir la estructura JSON, el cuerpo de la solicitud podría exceder el límite directamente. Cuando se incrustan 16 imágenes mediante base64, este problema se multiplica por 16, por lo que para materiales de gran volumen es obligatorio utilizar el canal de pre-carga file_id.
Segundo, el tiempo de transmisión y decodificación. Después de superar los 5 MB, el tiempo de carga y el tiempo de decodificación del lado del servidor aumentan de forma no lineal, y en caso de fluctuaciones de red, es fácil activar reintentos por tiempo de espera, lo que ralentiza la velocidad general de generación de imágenes. Una imagen de alrededor de 1.5 MB se puede cargar en 1-2 segundos con una conexión de banda ancha doméstica normal, siendo el punto de equilibrio entre estabilidad y calidad.
Tercero, la disminución de los beneficios en la calidad de imagen. gpt-image-2 realiza un preprocesamiento interno al manejar la imagen de entrada; cuando la resolución de entrada es muy superior a la de salida, los píxeles adicionales se desperdician básicamente. Una imagen JPG con un lado largo de 3840 px comprimida a menos de 2 MB no tiene diferencias perceptibles en el efecto de edición en comparación con un PNG sin pérdidas de 40 MB, pero el costo y el tiempo son un orden de magnitud diferentes.
Recomendaciones prácticas para el tamaño de imagen en gpt-image-2
| Situación de la imagen original | Manejo sugerido | Efecto esperado |
|---|---|---|
| < 1.5 MB | Carga directa | Velocidad y estabilidad óptimas |
| 1.5 MB – 5 MB | Carga directa, se sugiere convertir a JPG/WebP | Velocidad aceptable |
| 5 MB – 20 MB | Comprimir a lado largo ≤ 3840 px + calidad 85 | Calidad casi sin pérdidas, tiempo reducido drásticamente |
| 20 MB – 50 MB | Compresión obligatoria, usar carga por file_id |
Evitar exceder el límite por expansión base64 |
| > 50 MB | Excede el límite estricto, compresión obligatoria | De lo contrario, devolverá error |
💡 Sugerencia para escenarios por lotes: Para escenarios de alta concurrencia como recorte de imágenes para comercio electrónico o estilización por lotes, recomendamos realizar una pre-compresión uniforme de "lado largo 3840 px + calidad JPG 85" usando sharp o Pillow antes de la carga. Hemos verificado esto en los casos de clientes corporativos de APIYI (apiyi.com), y este paso reduce el tiempo de extremo a extremo de una sola solicitud de edición en más de un 40%, con cero quejas sobre la calidad de imagen.
Guía rápida de la API gpt-image-2: Ejemplo de código para edición con múltiples imágenes
gpt-image-2 sigue el protocolo estándar de la API de OpenAI. A continuación, te presento un ejemplo básico de edición utilizando varias imágenes de referencia. Si utilizas el servicio proxy de API de APIYI, solo necesitas reemplazar la base_url:
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # Interfaz unificada de APIYI
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Fusiona la imagen del producto con el estilo ciberpunk de neón de la referencia, manteniendo el sujeto del producto intacto",
input_fidelity="high", # Alta fidelidad para conservar detalles, consume más tokens de entrada
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Devuelve la imagen resultante codificada en base64
Puntos clave sobre los parámetros: al configurar input_fidelity en high, la retención de detalles como rostros o logotipos mejora notablemente, aunque el consumo de tokens de entrada aumenta; quality y size son las dos palancas principales que determinan el costo de salida; el parámetro n permite generar hasta 10 imágenes por solicitud. En cuanto a la facturación, gpt-image-2 se cobra por token: $5/M para entrada de texto, $8/M para entrada de imagen ($2/M si hay acierto de caché) y $30/M para salida de imagen. Traducido a una sola imagen de 1024×1024, el nivel "low" cuesta unos $0.006, el "medium" unos $0.05 y el "high" unos $0.21; la salida siempre representa la mayor parte del costo.
Ten en cuenta que los límites de velocidad oficiales varían según el nivel de la cuenta: el Nivel 1 tiene solo 5 imágenes/minuto, el Nivel 4 tiene 150 imágenes/minuto y el Nivel 5 tiene 250 imágenes/minuto. Las cuentas nuevas tienen niveles bajos, por lo que las tareas por lotes pueden alcanzar fácilmente el límite. Al realizar llamadas a través de plataformas de agregación como APIYI (apiyi.com), puedes evitar las restricciones de nivel de cuenta individual, lo cual es ideal para entornos de producción que requieren una alta concurrencia.
Diferencias en las restricciones de carga entre gpt-image-2 y modelos anteriores
Si tu proyecto proviene de gpt-image-1 o DALL·E 2, debes tener en cuenta algunas diferencias generacionales. El mayor cambio ocurrió entre DALL·E 2 y la serie GPT image: la interfaz de edición de DALL·E 2 solo aceptaba una imagen PNG cuadrada de menos de 4 MB; con la serie GPT image, esto se amplió a 16 imágenes, 50 MB y tres formatos. Muchas lógicas de preprocesamiento de "PNG + compresión de 4 MB" escritas en proyectos antiguos pueden simplificarse drásticamente tras la migración.
La actualización de gpt-image-2 respecto a gpt-image-1 se refleja principalmente en la resolución y el costo. gpt-image-1 solo admitía tres salidas fijas (1024×1024, 1536×1024, 1024×1536); gpt-image-2 permite resoluciones personalizadas, soportando hasta una salida 4K con un lado largo de 3840px. En cuanto a precios, la entrada de imagen de gpt-image-2 bajó de $10/M a $8/M, la salida de imagen de $40/M a $30/M, y se añadió un nivel de acierto de caché de $2/M, lo que reduce significativamente los costos en escenarios con imágenes de referencia repetidas.
Comparativa de restricciones de carga entre gpt-image-2 y modelos anteriores
| Comparativa | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Cantidad de imágenes de entrada | 1 imagen | Hasta 16 imágenes | Hasta 16 imágenes |
| Límite de tamaño por imagen | < 4 MB | < 50 MB | < 50 MB |
| Formato de entrada | Solo PNG cuadrado | PNG/WebP/JPG | PNG/WebP/JPG |
| Resolución de salida | Imagen cuadrada fija | 3 tamaños fijos | Personalizado, lado largo 3840px |
| Precio de salida de imagen | Por imagen | $40/M tokens | $30/M tokens (entrada caché $2/M) |
| input_fidelity | No compatible | Compatible | Compatible, mayor fidelidad de detalles |
Al migrar el código, básicamente solo necesitas cambiar el parámetro model, pero se recomienda actualizar simultáneamente la validación de resolución y la estrategia de compresión según la tabla de restricciones de este artículo. Si deseas verificar el efecto de la migración antes de modificar el código de producción, puedes realizar llamadas con el mismo conjunto de materiales a ambos modelos en APIYI (apiyi.com) para comparar visualmente la calidad de edición y la diferencia real en la facturación.
FAQ sobre problemas comunes de carga de imágenes en gpt-image-2
P1: ¿Cuál es el tamaño máximo permitido para una sola imagen en gpt-image-2?
El límite estricto es de 50 MB y se admiten formatos PNG, WebP y JPG. Esta restricción se encuentra en la guía de uso de generación de imágenes de OpenAI, no en la tabla de parámetros de referencia de images/edit, por lo que es normal no encontrarla si solo revisas la página de referencia. En la práctica, recomendamos mantener el tamaño entre 1.5 y 5 MB para obtener la mejor experiencia.
P2: ¿Cómo funciona el límite de 16 imágenes?
El parámetro images acepta hasta 16 objetos de imagen, donde cada uno se especifica mediante image_url o file_id. El Modelo de Lenguaje Grande utilizará múltiples imágenes como referencia conjunta, lo cual es ideal para escenarios de edición combinada como "imagen de producto + imagen de estilo + referencia de composición". Ten en cuenta que 16 es el límite de entrada, mientras que la cantidad de salida está controlada por el parámetro n, con un máximo de 10 imágenes.
P3: ¿Cuál es la causa habitual del error "invalid mask" en la máscara?
En el 90% de los casos, se debe a problemas con el canal alfa. La máscara debe tener el mismo formato y dimensiones que la imagen editada, y debe incluir un canal alfa; como el formato JPG no admite canales alfa, la máscara debe ser obligatoriamente un PNG. Las áreas transparentes representan las zonas donde se "permite el redibujado", mientras que las áreas opacas permanecen intactas.
P4: ¿Cómo elegir entre la carga en base64 y la carga mediante file_id?
Para imágenes pequeñas (< 5 MB) o solicitudes únicas, usar una URL de datos en base64 es lo más sencillo. Para imágenes grandes o recursos que necesiten reutilizarse varias veces, es mejor usar la API de archivos para realizar una carga previa y obtener un file_id. Esto evita la expansión del 33% en el tamaño que genera el base64 y permite la reutilización entre solicitudes. Si no estás seguro, puedes probar ambos métodos en el panel de control de APIYI (apiyi.com) y comparar los tiempos de respuesta reales antes de decidir tu estrategia.
Resumen: Tres cifras clave sobre las restricciones de carga en gpt-image-2
Volviendo a la pregunta inicial, las restricciones de carga de la API de edición de imágenes gpt-image-2 se pueden resumir en tres números: 16 imágenes (límite de entrada única, indicado en la referencia), 50 MB (límite de tamaño por imagen, indicado en la guía de uso) y 1.5 MB (el tamaño ideal para la práctica de ingeniería). La documentación separa la cantidad y el tamaño en dos páginas distintas, lo que suele causar la confusión de "solo ver el límite de 16 imágenes".
Nuestras recomendaciones de implementación son sencillas: antes de cargar, comprime uniformemente las imágenes a un lado largo de máximo 3840px con una calidad JPG de alrededor del 85%; utiliza siempre PNG con canal alfa para las máscaras; y para los recursos pesados, utiliza el canal file_id. Si conviertes estos tres pasos en un preprocesamiento fijo antes de cada solicitud, podrás evitar prácticamente todos los errores relacionados con la carga.
Si necesitas invocar gpt-image-2 de forma estable desde China, o si deseas elevar tus límites de tasa a un nivel de producción, puedes conectarte a través de la interfaz unificada de APIYI (apiyi.com). Esta es compatible con la sintaxis nativa del SDK de OpenAI; solo necesitas cambiar una línea en base_url para realizar la migración.
Referencias: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
Autor: Equipo de APIYI
Especialistas en agregación de API de Modelos de Lenguaje Grande de IA y mejores prácticas. Para más evaluaciones de modelos y guías de integración, visita APIYI en apiyi.com.
