text-to-image

Create image from text - GPT Image 2

Generate images from a text prompt using OpenAI's GPT Image 2.5 model.

Key Features:

  • Strong instruction following on long, detailed prompts
  • Reliable text rendering inside the image
  • Explicit resolution tier, aspect ratio, format and compression control
  • Selectable quality tier (low / medium / high)

Best for:

  • Marketing and editorial images that must contain legible text
  • Prompts with many precise constraints
  • Cases where transparency or an exact output format is required

Output: one image per num_images (up to 10), at the size selected by resolution + aspect_ratio, delivered as CDN URLs in the task's generated array.

Credits: the quality tier sets the price per image and resolution multiplies it (1k x1, 2k x2, 4k x3). Every image in num_images is billed.

The request is processed asynchronously: the endpoint returns a task id immediately. Retrieve the result by polling the task endpoint or by providing an optional webhook_url.

post/v1/ai/text-to-image/gpt-image-2-5

Request

  • Base URL: https://api.magnific.com
  • URL: https://api.magnific.com/v1/ai/text-to-image/gpt-image-2-5
  • Auth: API key in header x-magnific-api-key

Request body

promptstring required

Text description of the image you want to generate.

Tips:

  • GPT Image 2.5 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"
webhook_urlstring 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.

num_imagesinteger

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

variant'flare' | 'sunburst'

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
resolution'1k' | '2k' | '4k'

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.

aspect_ratio'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'

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.

quality'low' | 'medium' | 'high' | 'xhigh' | 'max'

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.

output_format'png' | 'jpeg' | 'webp'

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.

background'transparent' | 'opaque' | 'auto'

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.

output_compressioninteger

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

moderation'auto' | 'low'

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.

Example request

{
  "prompt": "A vintage travel poster for Mars, bold sans-serif title, muted orange palette",
  "webhook_url": "https://www.example.com/webhook",
  "num_images": 1,
  "variant": "flare",
  "resolution": "1k",
  "aspect_ratio": "auto",
  "quality": "medium",
  "output_format": "png",
  "background": "auto",
  "output_compression": 80,
  "moderation": "auto"
}

Response

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

Example response

{
  "data": {
    "generated": [
      "https://openapi-generator.tech",
      "https://openapi-generator.tech"
    ],
    "task_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "status": "CREATED"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.