Parámetros de la API de GPT Image 2: tamaño, resolución, relación de aspecto y calidad
Los parámetros de la API de GPT Image 2 que definen la imagen: modelo, tamaño y resolución, relaciones de aspecto, límites 4K, calidad, formatos y errores.
Leer en MarkdownLa API de GPT Image 2 recibe el nombre del modelo en model, las dimensiones de salida en size como píxeles WIDTHxHEIGHT y la calidad en quality (low, medium, high o auto). No existe un campo resolution ni aspect_ratio. Para obtener una imagen 16:9 en 4K envías "size": "3840x2160". Los tamaños deben usar múltiplos de 16, mantener ambos lados en 3840 píxeles o menos, quedar entre 1:3 y 3:1, y sumar entre 655.360 y 8.294.400 píxeles.
Esta guía recorre cada parámetro que cambia la imagen, con el valor exacto que hay que enviar y el error que devuelve un valor incorrecto. Todos los errores de abajo se comprobaron contra la API en producción.
¿Cuál es el nombre del modelo GPT Image 2 en la API?
Usa gpt-image-2 o gpt-image-2-official. Ambos son el mismo modelo con los mismos campos; gpt-image-2 cobra un precio fijo por imagen entregada y gpt-image-2-official factura los tokens que reporta cada render.
Los nombres de los titulares no sirven como IDs de modelo. gpt-image-2.0, GPT Image 2 o chatgpt-images-2 devuelven HTTP 400 con el código de error 20002.
¿Cómo se configuran la resolución y la relación de aspecto?
Con size, en píxeles. Elige la relación de aspecto y el presupuesto de píxeles que quieres y envía el ancho y el alto resultantes:
| Relación de aspecto | Unos 1K | Unos 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:2 | 1248x832 | 2496x1664 | 3504x2336 |
| 2:3 | 832x1248 | 1664x2496 | 2336x3504 |
| 4:3 | 1152x864 | 2304x1728 | 3264x2448 |
| 3:4 | 864x1152 | 1728x2304 | 2448x3264 |
| 16:9 | 1280x720 | 2560x1440 | 3840x2160 |
| 9:16 | 720x1280 | 1440x2560 | 2160x3840 |
| 21:9 | 1456x624 | 3024x1296 | 3808x1632 |
| 3:1 | 1728x576 | 3504x1168 | 3840x1280 |
Son las mismas conversiones que usa el Playground cuando eliges una relación y un preajuste de 1K, 2K o 4K. El 4K cuadrado se queda en 2880x2880 porque un cuadrado de 3840 píxeles superaría el límite total de píxeles.
size: "auto" deja las dimensiones en manos del modelo. Es el valor por defecto y resulta cómodo, pero fija un tamaño explícito cuando las salidas deban encajar en un diseño o coincidir entre sí.
OpenAI describe la salida por encima de 2560×1440 como experimental. Aquí se acepta dentro de los límites, pero un lienzo más grande no garantiza más detalle.
¿Qué valores de size se rechazan?
| Valor enviado | Por qué falla | Respuesta |
|---|---|---|
"size": "16:9" | Una relación no es un tamaño | 400 20001, el mensaje nombra size |
"size": "4096x2304" | Lado mayor de 3840 | 400 20001, el mensaje nombra size |
"size": "1000x1000" | No es múltiplo de 16 | 400 20001, el mensaje nombra size |
"size": "3840x1024" | Más ancho que 3:1 | 400 20001, el mensaje nombra size |
"resolution": "4k" | Campo desconocido | 400 20001, sin campo nombrado |
"aspect_ratio": "16:9" | Campo desconocido | 400 20001, sin campo nombrado |
Fíjate en las dos últimas filas. Un campo desconocido se rechaza, pero el error no lo nombra. Si recibes 20001 con el mensaje general «Check the parameters against the API documentation», busca un campo que la API no acepte, como resolution, aspect_ratio o response_format.
¿Qué calidad conviene elegir?
quality acepta low, medium, high y auto. Los niveles más altos tardan más y conservan más detalle fino. xhigh y max son exclusivos de GPT Image 2.5; enviarlos a GPT Image 2 devuelve 20001 con un mensaje que nombra quality.
Una rutina práctica: haz borradores en low mientras la composición sigue cambiando, revisa texturas y texto pequeño en medium y produce las versiones finales en high. En gpt-image-2 el precio es el mismo en todos los niveles. En gpt-image-2-official los niveles más altos reportan más tokens de salida, así que cuestan más. La guía de precios muestra las cifras.
auto deja que el modelo elija el nivel. Fija un valor explícito cuando compares ejecuciones; de lo contrario, dos solicitudes "idénticas" pueden renderizarse en niveles distintos.
¿Qué controla el formato y el fondo?
output_format:png(por defecto) ojpeg. No se ofrece salida WebP;webpdevuelve20001con un mensaje que nombraoutput_format.output_compression: de 0 a 100, solo conjpeg.background:auto,opaqueotransparent. La transparencia requierepng;transparentconjpegdevuelve20001con un mensaje que nombrabackground.n: de 1 a 10 imágenes por solicitud. Se te cobran las imágenes entregadas.moderation:autoolow.
¿Cómo se pasan las imágenes de referencia y las máscaras?
Como URL, nunca como archivos ni base64. images admite de 1 a 16 objetos con la forma {"image_url": "https://..."}, y enviarlo convierte la solicitud en una edición. mask admite un objeto con la misma forma: un PNG del tamaño de la primera imagen de referencia, donde el área transparente marca lo que se debe cambiar. La referencia enumera los límites de los archivos.
Preguntas frecuentes
¿GPT Image 2 admite 4K?
Sí, dentro de los límites anteriores. 3840x2160 para 16:9 y 2160x3840 para 9:16 son los encuadres más grandes, y 2880x2880 es el cuadrado más grande.
¿Puedo enviar una relación de aspecto en lugar de píxeles?
A la API, no. Convierte primero la relación en un tamaño WIDTHxHEIGHT con la tabla de arriba o con el Playground, que muestra el tamaño exacto antes de enviar.
¿Cuáles son el tamaño y la calidad por defecto?
Ambos son auto por defecto, lo que deja la elección al modelo. Envía valores explícitos cuando necesites una salida predecible.
Envía píxeles, fija la calidad y lee el mensaje de error
Casi todos los problemas de parámetros son una de tres cosas: una relación enviada como tamaño, un campo que la API no acepta o un valor fuera de los límites. En el primer y el tercer caso, el mensaje de error nombra el campo; un mensaje general que no nombra ningún campo señala el segundo. Ten esta página a mano junto a la referencia de la API de GPT Image 2 mientras integras.
