OpenAI Image Generation - Output Sizes and Resizing

Tools can generate an image using the OpenAI image API and, when needed, create an exact local output size without replacing the untouched provider result.

The image generator is available at /admin/openai/images.

Provider size and final output size

The generator separates two concepts:

• Provider size is the resolution requested from OpenAI.
• Final output size is the exact resolution Tools should return after optional local processing.

When the selected model can generate the requested final size natively, Tools uses that size directly and no local resize is performed.

When the requested final size is not a valid native provider size, Tools selects a suitable provider resolution and creates the exact final derivative locally.

Final output presets

The UI includes common presets such as:

• 640x480 - 4:3
• 800x600 - 4:3
• 1024x768 - 4:3
• 1280x720 - 16:9
• 1920x1080 - Full HD
• 2560x1440 - QHD
• 3840x2160 - 4K
• 720x1280 - 9:16
• 1080x1920 - 9:16
• 1024x1024 - square
• 2048x2048 - square
• 3000x3000 - Spotify artwork
• Custom width and height

Custom dimensions are accepted up to 4096 pixels per edge.

GPT Image 2 native sizing

GPT Image 2 can use flexible native sizes when the requested dimensions satisfy the provider constraints used by Tools:

• maximum edge: 3840 pixels
• both edges divisible by 16
• maximum aspect ratio: 3:1
• total pixel count between 655,360 and 8,294,400

If the target satisfies those constraints, Tools requests it directly from OpenAI.

If it does not, Tools calculates a suitable native source size and performs only the final local resize.

Quality and upscaling

Tools avoids destructive raster upscaling where possible. Raster enlargement cannot recreate source detail that does not exist.

For generated output, Tools prefers a provider image that is at least as large as the requested target so the local step can downscale instead of enlarge. Requests that would require a larger unnecessary upscale are rejected rather than silently degrading the output.

The exception is Spotify artwork at 3000x3000. GPT Image 2 cannot produce 3000x3000 within its total-pixel limit, so Tools uses a 2880x2880 provider image and creates the required 3000x3000 derivative. The untouched 2880x2880 original remains stored alongside the derivative.

Local resize implementation

When a derivative is required, Tools uses:

1. ImageMagick with Lanczos resampling when Imagick is available.
2. GD resampling as a fallback.

The derivative is written as PNG to avoid adding JPEG or WebP generation loss during the local resize step.

If a request requires local resizing and neither Imagick nor GD is available, validation fails before the image job is started.

Reference images

Uploaded reference images can optionally be resized before they are sent to OpenAI.

Reference processing is stricter than generated-output processing:

• large reference images may be downscaled or cropped to the selected target
• smaller reference images are never enlarged locally
• if a reference is smaller than the requested target, the original reference is sent unchanged
• the original upload is retained in provenance when a resized derivative is used for the provider request

This prevents Tools from degrading a reference image merely to force it into a larger raster size.

Original and derived images

When a final derivative is created, Tools keeps both versions:

• the untouched OpenAI result
• the exact resized output

The image generator UI exposes both links. The resized output is stored as a generated-image source variant instead of replacing the original generated-image record.

API fields

The image-generation endpoints continue to accept the normal provider size and quality fields and additionally support final-output planning fields used by the Tools image layer:

• target_size - exact WIDTHxHEIGHT output, or custom
• target_width - custom width
• target_height - custom height
• resize_references - resize eligible uploaded references before the provider request

The response can contain both image_url for the final result and original_image_url when a derivative was created.

Related implementation

This functionality was introduced through Tools API issue #247 and pull request #250.