GPT Image 1.5 Edit API

openai/gpt-image-1.5/edit

image_urls · mask_url

GPT Image 1.5 Edit modifies existing images using text instructions and image references, featuring robust facial likeness preservation, optional mask-guided inpainting, and multi-image context blending. It seamlessly integrates new creative changes while preserving original subject identity, natural lighting, and fine background textures.

Get API Key

Input

PromptRequired0/1000

Image UrlsRequired

Add images

SizeOptional

NOptional

Mask UrlOptional

Upload Mask

OutputIdle

Generated images will appear here

Estimated cost: 2 × 1 = 2 credits · $0.010

2 credits ($0.010) per image, multiplied by n.

Continue using

GPT Image 1.5 Text to Image Kling O3 Image Edit Flux Dev Image to Image

Examples

Edit only the text on the lower plank: replace "SUMMIT 5 KM" with "SUMMIT CLOSED - SNOW" in the same cream-white hand-brushed capital letters, with the same letter height, stroke texture and slight unevenness, fitted neatly inside the same plank. Leave the upper plank "LAKE TRAIL 2 KM", both arrow shapes, the post, the wood grain, the camera angle and the forest exactly as they are. Then add only a thin layer of fresh snow resting on the top edges of both planks and on top of the post, with a few light snowflakes in the air. No other changes, no extra text, no logos, no watermark.

Turn the creature in this child's crayon drawing into a believable real animal photographed in a sunny backyard garden. Keep its exact design from the drawing: the round purple body, the same large orange spots in the same places, exactly six short stubby legs, two antennae ending in yellow balls, one big eye and the wide crooked smile with two square teeth. Give it realistic soft velvety skin, natural weight and contact shadows on the grass. Eye-level wildlife photography with shallow depth of field, warm afternoon light, a blurred wooden fence and flowers in the background. Friendly and charming, not scary. No paper, no crayon texture, no text, no watermark.

Combine the two reference images. Place the woman from image 1 into the hillside apiary from image 2. She stands beside the second beehive, holding a honeycomb frame she has just lifted out with both gloved hands and inspecting it closely while a few bees fly around. Keep her face, age, silver hair bun, hazel eyes and white beekeeping jacket exactly as in image 1. Keep the painted hive colors, lavender, stone wall, olive trees and hills from image 2. Relight the whole scene to warm golden-hour sunlight coming from the right, with matching shadows on the ground and a soft rim light on her hair, so she looks naturally photographed there. Realistic documentary photograph, three-quarter view, no text, no logos, no watermark.

REST API

Quick Start

This flow submits one valid GPT Image 1.5 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-1.5/edit",
  "input": {
    "prompt": "Replace the sky with a starry night sky.",
    "image_urls": [
      "https://example.com/image.png"
    ],
    "size": "1024x1024",
    "n": 1
  }
}'

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-1.5/edit",
  "input": {
    "prompt": "Replace the sky with a starry night sky.",
    "image_urls": [
      "https://example.com/image.png"
    ],
    "size": "1024x1024",
    "n": 1
  }
}
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	–	Describe the requested image changes using 1–1,000 characters, including at least one non-whitespace character.
input.image_urls	string[]	Yes	–	Provide at least one publicly accessible HTTP(S) image URL. Enter URLs or upload images.
input.size	string	No	1024x1024	Output image dimensions in pixels. Defaults to 1024x1024. 1024x1024, 1024x1536, 1536x1024.
input.n	integer	No	1	Number of output images: integer 1, 2, 3 or 4. Defaults to 1. 1, 2, 3, 4.
input.mask_url	string	No	–	Mask image selecting the area to edit. Enter a publicly accessible HTTP(S) URL or upload an image.

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-1.5/edit	Edit reference images using text instructions.
size	1024x1024 / 1024x1536 / 1536x1024	Default: 1024x1024

GPT Image 1.5 Edit API documentation

GPT Image 1.5 Edit

GPT Image 1.5 Edit is OpenAI's multimodal image editing model designed for precision modifications and multi-source visual synthesis. Supporting one or more reference images alongside optional mask inputs, it enables targeted inpainting, style transfers, object addition or removal, and background replacement via natural language instructions. The model excels at facial and identity preservation, supports square, portrait, and landscape sizes, and maintains seamless lighting and texture coherence between edited areas and original surroundings.

Why Choose GPT Image 1.5 Edit?

Robust Facial & Identity PreservationDeeply locks subject facial features, contours, and fine details across iterative edits, preventing identity drift during wardrobe, background, or pose changes.
Mask-Guided Inpainting & Direct Prompt EditsSupports targeted edits using mask_url for bounded modifications, or executes hair-level precision inpainting directly guided by natural language instructions.
Multi-Reference Context BlendingAccepts multiple reference images in image_urls, intelligently combining subject identity, apparel style, props, and backgrounds into a coherent composite.
Physically Consistent Lighting & TexturesAccurately simulates ambient lighting, reflections, shadows, and depth of field across edited and untouched regions for seamless integration.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the requested image changes using 1–1,000 characters, including at least one non-whitespace character.
image_urls	Required	Provide at least one publicly accessible HTTP(S) image URL. Enter URLs or upload images.
size	Optional	Output image dimensions in pixels. Defaults to 1024x1024. Default`1024x10241024x15361536x1024`
n	Optional	Number of output images: integer 1, 2, 3 or 4. Defaults to 1. Default`1234`
mask_url	Optional	Mask image selecting the area to edit. Enter a publicly accessible HTTP(S) URL or upload an image.

How to Use

Provide Reference Image URLsInclude at least one publicly accessible HTTP(S) image URL in the image_urls array as the editing canvas.
Specify Prompt and Optional MaskDescribe desired modifications in prompt (e.g., "replace background with a night beach"); optionally pass a black-and-white mask via mask_url to constrain edits.
Configure Canvas Size and CountSelect desired size (1024x1024, 1024x1536, or 1536x1024) and image count n (1–4), then review the estimated cost.
Submit Request and Retrieve EditsSubmit the request to obtain a task_id, then retrieve finished high-resolution image URLs via status polling or webhook callback.

Pricing

Each image costs 2 credits ($0.010). Total cost is multiplied by n.

Usage	Rate	Details
Standard generation	2 credits/image · $0.010/image	2 × n credits · $0.010 × n
n = 1 / 2 / 3 / 4	2 / 4 / 6 / 8 credits	$0.010 / $0.020 / $0.030 / $0.040

Best Use Cases

Portrait Retouching & Wardrobe ChangesRefine facial expressions, update clothing materials, and modify hairstyles while preserving complete subject likeness.
E-Commerce Product Background ReplacementIsolate merchandise and transport items into upscale lifestyle or outdoor settings without expensive studio reshoots.
Object Removal & Flaw InpaintingSeamlessly erase photobombers, watermarks, or unwanted clutter with automatic background texture infilling.
Brand Style Adaptation & Visual CompositingSynthesize multiple brand visual assets to produce consistent multi-image campaign variations and aesthetic transfers.

Pro Tips

Use a structured 'action + target object + preservation constraints' phrasing, such as 'replace the coffee cup with a book while keeping the person\'s pose, face, and background unchanged.'
When performing precise inpainting, pair prompts with a black-and-white mask image (white for edited zones, black for preserved areas) matching the source dimensions.
When blending multiple images, explicitly reference source roles in the prompt (e.g., 'the person from image 1 placed in the lighting of image 2').
For optimal facial preservation, use clear, evenly lit reference images without heavy obstructions or extreme angles.

Notes

image_urls is required and accepts one or more publicly accessible HTTP(S) image URLs to serve as visual references.
prompt is required and accepts 1 to 1,000 characters describing target modifications and elements to keep unchanged.
mask_url is optional, providing black-and-white spatial guidance for localized inpainting boundaries.
size supports 1024x1024, 1024x1536, and 1536x1024 dimensions, with n generating 1 to 4 parallel variations billed at 2 credits ($0.010) per image.

Related Models

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.

Seedream 5.0 Pro Image EditThe 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.

Nano Banana 2 Lite Text to Image preview

Nano Banana 2 Lite Text to ImageGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Nano Banana 2 Lite EditGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Grok Imagine Image Quality Text to Image preview

Grok Imagine Image Quality Text to ImageGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

Grok Imagine Image Quality EditGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

GPT Image 2 Text-to-ImageOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

GPT Image 2 Image EditOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

Wan 2.7 Image Standard Text to Image preview

Wan 2.7 Image Standard Text to ImageCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Wan 2.7 Image Standard EditCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

GPT Image 1.5 Edit API Frequently Asked Questions

What is the GPT Image 1.5 Edit API?

GPT Image 1.5 Edit is an OpenAI model for precision image editing and inpainting. It combines publicly accessible reference images, natural language edit instructions, and optional masks to generate modified high-fidelity visuals across 1024x1024, 1024x1536, or 1536x1024 dimensions, featuring robust facial likeness retention and multi-image blending. Built on OpenAI's advanced multimodal diffusion editing architecture, it integrates targeted creative modifications while preserving original subject identity, lighting, and ambient composition. You can call it programmatically or try it from the playground above.

How does GPT Image 1.5 Edit maintain facial consistency during edits?

The model leverages specialized identity-preservation representations. By specifying instructions such as 'keep the person\'s face and identity identical', the latent diffusion model locks key facial geometry and landmarks, modifying only target attributes like clothing or background while preventing facial distortion.

Is a mask image required for local edits in GPT Image 1.5 Edit?

No, a mask is optional. The model natively supports text-guided regional editing when you clearly describe which areas to alter and which to keep intact. Supplying a mask_url provides additional spatial bounding for complex or delicate inpainting tasks.

Does GPT Image 1.5 Edit support multiple reference images?

Yes. You can supply multiple image URLs in the image_urls array. The model extracts individual subjects, styles, and props across the provided inputs and composes them into a unified, coherent output guided by your prompt.

Are there additional fees for input images or masks in GPT Image 1.5 Edit?

No. GPT Image 1.5 Edit shares the exact same pricing model as text-to-image generation, with no surcharges for input images or mask URLs. Pricing is strictly 2 credits ($0.010) per output image, and failed tasks are automatically refunded.

Which canvas dimensions does GPT Image 1.5 Edit support?

GPT Image 1.5 Edit supports three native output dimensions: 1024x1024 (1:1 square, default), 1024x1536 (2:3 portrait), and 1536x1024 (3:2 landscape). The model maintains consistent compositional proportion and perspective across all supported aspect ratios.

Can GPT Image 1.5 Edit generate multiple edit variations simultaneously?

Yes. You can generate 1 to 4 distinct edit variations in a single API call by setting the n parameter (defaults to 1). All variations are processed in parallel according to your reference images and prompt, allowing rapid comparison of different edit styles.

How should prompts be written for effective GPT Image 1.5 Edit modifications?

Adopt an explicit edit pattern: define the specific modification, identify the target area, and explicitly list what should be preserved (e.g., 'replace the brick wall with a wooden fence, preserving the cat in the foreground'). Clarity on changes versus invariants produces the most reliable results.