text-to-image

Edit images from text - GPT Image 2

Edit or recompose one or more input images from a text prompt using OpenAI's GPT Image 2 model.

Key Features:

  • Accepts 1-16 input images, used together as the visual context
  • Restyle a single image, or compose a new one from several
  • Same output controls as text-to-image (resolution, aspect ratio, format, compression, quality)

Best for:

  • Product and scene variations from an existing shot
  • Combining a subject, a background and a style reference in one call
  • Adding or correcting text on an existing image

Output: one edited image per num_images (up to 10), delivered as CDN URLs in the task's generated array. The input images are never modified.

Credits: editing sends your images to the model and their input tokens dominate the cost, so it is priced differently from generation: flat units per output image by quality (low x1, medium x4, high x6), with resolution not affecting the price.

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-edit

Request

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

Request body

promptstring 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"
reference_imagesstring[] required

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

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

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.

resolution'1k' | '2k' | '4k'

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.

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

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.

quality'low' | 'medium' | '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)
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.

background'opaque' | 'auto'

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.

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": "Put the product on a marble surface",
  "reference_images": [
    "https://example.com/product.jpg"
  ],
  "webhook_url": "https://www.example.com/webhook",
  "num_images": 1,
  "resolution": "1k",
  "aspect_ratio": "square_1_1",
  "quality": "high",
  "output_format": "png",
  "background": "auto",
  "output_compression": 80,
  "moderation": "auto"
}

Response

OK - The request has succeeded and the GPT Image 2 Edit 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.