--- title: "Edit images from text - GPT Image 2" method: POST path: "/v1/ai/text-to-image/gpt-image-2-5-edit" tags: ["text-to-image"] --- # Edit images from text - GPT Image 2 `POST /v1/ai/text-to-image/gpt-image-2-5-edit` ## Request - Base URL: `https://api.magnific.com` - URL: `https://api.magnific.com/v1/ai/text-to-image/gpt-image-2-5-edit` - Auth: API key in header `x-magnific-api-key` Edit or recompose one or more input images from a text prompt using OpenAI's GPT Image 2.5 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`. ## Request body - Ttigi25EditRequestContent - `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" - `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. - `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. - `num_images` integer: 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_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`. - `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. ## Response `200` OK - The request has succeeded and the GPT Image 2.5 Edit process has started. - GetStyleTransferTaskStatus200Response - `data` TaskDetail, required - `task_id` string, uuid, required: Task identifier - `status` 'CREATED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED', required: Task status - `generated` string[], required ## Other responses - `400`: Bad Request - The server could not understand the request due to invalid syntax. - `401`: Unauthorized - The client must authenticate itself to get the requested response. - `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle. - `503`: Service Unavailable --- [API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)