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 description of the image you want to generate.

Tips:

  • GPT Image 2 follows long, detailed instructions well
  • Text to render inside the image can be given verbatim, in quotes
  • Precise constraints (colours, layout, camera) are respected closely

Examples:

  • Simple: "A vintage travel poster for Mars"
  • Detailed: "A vintage travel poster for Mars, bold sans-serif title reading VISIT MARS, muted orange palette, grain"
Required string length: 1 - 32000
Example:

"A vintage travel poster for Mars, bold sans-serif title, muted orange palette"

​
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

​
resolution
enum<string>
default:1k

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

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:square_1_1

Image size with the aspect ratio. The aspect ratio is the proportional relationship between an image's width and height, expressed as *_width_height (e.g., square_1_1, widescreen_16_9). It is calculated by dividing the width by the height. If not present, the default is square_1_1.

Available options:
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:

"square_1_1"

​
quality
enum<string>
default:high

Render quality tier. Higher tiers spend more provider compute and cost more credits; lower tiers are faster and cheaper.

  • low: fastest and cheapest, for drafts and iteration
  • medium: balanced
  • high: maximum detail and prompt adherence (default)
Available options:
low,
medium,
high
Example:

"high"

​
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.

Available options:
png,
jpeg,
webp
Example:

"png"

​
background
enum<string>

How the image background is produced.

  • opaque: always render a filled background
  • auto: let the model decide, which may return a transparent background

Transparency is only preserved by formats that support an alpha channel (png, webp). When omitted, the provider default applies.

Available options:
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 process has started.

​
data
object
required
Example: