Skip to main content
POST

Authorizations

​
x-magnific-api-key
string
header
required

Your Magnific API key. Required for authentication. Learn how to obtain an API key

Body

application/json
​
prompt
string
required

Text instruction describing the edit to apply to the reference images.

Tips:

  • Say what should change, not what the image already contains
  • Several references are used together as one visual context
  • Text inside the image can be corrected or replaced verbatim

Examples:

  • Simple: "Put the product on a marble surface"
  • Detailed: "Replace the background with a sunlit studio, keep the product and its shadow, change the label text to ORGANIC"
Required string length: 1 - 32000
Example:

"Put the product on a marble surface"

​
reference_images
string[]
required

The images to edit, in order. GPT Image 2.5 uses them together as the visual context for the prompt: it can restyle one image, or compose a new image from several.

With the default aspect_ratio: auto, the output keeps the aspect ratio of these images.

Each image may be up to 20 MiB, and one request may carry up to 64 MiB of images in total.

Required array length: 1 - 16 elements

Image URL (must be publicly reachable over HTTPS), a base64-encoded image, or an upload id returned by the uploads API. Supported formats: jpg, jpeg, png, webp.

​
webhook_url
string<uri>

Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

Example:

"https://www.example.com/webhook"

​
num_images
integer
default:1

How many images to generate for this prompt. Each image is billed separately.

Required range: 1 <= x <= 10
Example:

1

​
variant
enum<string>
default:flare

Which model of the GPT Image 2.5 line renders the request. Both share every other parameter, the quality scale and the price.

  • flare: optimised for latency (default)
  • sunburst: optimised for editing precision
Available options:
flare,
sunburst
Example:

"flare"

​
resolution
enum<string>
default:1k

Resolution tier of the generated image. Combined with aspect_ratio it selects the exact pixel size.

With aspect_ratio: auto, only 1k leaves the size to the model; 2k and 4k render a square at that tier.

Credits: the tier multiplies the price set by quality — 1k x1, 2k x2, 4k x3. On the edit endpoint it does not affect the price.

Available options:
1k,
2k,
4k
Example:

"1k"

​
aspect_ratio
enum<string>
default:auto

Shape of the generated image, expressed as *_width_height (e.g. square_1_1, widescreen_16_9).

auto (the default) lets the model choose the shape. When the request carries reference_images, the output keeps their aspect ratio, including ratios that are not in this list — which is what makes auto the right choice for editing a picture whose proportions must be preserved.

Available options:
auto,
square_1_1,
classic_4_3,
traditional_3_4,
widescreen_16_9,
social_story_9_16,
film_horizontal_21_9,
standard_3_2,
portrait_2_3,
horizontal_2_1,
banner_3_1
Example:

"auto"

​
quality
enum<string>
default:medium

Render quality tier. Higher tiers spend more provider compute; lower tiers are faster.

  • low: fastest, for drafts and iteration
  • medium: balanced (default)
  • high: high detail and prompt adherence
  • xhigh, max: the extended tiers of GPT Image 2.5, for the most demanding renders

Credits: low, medium and high are billed on their own tier. xhigh and max are currently billed at the high price.

Available options:
low,
medium,
high,
xhigh,
max
Example:

"medium"

​
output_format
enum<string>
default:png

The file format of the generated image.

  • png: lossless, supports transparency. Best for logos, text and sharp edges
  • jpeg: compressed, no transparency. Smallest files for photographic content
  • webp: compressed, supports transparency

output_compression only applies to jpeg and webp. A jpeg output cannot carry an alpha channel, so it is rejected when background is transparent.

Available options:
png,
jpeg,
webp
Example:

"png"

​
background
enum<string>

How the image background is produced.

  • transparent: render without a background. Requires an output_format with an alpha channel (png or webp)
  • opaque: always render a filled background
  • auto: let the model decide

When omitted, the provider default applies.

Available options:
transparent,
opaque,
auto
Example:

"auto"

​
output_compression
integer

Compression level for the generated image, where 100 is the least compressed. Only applies when output_format is jpeg or webp; ignored for png.

Required range: 0 <= x <= 100
Example:

80

​
moderation
enum<string>
default:auto

Strictness of the model provider's own content filter.

  • auto: the provider's standard filtering (default)
  • low: less restrictive filtering

This is the model provider's filter and is applied in addition to Freepik's platform moderation, which cannot be disabled.

Available options:
auto,
low
Example:

"auto"

Response

OK - The request has succeeded and the GPT Image 2.5 Edit process has started.

​
data
object
required
Example: