GPT Image 2.5 Flare Image Edit API

openai/gpt-image-2.5-flare/edit

image_urls · mask_url

GPT Image 2.5 Flare Image Edit turns reference images and text prompts into new visuals, supporting 1–16 references and local repainting. It makes targeted changes quickly while preserving the original subject’s appearance and composition.

Get API Key

Input

PromptRequired962/32000

Image UrlsRequired

Drag and drop files, paste from clipboard, or provide a URL. Provide 1–16 public HTTP(S) image URLs without embedded credentials, in prompt order.

2/16 files added

SizeOptional

ResolutionOptional

Output FormatOptional

QualityOptional

BackgroundOptional

Mask UrlOptional

Drag and drop files, paste from clipboard, or provide a URL. Optional single HTTP(S) mask URL without embedded credentials; requires reference images.

OutputReady

Estimated cost: low / 1K · 1.31 credits · $0.00655

Billed per image, based on the selected quality and resolution. 1 credit = $0.005.

Continue using

GPT Image 2.5 Flare Text to Image GPT Image 2.5 Sunburst Image Edit Nano Banana 2.1 Edit

Examples

Edit image 1 using the supplied mask. Change only the visible sky through the window glass from dull overcast grey to a clear dark blue night with many fine stars and a faint natural Milky Way band. Preserve the wooden window frame and crossbars, brass telescope, stool, cable, interior lamp, wall texture and exact camera composition. Keep the interior lighting and all object positions unchanged; the night sky should fit naturally behind the existing window panes. No added planets, moon, figures, text, labels or surreal light beams. No brands, logos, products for sale, advertisements, promotional graphics, watermark, split screen or comparison panels.

Use image 1 as the only reference. Isolate the exact handmade terracotta dragon from its workbench onto a genuinely transparent background. Preserve the dragon's rusty-red clay body, green glazed eyes, closed-mouth friendly smile, exactly four feet, both wings, curled tail, tiny belly crack, fingerprint impressions and chipped right wing tip. Keep its original pose and framing with the whole silhouette visible. Remove only the wooden tabletop and all background tools; do not restyle, repaint, smooth or redesign the sculpture. Retain natural soft light on the subject. No replacement floor, solid backdrop, checkerboard or shadow rectangle. No brands, logos, products for sale, advertisements, promotional graphics, watermark, split screen or comparison panels.

REST API

Quick Start

This flow submits one valid GPT Image 2.5 Flare Image Edit request, captures its task_id, and reads image URLs after the asynchronous task ends.

Connect to the Vidgo API

Create an API key, keep it on the server, and send it as Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one image task

Send the current model ID, prompt, and ordered image URLs to the unified submit endpoint. The example keeps only first-call fields.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai/gpt-image-2.5-flare/edit",
  "input": {
    "prompt": "Replace the sky with a starry night sky.",
    "image_urls": [
      "https://example.com/image.png"
    ],
    "size": "1:1",
    "resolution": "1K",
    "output_format": "png",
    "quality": "high",
    "background": "auto"
  }
}'

Wait for the image result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-example",
    "status": "not_started",
    "created_time": "2026-09-25T08:00:00"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-example",
    "status": "finished",
    "created_time": "2026-09-25T08:00:00",
    "files": [
      {
        "file_url": "https://example.com/result.png",
        "file_type": "image"
      }
    ]
  }
}

Complete runnable polling example

Expand for the same payload end to end, including business-code, missing-task-ID, failed-state, unexpected-state, and network-error handling.

Complete runnable polling example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "openai/gpt-image-2.5-flare/edit",
  "input": {
    "prompt": "Replace the sky with a starry night sky.",
    "image_urls": [
      "https://example.com/image.png"
    ],
    "size": "1:1",
    "resolution": "1K",
    "output_format": "png",
    "quality": "high",
    "background": "auto"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	Non-blank text, up to 32,000 characters.
input.image_urls	string[] \| string	Yes	–	Provide 1–16 public HTTP(S) image URLs without embedded credentials, in prompt order.
input.size	string	No	1:1	Default 1:1. Ratios: auto, 1:1, 2:3, 3:2, 4:3, 3:4, 4:5, 5:4, 16:9, 9:16, 21:9. auto requires 1K. Custom WIDTHxHEIGHT requires 2K/4K, positive multiples of 16, maximum edge 3840, ratio at most 3:1 and 655360–8294400 pixels; a 3840 edge requires 4K.
input.resolution	string	No	1K	1K, 2K or 4K. Default 1K. 1K, 2K, 4K.
input.output_format	string	No	png	png, jpeg or webp. Default png. png, jpeg, webp.
input.quality	string	No	high	low, medium, high, xhigh or max. Default high. Price depends on quality and resolution. low, medium, high, xhigh, max.
input.background	string	No	auto	auto, transparent or opaque. Default auto. transparent requires png or webp. auto, transparent, opaque.
input.mask_url	string	No	–	Optional single HTTP(S) mask URL without embedded credentials; requires reference images.

Response Fields

The submit response identifies the task. The status response supplies image files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-image URL.
data.files[].file_type	string	Image results are identified as image.
data.files[].watermark_url	string \| null	Optional watermarked-file URL when present.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Image generation is in progress; continue polling.
finished
Successful terminal state; validate files and read image URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

AuthenticationKeep a valid VIDGO_API_KEY on the server and send requests with Bearer authentication.
Validation400 indicates an invalid model ID, field, enum, length, or image count.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesRead image URLs from files after finished, or error_message after failed. Both states end polling.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Model	openai/gpt-image-2.5-flare/edit	Edit reference images using text instructions.
size	auto / 1:1 / 2:3 / 3:2 / 4:3 / 3:4 / 4:5 / 5:4 / 16:9 / 9:16 / 21:9 / WIDTHxHEIGHT	Default: 1:1

GPT Image 2.5 Flare Image Edit API documentation

GPT Image 2.5 Flare Image Edit

GPT Image 2.5 Flare Image Edit is OpenAI’s image editing model for quick changes and frequent iteration. It accepts 1–16 reference images and an optional mask, using natural language instructions for local replacements, style transfer and combining features across images. Fast responses and preservation of subject appearance and core composition help creators efficiently change product backgrounds, retouch portraits and assemble visual assets.

Why Choose GPT Image 2.5 Flare Image Edit?

Up to 16 references for image blendingProvide 1–16 public image URLs to extract and combine character traits, product details and artistic styles from different references in a single generation workflow.
Preserve subject identity and compositionWhen changing scenes or materials, the model locks facial features, product outlines and core spatial composition to prevent excessive distortion or loss of identity.
Low latency for interactive editingFlare’s fast inference substantially reduces generation latency, supporting successive rounds of gradual edits, concept testing and quick release reviews.
Precise masks for targeted local editsUse an optional single binary mask through mask_url to make targeted changes with pixel-level precision while leaving unselected regions completely unaffected.
Flexible sizes, formats and backgroundsSupport for 1K–4K resolution, transparent output and custom sizes makes edited images ready for print, product detail pages and digital compositing.

Parameters

Parameter	Requirement	Description
prompt	Required	Non-blank text, up to 32,000 characters.
image_urls	Required	Provide 1–16 public HTTP(S) image URLs without embedded credentials, in prompt order.
size	Optional	Default 1:1. Ratios: auto, 1:1, 2:3, 3:2, 4:3, 3:4, 4:5, 5:4, 16:9, 9:16, 21:9. auto requires 1K. Custom WIDTHxHEIGHT requires 2K/4K, positive multiples of 16, maximum edge 3840, ratio at most 3:1 and 655360–8294400 pixels; a 3840 edge requires 4K. Default`1:1`
resolution	Optional	1K, 2K or 4K. Default 1K. Default`1K2K4K`
output_format	Optional	png, jpeg or webp. Default png. Default`pngjpegwebp`
quality	Optional	low, medium, high, xhigh or max. Default high. Price depends on quality and resolution. Default`highlowmediumxhighmax`
background	Optional	auto, transparent or opaque. Default auto. transparent requires png or webp. Default`autotransparentopaque`
mask_url	Optional	Optional single HTTP(S) mask URL without embedded credentials; requires reference images.

How to Use

Prepare references and an optional maskPrepare 1–16 publicly accessible HTTP(S) image URLs. For targeted local edits, you can also provide a single-channel mask image.
Write your editing instructionsUse prompt to specify elements to add, replace or remove. State which parts of the subject should remain and describe the desired lighting and color.
Set the aspect ratio and qualityChoose 1:1 or an aspect ratio matching the original image, then select 1K–4K resolution and a quality level from low to max for your intended output.
Submit an asynchronous editing taskSend an editing request containing image_urls and prompt to the API. You will immediately receive a task_id for polling progress.
Poll the status and retrieve the editQuery the task using task_id. Once its status becomes finished, read the response and download the high-quality edited image.

Usage and Pricing

Each request generates one image. Pricing depends on quality and resolution, starting at 1.31 credits per image. The API default high / 1K setting costs 11.78 credits per image ($0.05890). 1 credit = $0.005. See the table below for all rates.

Usage and Pricing
Quality	Resolution	Cost per image
low	1K	1.31 credits $0.00655
	2K	2.65 credits $0.01325
	4K	2.47 credits $0.01235
medium	1K	2.95 credits $0.01475
	2K	5.99 credits $0.02995
	4K	5.81 credits $0.02905
high	1KAPI Default	11.78 credits $0.05890
	2K	23.94 credits $0.11970
	4K	22.39 credits $0.11195
xhigh	1K	20.93 credits $0.10465
	2K	42.55 credits $0.21275
	4K	39.78 credits $0.19890
max	1K	47.11 credits $0.23555
	2K	95.74 credits $0.47870
	4K	89.51 credits $0.44755

Best Use Cases

Product backgrounds and model outfit changesUpload a product or model image and replace studio backgrounds, environmental lighting or outfits while preserving the product’s appearance and texture.
Consistent characters across scenesUse existing character artwork as a reference and guide the model to preserve the same face and hairstyle across poses, outfits and expansive scenes.
Local poster cleanup and text repaintingUse precise masks to repaint unwanted objects, specific slogans or outdated backgrounds and quickly refresh existing visual assets.
Concept art blending and style transferCombine line drawings, color references and composition sketches in a single request, merging their visual strengths while keeping the image coherent.

Pro Tips

Map references by order: refer to "the first image", "the second image" or distinctive subject features in prompt. The model aligns features with the order of image_urls.
Use a mask for targeted editing: mask_url should point to a black-and-white binary or grayscale image. White marks regions to regenerate; black marks original content to preserve exactly.
Iterate in stages: use each satisfactory output as the reference for the next round. Separate background changes, lighting adjustments and added details for more controllable results.
Export with a transparent background: set background to transparent and choose png to isolate the edited subject and export an asset ready for compositing.

Notes

image_urls is a required array of 1–16 publicly accessible HTTP(S) image URLs. URLs must not contain usernames or passwords.
mask_url is an optional single mask image and must be used with image_urls. It cannot work independently without a reference image.
prompt is required and supports up to 32,000 characters. Clearly describe both the intended changes and the elements to preserve.
Editing uses the same pricing as text-to-image generation. Each submission is billed in credits according to quality and resolution.

Related Models

Nano Banana 2.1 Text to ImageNano Banana 2.1 Text to Image turns text prompts into 1K–4K images with text layout rendering and panoramic compositions. It preserves perspective and lighting while eliminating tiling artifacts in panoramic aspect ratios.

Nano Banana 2.1 EditNano Banana 2.1 Text to Image turns text prompts into 1K–4K images with text layout rendering and panoramic compositions. It preserves perspective and lighting while eliminating tiling artifacts in panoramic aspect ratios.

Qwen Image 2.1 Text to ImageQwen Image 2.1 Text to Image turns text into native 1K and 2K images with RGBA transparency and Chinese-English typography. It preserves lighting, composition, and aspect ratios while delivering clean transparent layers that need no background removal.

Qwen Image 2.1 EditQwen Image 2.1 Text to Image turns text into native 1K and 2K images with RGBA transparency and Chinese-English typography. It preserves lighting, composition, and aspect ratios while delivering clean transparent layers that need no background removal.

Seedream 5.0 Flash Text to Image preview

Seedream 5.0 Flash Text to ImageSeedream 5.0 Flash Text to Image turns text prompts into high-definition 1K to 2K images, with Chinese and English text layout and 8 aspect ratios. It closely follows complex prompts while providing fine control over lighting and composition.

Seedream 5.0 Flash Image EditSeedream 5.0 Flash Text to Image turns text prompts into high-definition 1K to 2K images, with Chinese and English text layout and 8 aspect ratios. It closely follows complex prompts while providing fine control over lighting and composition.

GPT Image 2.5 Flare Text to Image preview

GPT Image 2.5 Flare Text to ImageGPT Image 2.5 Flare Text to Image turns text prompts into detailed 1K–4K images, with transparent backgrounds and low latency. It combines fast responses with natural lighting while avoiding structural distortion in large images.

GPT Image 2.5 Sunburst Text to Image preview

GPT Image 2.5 Sunburst Text to ImageGPT Image 2.5 Sunburst Text to Image turns complex prompts into visuals up to 4K, with fine material textures and realistic lighting. It accurately reproduces depth and fine detail while maintaining precise composition under long, detailed instructions.

GPT Image 2.5 Sunburst Image Edit preview

GPT Image 2.5 Sunburst Image EditGPT Image 2.5 Sunburst Text to Image turns complex prompts into visuals up to 4K, with fine material textures and realistic lighting. It accurately reproduces depth and fine detail while maintaining precise composition under long, detailed instructions.

Grok Imagine Image 2.0 Text to Image preview

Grok Imagine Image 2.0 Text to ImageGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Grok Imagine Image 2.0 EditGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Qwen Image 3.0 Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Text-to-Image preview

Qwen Image 3.0 Pro Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Seedream 5.0 Pro Text-to-ImageThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

GPT Image 2.5 Flare Image Edit API FAQ

What is GPT Image 2.5 Flare Image Edit API?

GPT Image 2.5 Flare Image Edit is OpenAI’s high-performance model for image editing and blending multiple references. It uses 1–16 input images and text prompts for targeted repainting, style changes and combining features, with millisecond-level response latency, up to 4K resolution and optional mask control. Its next-generation multimodal reasoning preserves the original subject’s identity, structural perspective and lighting consistency while quickly changing image elements. You can call it programmatically through the API or try it directly in the Playground above.

How many reference images does GPT Image 2.5 Flare Image Edit support?

image_urls accepts up to 16 publicly accessible HTTP(S) image URLs. The model can interpret and combine subject outlines, color styles, material details and spatial composition from multiple images for complex reference blending.

How do I use a mask for targeted edits with GPT Image 2.5 Flare Image Edit?

Provide mask_url in the request to enable masked editing. White areas mark the regions to regenerate, while black areas mark protected content to keep unchanged. The model follows your prompt to repaint only the white selection.

Does GPT Image 2.5 Flare Image Edit lose quality over successive edits?

Traditional models can blur details and lose quality after repeated repainting. GPT Image 2.5 reinforces memory across editing rounds to retain earlier changes, allowing creators to refine an image step by step as they would in professional editing software.

Should I choose GPT Image 2.5 Flare Image Edit or Sunburst Edit?

Flare Edit prioritizes low latency and fast responses while maintaining subject consistency, making it suitable for real-time interaction and large batches. Sunburst Edit targets commercial finals and fine detail, with stronger control over complex lighting adjustments and precise local edits.

How much does GPT Image 2.5 Flare Image Edit cost?

Editing and text-to-image endpoints share the same pricing matrix, based on quality and resolution. low / 1K costs 1.31 credits ($0.00655) per image, and the default high / 1K costs 11.78 credits ($0.05890). Additional reference images do not incur extra charges.

How should I write prompts to preserve people or product details in reference images?

Clearly state what to change and what to preserve. For example: "Replace the model’s outfit in the first image with a black evening dress. Keep the face, hairstyle, hair color and body pose exactly the same." This helps minimize repainting outside the intended area.