GPT Image 2.5 Sunburst Image Edit API

openai/gpt-image-2.5-sunburst/edit

image_urls · mask_url

GPT Image 2.5 Sunburst Image Edit uses 1–16 references and masks for precise local edits and feature transfer across images. It locks subject identity and environmental lighting while changing selected elements, preserving quality throughout successive editing rounds.

Get API Key

Input

PromptRequired794/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.

1/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.

1/1 files added

OutputReady

Estimated cost: medium / 2K · 5.99 credits · $0.02995

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

Continue using

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

Examples

Image 1 defines the botanist's exact identity, face, glasses, clothes, kneeling pose, basalt coast and warm misty afternoon lighting. Image 2 defines only the distinctive fern cutting and its frond structure. Place one matching fern cutting resting diagonally across the cream notebook in his right hand. His left index finger gently indicates the fern's small amber spore dots; keep the hands anatomically correct and preserve the overall arm positions. The fern should be physically supported by the notebook with fine contact shadows, naturally scaled to the notebook, and illuminated by the same warm coastal light. Keep the face, clothing, basalt rocks, ocean mist and scene composition unchanged. Do not copy the neutral background from image 2 or add other plants, people or writing. No brands, logos, products for sale, advertisements, promotional graphics, watermark, split screen or comparison panels.

Use image 1, the already restored antique book, as the sole reference. Add only two small aged brass protective corner fittings to the upper-right and lower-right corners of the front cover, physically wrapped around the leather edges. Their patina and subtle highlights must fit the existing warm afternoon light. Preserve the previously repaired central leather surface without reintroducing the diagonal tear; keep the exact leather grain, blind-embossed border, book geometry, spine, worktable, bone folder, brush and linen cloth unchanged. No fittings on the spine side, no new cracks, writing or other objects. 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 Sunburst 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-sunburst/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-sunburst/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-sunburst/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 Sunburst Image Edit API documentation

GPT Image 2.5 Sunburst Image Edit

GPT Image 2.5 Sunburst Image Edit is OpenAI’s flagship editing model for precise local control and iterative creation. It combines up to 16 references, accurate masks and natural language instructions with strong local feature preservation. While changing target regions, it maintains the geometry and lighting of untouched areas and addresses detail degradation across successive edits, supporting premium commercial retouching and final visual production.

Why Choose GPT Image 2.5 Sunburst Image Edit?

Precise local edits with protected surroundingsWhen replacing objects or changing text, the model locks product structures, label designs, surface highlights and surrounding shadows in unselected areas to prevent unintended distortion.
Up to 16 references for detailed blendingProvide 1–16 high-resolution references to interpret and naturally combine composition lines, character identity, clothing textures and artistic styles from different images.
Consistent successive editing: Edits that stickA new memory architecture keeps details sharp and structures stable across editing rounds, retaining elements established in earlier steps throughout subsequent changes.
Flagship material rendering and lightingSunburst’s rendering engine blends repainted regions seamlessly with the original image’s grain, depth of field and natural lighting.
Up to 4K resolution and transparent outputNative 1K–4K resolution, transparent output and custom sizes support edited images for premium commercial printing and large-format advertising.

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 a local maskPrepare 1–16 publicly accessible HTTP(S) image URLs. Add a black-and-white mask for precise repainting of a specific region.
Write structured, targeted instructionsUse prompt to identify the elements to change and their desired properties. Explicitly state which subject features, composition and environmental lighting should remain locked.
Choose the resolution, quality and aspect ratioSet 1K–4K resolution and a preset aspect ratio to match your delivery requirements. Choose xhigh or max quality for the finest detail.
Submit an asynchronous editing taskSubmit your parameters through the API to receive a unique task_id. The high-performance cluster begins precise feature alignment and local repainting.
Poll the status and retrieve the resultCheck the status periodically using task_id. When the API returns finished, read the response and download the high-fidelity 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

Premium commercial and product retouchingReplace photographic backgrounds, correct local reflections or change display props while fully preserving fine material textures and distinctive product details.
Iterative film storyboards and concept artAdd character equipment, adjust expressions or change weather and lighting step by step while keeping the scene structure consistent across editing rounds.
Complex reference blending and character stylingCombine character artwork, real-world photographs and accessory references into a unified visual with consistent perspective, harmonious colors and key features from every image.
Local updates to signs and packaging textUse precise masks to replace specific English text and graphics on posters or packaging while leaving the surrounding print texture and lighting unchanged.

Pro Tips

Align binary masks precisely: use clear-edged pure white (#FFFFFF) selections in mask_url for regions to change. Pure black (#000000) regions are strictly protected as immutable content.
Describe local changes and global preservation: for example, "Change only the white sneakers in the selection to brown leather shoes. Keep the leg pose, lighting direction and ground shadows exactly the same." This helps maintain stable preservation.
Match references by order: explicitly mention "the subject in image 1" and "the background style in image 2". The model separates and maps features according to their order in image_urls.
Use max quality and 4K for commercial finals: choose this combination for retouched images intended for large-format printing or posters to achieve natural material seams and grain transitions.

Notes

image_urls is a required array of 1–16 publicly accessible HTTP(S) image URLs. URLs must not contain authentication information.
mask_url is an optional single mask and must be used together with image_urls. It cannot serve as an independent basis for generation.
prompt is required and supports up to 32,000 characters. Describe the requested edits and contextual features to preserve in detail.
Pricing depends on the selected quality and resolution, starting at 1.31 credits per generation. Additional reference images do not increase the charge.

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 Flare Image EditGPT 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.

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 Sunburst Image Edit API FAQ

What is GPT Image 2.5 Sunburst Image Edit API?

GPT Image 2.5 Sunburst Image Edit is OpenAI’s flagship model for precise image editing and reference blending. It uses 1–16 reference images and natural language instructions for local repainting, feature transfer and pixel-level mask control, with native resolution up to 4K and transparent output. Its advanced multimodal visual understanding locks the geometry, faces and fine environmental lighting in unselected regions while changing target elements, maintaining consistent quality across successive edits. You can call it programmatically through the API or try it directly in the Playground above.

How does GPT Image 2.5 Sunburst Image Edit protect unselected regions?

The model uses precise spatial awareness and feature isolation to distinguish target objects from the original background that should remain. Even without a mask, it can replace clothing or props while keeping faces, composition and environmental lighting unchanged.

What does GPT Image 2.5’s "Edits that stick" capability mean?

Traditional image models can gradually lose detail or distort structures after repeated repainting. Sunburst Edit reinforces the memory of earlier editing states, retaining details throughout successive adjustments so creators can confidently refine images through multiple stages.

How many reference images can GPT Image 2.5 Sunburst Image Edit combine?

image_urls accepts 1–16 public image URLs. The model can extract facial features, object textures and artistic styles across references, then combine them into a new image with consistent perspective and natural colors.

Can GPT Image 2.5 Sunburst Image Edit export subjects with transparent backgrounds?

Yes. Set background to transparent and output_format to png or webp. The model edits the subject while removing the background, producing a commercial-quality transparent asset ready for compositing.

How is GPT Image 2.5 Sunburst Image Edit priced?

The cost depends entirely on quality, with five levels from low to max, and resolution, with 1K, 2K and 4K options. low / 1K costs 1.31 credits ($0.00655) per image, while the default high / 1K costs 11.78 credits ($0.05890). Multiple references do not incur extra charges.

What are the mask requirements for GPT Image 2.5 Sunburst Image Edit?

mask_url must point to a single publicly accessible HTTP(S) image. Its dimensions and aspect ratio should match the main reference image. White regions mark content to regenerate; black regions mark original content to protect strictly.