Images API - Image Editing¶

Edit images using inpainting with Amazon Bedrock image models through an OpenAI-compatible interface.

At a glance¶

Nineteen Amazon Bedrock editing models — inpainting, image-to-image, upscale, style transfer, search-and-replace, background removal and control, all on /v1/images/edits, see Models.
Task types the OpenAI surface has no field for — Nova Canvas adds OUTPAINTING, BACKGROUND_REMOVAL and VIRTUAL_TRY_ON with three mask types, reached with extra form fields, see Working with the editing endpoint.
Masks in either convention — an alpha-channel PNG is converted to the black/white RGB form each backend requires, a black/white mask passes through unchanged, see Working with the editing endpoint.
Served by Amazon Bedrock in your own AWS account — url responses are download links to your own AWS_S3_BUCKET, valid for 60 minutes, see Feature compatibility.
A JSON body is accepted as well as multipart — an images array of 1-16 Files API IDs or URLs, where the OpenAI edits API is multipart-only, see Working with the editing endpoint.
One source image per request, and input_fidelity: high is refused — see Limits and behaviour to know.

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@source.png \
  -F mask=@edit_mask.png \
  -F prompt="A red apple on a wooden table" \
  -F model="amazon.nova-canvas-v1:0"

Endpoints¶

Endpoint	Method	What It Does	Powered By	MCP Tool
`/v1/images/edits`	`POST`	Edit images using prompts and masks	Amazon Bedrock Image Models	`openai_image_edit`

Feature compatibility¶

Feature	Status	Notes
Editing
Image-to-image (`/edits`)		Edit images with prompts and masks
Request Formats
Multipart form-data		Binary file uploads via `image` / `image[]` / `mask` fields
JSON body		Structured `images` array with Files API IDs or URLs (the OpenAI edits API is multipart-only)
Parameters
`image` / `image[]`		PNG image(s) to edit; every available model accepts exactly one source image and rejects requests providing more with an error
`images` (JSON)		Array of `{file_id}` or `{image_url}` references (JSON body, 1-16 entries)
`prompt`		Text description of desired changes
`mask`		Optional mask defining edit regions; models that do not use a mask reject requests that include one
`n` (number of images)		Multiple images per request; accepted range is 1-10, but the effective maximum is model-dependent (e.g. Amazon Titan and Nova Canvas cap at 5)
`size` (WIDTHxHEIGHT)		Output dimensions (default: 1024x1024, format validated; `auto` resolves to the default)
`model`		Required parameter
`response_format`		`url` or `b64_json` (default: `url`); with `stream: true` every event carries `b64_json`, whichever format was requested
`output_format`		`png`, `jpeg`, or `webp` on every model; the gateway re-encodes when the model cannot produce the format natively
`output_compression`		Compression level 0-100% (default: 100)
`quality`		Quality setting (default: `auto`, supports OpenAI & model-specific); accepted and ignored by models with no quality control
`stream`		Generate images in streaming mode, emitting the endpoint's `image_edit.partial_image` and `image_edit.completed` events
`partial_images`		Accepted (0-3) but ignored — no available model currently streams partial images; the final image is always sent as a single event
`background`		Accepts `auto` (default) and `opaque`; `transparent` is unsupported — responses report `opaque`
`input_fidelity`		Only the default `low` is accepted; `high` is rejected with an error
Output
URL response format		Temporary download URLs, valid for 60 minutes (requires AWS_S3_BUCKET)
Base64 JSON format		Inline base64-encoded images
PNG format		Lossless image output
JPEG format		Lossy compression, re-encoded server-side when the model has no native JPEG output
WebP format		Modern format with compression, re-encoded server-side when the model has no native WebP output
Streaming response		Server-sent events with final images (no partial previews)
Usage tracking
Input text tokens		Sourced from AWS billing data when available; remainder after subtracting image tokens
Input image tokens		Count of input images (image files + mask file), capped at the billed input tokens
Output image tokens		Sourced from AWS billing data when available; falls back to the image count (`n`)
Other
`user`		Logged but not used for abuse monitoring
Extra parameters via form data		Provider-specific parameters passed through

Legend:

Supported — Fully compatible with OpenAI API
Available on Select Models — Check your model's capabilities
Partial — Supported with limitations
Unsupported — Not available in this implementation
Extra Feature — Enhanced capability beyond OpenAI API

Models¶

Model Support

Inpainting (mask-based editing) is supported by Amazon Nova Canvas, Amazon Titan Image Generator, and Stability AI inpaint models.

Image-to-image (transformation without masks) is supported by Stability AI text-to-image models (SD3.5, Stable Image Core, Stable Image Ultra).

Upscale (resolution enhancement) is supported by Stability AI upscale models (creative, conservative, fast).

Style Transfer (applying reference image style) is supported by Stability AI style transfer models.

Search-based editing (find & replace/recolor objects) is supported by Stability AI search models.

Background removal is supported by Amazon Titan Image Generator v2, Amazon Nova Canvas, and Stability AI remove background model.

Amazon Models¶

Model	Supported Task Types	Mask Support	Notes
amazon.nova-canvas-v1:0 (legacy)	`TEXT_IMAGE`, `INPAINTING`, `OUTPAINTING`, `BACKGROUND_REMOVAL`, `VIRTUAL_TRY_ON`	✅ Required for inpainting/outpainting ✅ Used as reference for virtual try-on	Supports multiple editing modes including advanced virtual try-on with 3 mask types
amazon.titan-image-generator-v1 (legacy)	`INPAINTING`, `OUTPAINTING`	✅ Required for inpainting/outpainting	Supports text-based mask prompts as alternative to mask images
amazon.titan-image-generator-v2:0 (legacy)	`INPAINTING`, `OUTPAINTING`, `BACKGROUND_REMOVAL`	✅ Required for inpainting/outpainting ❌ Rejected for background removal	Enhanced features including background removal without mask

Legacy Amazon Image Models

AWS has scheduled amazon.nova-canvas-v1:0 and the Titan image models to reach end of life on September 30, 2026. Deployments with existing access can keep using them until then (legacy models are hidden unless AWS_BEDROCK_LEGACY=true); the Stability AI Stable Image family is the long-term successor.

Amazon Nova Canvas Default Behavior

amazon.nova-canvas-v1:0 automatically selects the task type based on the presence of a mask when no taskType is explicitly provided:

No mask provided → Uses TEXT_IMAGE by default
Mask provided → Uses INPAINTING by default

Stability AI Models¶

Image-to-Image Models¶

Model	Prompt Usage	Mask Usage	Extra Parameters Required	Notes
stability.sd3-5-large-v1:0	Guides transformation	Rejected if provided	None	Transform images with prompt
stability.stable-image-core-v1:1	Guides transformation	Rejected if provided	None	Balanced quality and speed
stability.stable-image-ultra-v1:1	Guides transformation	Rejected if provided	None	Premium quality and detail

Upscale Models¶

Model	Prompt Usage	Mask Usage	Extra Parameters Required	Notes
stability.stable-creative-upscale-v1:0	Guides upscaling	Rejected if provided	None	Prompt-guided upscaling with creativity
stability.stable-conservative-upscale-v1:0	Guides upscaling	Rejected if provided	None	Detail-preserving upscaling
stability.stable-fast-upscale-v1:0	Not used	Rejected if provided	None	Fast 4x upscaling without prompt

Edit Models¶

Model	Prompt Usage	Mask Usage	Extra Parameters Required	Notes
stability.stable-image-inpaint-v1:0	Guides inpainting	Optional (marks edit region)	None	Fill masked regions
stability.stable-outpaint-v1:0	Guides outpainting	Rejected if provided	None	Extend image beyond borders
stability.stable-image-search-recolor-v1:0	Describes new color	Rejected if provided	`select_prompt`	Recolor objects by search prompt
stability.stable-image-search-replace-v1:0	Describes replacement	Rejected if provided	`search_prompt`	Replace objects by search prompt
stability.stable-image-erase-object-v1:0	Not used	Required (marks object)	None	Remove objects with mask
stability.stable-image-remove-background-v1:0	Not used	Rejected if provided	None	Automatic background removal

Control Models¶

Model	Prompt Usage	Mask Usage	Extra Parameters Required	Notes
stability.stable-image-control-sketch-v1:0	Guides generation	Rejected if provided	None	Generate from sketch
stability.stable-image-control-structure-v1:0	Guides generation	Rejected if provided	None	Structure-preserving generation

Style Models¶

Model	Prompt Usage	Mask Usage	Extra Parameters Required	Notes
stability.stable-image-style-guide-v1:0	Guides style	Rejected if provided	None	Extract and apply style
stability.stable-style-transfer-v1:0	Guides style transfer	Required (repurposed as `style_image`)	None	Transfer style between images

Output Formats

All models support standard OpenAI output formats (png, jpeg, webp) via the output_format parameter. When a model cannot produce the requested format natively, the gateway re-encodes the result server-side, so the response always carries the format you asked for.

Extra Parameters Required

Some models require parameters beyond the standard OpenAI API:

stability.stable-image-search-recolor-v1:0: Requires select_prompt form field
stability.stable-image-search-replace-v1:0: Requires search_prompt form field

Models that don't use prompt: stability.stable-fast-upscale-v1:0, stability.stable-image-erase-object-v1:0, stability.stable-image-remove-background-v1:0 - provide empty string or omit the prompt parameter.

All other Stability models use only standard OpenAI parameters (image, prompt, and optionally mask).

No Built-In Aliases for OpenAI Image Model Names

gpt-image-1 and gpt-image-1-mini have no built-in alias, so requests naming them fail with a model-not-found error — the most common first-call issue. Pass one of the model IDs above, or map those names to your preferred models with MODEL_ALIASES. The retired dall-e-2 and dall-e-3 names are legacy strings older clients may still send; map them the same way.

Configuration Required

You must configure the AWS_S3_BUCKET environment variable with a bucket to use the URL response format.

Working with the editing endpoint¶

Request Formats¶

The /v1/images/edits endpoint accepts two request formats:

Multipart Form-Data (Binary Uploads)¶

The classic format — upload image files directly. Use image (single) or image[] (multiple) for source images and mask for the optional edit mask.

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@source.png \
  -F mask=@mask.png \
  -F prompt="A red apple on a wooden table" \
  -F model="amazon.nova-canvas-v1:0"

JSON Body (Files API or URL References) ¶

The modern format — reference images already stored in the Files API or accessible via URL. Send Content-Type: application/json with an images array (1-16 entries), where each element has either file_id or image_url:

# Edit using a Files API file ID
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "prompt": "A red apple on a wooden table",
    "images": [{"file_id": "file-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}],
    "response_format": "b64_json",
    "size": "1024x1024"
  }'

# Edit using an HTTP URL
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "prompt": "Add a dramatic sky",
    "images": [{"image_url": "https://example.com/photo.png"}],
    "mask": {"file_id": "file-mxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    "size": "1024x1024"
  }'

ImageRef object (used in images array and mask field):

Field	Type	Description
`file_id`	string	Files API file identifier (`file-` or `file_` prefix)
`image_url`	string	HTTP/HTTPS URL, data URI (`data:image/png;base64,...`), S3 URI (`s3://bucket/key`), or Files API reference (`file-id:file-<id>` — see Files API)

Provide one of file_id or image_url per ImageRef; if both are given, file_id takes precedence. Each array element may also be a plain reference string (equivalent to image_url), and the array is additionally accepted under the image key — the shapes MCP clients derive from the tool schema:

{"model": "amazon.nova-canvas-v1:0", "prompt": "Add a dramatic sky", "image": ["data:image/png;base64,..."]}

Workflow Integration

The JSON body format works with the Files API: upload images once, reuse them across multiple edit requests by file ID without re-uploading.

How Image Editing Works¶

Image-to-Image (Stability AI Models)¶

Stability AI models support image-to-image transformation without masks. The source image is transformed according to the prompt:

# Transform a photo into an oil painting style
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="Transform into an oil painting style" \
  -F model="stability.sd3-5-large-v1:0"

Mask Not Supported

Stability AI image-to-image models do not support mask-based editing. Providing a mask parameter will result in an error.

Upscale (Stability AI)¶

Upscale models increase image resolution while preserving quality:

# Fast upscaling (4x) - no prompt parameter needed
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@low_res.png \
  -F model="stability.stable-fast-upscale-v1:0"

Upscale Characteristics

Fast Upscale: Conservative 4x upscaling that preserves original details
No prompt parameter needed or used
Best for enlarging photos and preserving original content

Style Transfer (Stability AI)¶

Apply visual characteristics from one image to another. The mask parameter is used to pass the style reference image:

# Apply style from reference image to target image
# image: content image, mask: style reference image
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@content.png \
  -F mask=@style_reference.png \
  -F prompt="Apply artistic style while preserving content" \
  -F model="stability.stable-style-transfer-v1:0"

Style Transfer Parameter Mapping

image (required): Target image to apply style to
mask (required): Maps to style_image - the reference style image
prompt: Guides the style application process

Inpainting with Masks (Amazon Models and Stability AI)¶

An image submitted without a mask is not auto-masked from its own transparency: it is sent as a conditioning image for text-to-image generation instead of an inpainting edit. To edit specific regions, always provide an explicit mask.

With Explicit Mask:

Provide an explicit mask image where transparent areas indicate regions to edit:

# Edit with explicit mask
# image: source image, mask: PNG where transparent areas mark edit regions
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@source.png \
  -F mask=@edit_mask.png \
  -F prompt="A beautiful flower" \
  -F model="amazon.nova-canvas-v1:0"

Mask format: PNG with alpha channel where transparent pixels indicate regions to edit, opaque pixels are preserved (standard OpenAI edits-API mask). A mask with an alpha channel is automatically converted to the black/white RGB format each backend requires (Nova Canvas, Titan, and the Stability AI inpaint/erase-object models); a mask that is already black/white RGB (no alpha channel) is passed through unchanged.

Provider-Specific Parameters¶

Amazon Nova Canvas¶

Basic Usage (Standard OpenAI Parameters):

# Inpainting with mask
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@source.png \
  -F mask=@mask.png \
  -F prompt="A sunset over mountains" \
  -F model="amazon.nova-canvas-v1:0"

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`prompt`	Depends on `taskType`	See taskType-specific mapping below
`image` / `image[]`	Depends on `taskType`	See taskType-specific mapping below (single image required)
`mask`	Depends on `taskType`	See taskType-specific mapping below
`size`	`imageGenerationConfig.width/height`	Output dimensions (320-4096)
`quality`	`imageGenerationConfig.quality`	"high" → "premium"
`n`	`imageGenerationConfig.numberOfImages`	1-5 images

TaskType-Specific Parameter Mapping:

taskType	`prompt` maps to	`image` maps to	`mask` maps to
`TEXT_IMAGE` (default, no mask)	`textToImageParams.text`	`textToImageParams.conditionImage`	Not used
`INPAINTING` (default with mask)	`inPaintingParams.text`	`inPaintingParams.image`	`inPaintingParams.maskImage`
`OUTPAINTING`	`outPaintingParams.text`	`outPaintingParams.image`	`outPaintingParams.maskImage`
`BACKGROUND_REMOVAL`	Not used	`backgroundRemovalParams.image`	Rejected if provided
`VIRTUAL_TRY_ON` (PROMPT)	`promptBasedMask.maskPrompt`	`virtualTryOnParams.sourceImage`	`virtualTryOnParams.referenceImage`
`VIRTUAL_TRY_ON` (GARMENT)	`garmentBasedMask.garmentClass`	`virtualTryOnParams.sourceImage`	`virtualTryOnParams.referenceImage`
`VIRTUAL_TRY_ON` (IMAGE)	`imageBasedMask.maskImage` (Base64 encoded image or data URI)	`virtualTryOnParams.sourceImage`	`virtualTryOnParams.referenceImage`

Advanced Task Types (with form fields):

Default taskType is "INPAINTING" when a mask is provided, "TEXT_IMAGE" otherwise.

Available task types:

"TEXT_IMAGE" - Prompt-driven transformation using the source image as condition
"INPAINTING" - Fill masked regions
"OUTPAINTING" - Extend image beyond borders
"BACKGROUND_REMOVAL" - Remove background
"VIRTUAL_TRY_ON" - Virtual fashion try-on

# Outpainting
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="Extend with a garden" \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="OUTPAINTING"

# Background Removal (no prompt needed)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="BACKGROUND_REMOVAL"

# Virtual Try-On - Prompt-Based (default)
# image: person photo, mask: garment image, prompt: area description
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@person.png \
  -F mask=@garment.png \
  -F prompt="upper body area" \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="VIRTUAL_TRY_ON"

# Virtual Try-On - Garment-Based
# image: person photo, mask: garment image, prompt: garment class
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@person.png \
  -F mask=@garment.png \
  -F prompt="UPPER_BODY" \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="VIRTUAL_TRY_ON" \
  -F "virtualTryOnParams[maskType]=GARMENT"

# Virtual Try-On - Image-Based Mask
# image: person photo, mask: garment image, prompt: base64 mask image
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@person.png \
  -F mask=@garment.png \
  -F prompt="BASE64_MASK_IMAGE" \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="VIRTUAL_TRY_ON" \
  -F "virtualTryOnParams[maskType]=IMAGE"

Full Parameter Reference

For all available parameters and task types, see Amazon Nova Canvas documentation

Amazon Titan Image Generator¶

Basic Usage (Standard OpenAI Parameters):

# Inpainting with mask
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@source.png \
  -F mask=@mask.png \
  -F prompt="A beautiful garden with flowers" \
  -F model="amazon.titan-image-generator-v2:0"

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`prompt`	Depends on `taskType`	See taskType-specific mapping below
`image` / `image[]`	Depends on `taskType`	See taskType-specific mapping below (single image required)
`mask`	Depends on `taskType`	See taskType-specific mapping below
`size`	`imageGenerationConfig.width/height`	Fixed sizes (512-2048)
`quality`	`imageGenerationConfig.quality`	"high" → "premium"
`n`	`imageGenerationConfig.numberOfImages`	1-5 images

TaskType-Specific Parameter Mapping:

taskType	`prompt` maps to	`image` maps to	`mask` maps to
`INPAINTING` (default)	`inPaintingParams.text`	`inPaintingParams.image`	`inPaintingParams.maskImage`
`OUTPAINTING`	`outPaintingParams.text`	`outPaintingParams.image`	`outPaintingParams.maskImage`
`BACKGROUND_REMOVAL`	Not used	`backgroundRemovalParams.image`	Rejected if provided

Advanced Task Types (with form fields):

Default taskType is "INPAINTING".

Available task types:

"INPAINTING" - Fill masked regions
"OUTPAINTING" - Extend image beyond borders
"BACKGROUND_REMOVAL" (v2 only) - Remove background

# Outpainting
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="Extend with a forest" \
  -F model="amazon.titan-image-generator-v2:0" \
  -F taskType="OUTPAINTING"

# Background Removal (v2 only, no prompt needed)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F model="amazon.titan-image-generator-v2:0" \
  -F taskType="BACKGROUND_REMOVAL"

Full Parameter Reference

For all available parameters and task types, see Amazon Titan Image Generator documentation

Stability AI Models¶

Basic Usage (Standard OpenAI Parameters):

Most Stability AI models work with standard OpenAI parameters:

# Image-to-image transformation
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="A dramatic cinematic scene" \
  -F model="stability.sd3-5-large-v1:0"

Parameter Mapping:

All Stability AI models use standard OpenAI parameters directly:

OpenAI Parameter	Stability Parameter	Notes
`image` / `image[]`	`image`	Base64-encoded input image (single image required)
`prompt`	`prompt`	Text description (may be unused for some models)
`mask`	`mask`	Base64-encoded mask (model-specific)
`n`	Multiple requests	Generates N images via multiple API calls
`size`	Model-specific	Some models support width/height

Model-Specific Parameters:

Model(s)	Required Form Fields	OpenAI `mask` Maps To	Notes
`stable-image-search-recolor-v1:0`	`select_prompt` (string)	Not used	Identifies object to recolor
`stable-image-search-replace-v1:0`	`search_prompt` (string)	Not used	Identifies object to find and replace
`stable-style-transfer-v1:0`	None (uses `mask` param)	`style_image`	Mask parameter repurposed as style image
`stable-image-erase-object-v1:0`	None	`mask` (required)	Prompt not used
`stable-image-remove-background-v1:0`	None	Not used	Prompt not used
`stable-fast-upscale-v1:0`	None	Not used	Prompt not used

Full Parameter Reference

For all Stability AI parameters, see Stability AI documentation

Limits and behaviour to know¶

Every available model edits exactly one source image. The schema accepts the repeated image[] parameter for OpenAI wire compatibility, and a request carrying more than one image is refused with an error.
An image sent without a mask is not auto-masked — see Inpainting with Masks.
A model that does not use a mask rejects one. The per-model tables under Models give each model's mask usage: image-to-image, upscale, outpaint and search-based models return an error when a mask is provided.
Two models need a form field the OpenAI API has no place for, select_prompt and search_prompt, listed under Models.
n is capped by the model, not by the endpoint. The endpoint accepts 1-10; the effective maximum is model-dependent, and Amazon Titan and Nova Canvas stop at 5.
input_fidelity accepts only its default low. high is rejected with an error.
partial_images never produces a preview. No available model streams partial images, so the value (0-3) is accepted and ignored and each finished image is sent as a single image_edit.completed event.
background has no transparent mode. auto and opaque are accepted, transparent is not, and every response reports opaque.
quality reaches only the models that have the control. A model with no equivalent setting accepts the field and ignores it.
OpenAI image model names resolve only once you map them, as described in the Models section.
An optional parameter sent as null in a JSON body counts as unset, and the request is served with that parameter's default, exactly as leaving the key out would be. model is the exception: it is required here, so a null one is refused like a missing one.

Request headers¶

This endpoint supports the same standard Bedrock headers as the other images endpoints: guardrail headers (X-Amzn-Bedrock-GuardrailIdentifier, X-Amzn-Bedrock-GuardrailVersion, X-Amzn-Bedrock-Trace) and performance headers (X-Amzn-Bedrock-Service-Tier, X-Amzn-Bedrock-PerformanceConfig-Latency). All headers are optional and can be combined as needed.

See the Images Generation API headers reference for the header tables, valid values, and configuration links.

Example with headers:

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Amzn-Bedrock-Service-Tier: priority" \
  -F image=@source.png \
  -F prompt="A red apple on a wooden table" \
  -F model="amazon.nova-canvas-v1:0"

Try it¶

Image-to-Image with Stability AI¶

# Transform image with default strength (0.35)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="Transform into a watercolor painting" \
  -F model="stability.sd3-5-large-v1:0"

Upscale with Stability AI¶

# Fast upscaling (4x resolution increase) - no prompt needed
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@low_res.png \
  -F model="stability.stable-fast-upscale-v1:0"

Style Transfer with Stability AI¶

# Apply style from reference image (mask parameter is style image)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@content.png \
  -F mask=@style_reference.png \
  -F prompt="Apply artistic style" \
  -F model="stability.stable-style-transfer-v1:0"

Search & Replace with Stability AI¶

# Replace objects by search prompt (requires search_prompt form field)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F prompt="a red car" \
  -F model="stability.stable-image-search-replace-v1:0" \
  -F search_prompt="blue car"

Search & Recolor with Stability AI¶

# Recolor objects by search prompt (requires select_prompt form field)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F prompt="bright red color" \
  -F model="stability.stable-image-search-recolor-v1:0" \
  -F select_prompt="car"

Erase Object with Stability AI¶

# Erase object with mask - no prompt needed
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F mask=@object_mask.png \
  -F model="stability.stable-image-erase-object-v1:0"

Remove Background with Stability AI¶

# Remove background automatically - no prompt needed
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="stability.stable-image-remove-background-v1:0"

Prompt-Driven Transformation Without a Mask (Amazon Models)¶

With no mask, the source image is used as a conditioning image for text-to-image generation, not as an inpainting edit.

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@image.png \
  -F prompt="A blue ocean with sailboats" \
  -F model="amazon.nova-canvas-v1:0"

Inpainting with an Explicit Mask¶

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@source.png \
  -F mask=@mask.png \
  -F prompt="A red sports car" \
  -F model="amazon.nova-canvas-v1:0"

Base64 Response Format¶

curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@image.png \
  -F prompt="A sunny day with blue sky" \
  -F model="amazon.nova-canvas-v1:0" \
  -F response_format="b64_json"

Multiple Edited Images¶

# Generate three edited images from the same source (n parameter)
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@image.png \
  -F prompt="A fantasy castle" \
  -F n=3 \
  -F model="amazon.nova-canvas-v1:0"

Streaming the Edit¶

curl -N -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@image.png \
  -F prompt="A fantasy castle" \
  -F model="amazon.nova-canvas-v1:0" \
  -F stream=true

Each frame names its event before carrying it, so a client reading the raw stream can dispatch on the event: line as well as on the payload's type:

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","output_format":"png","size":"1024x1024","usage":{...}}

The `image[]` Array Parameter¶

One Source Image Per Request

The schema accepts the repeated image[] multipart parameter for OpenAI wire compatibility, but every model currently available through the gateway edits exactly one source image and rejects a request carrying more than one with an error. Send a single image field, or an image[] array with a single entry.

# OpenAI-compatible array syntax, with the single source image every model expects
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "image[]=@gift-basket.png" \
  -F prompt="Add a ribbon around the basket" \
  -F model="amazon.nova-canvas-v1:0"

Generate from Sketch or Structure (Control Models)¶

# Control Sketch - generate from sketch
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@sketch.png \
  -F prompt="A realistic portrait" \
  -F model="stability.stable-image-control-sketch-v1:0"

# Control Structure - preserve structure
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@structure.png \
  -F prompt="A modern building" \
  -F model="stability.stable-image-control-structure-v1:0"

Inpainting & Outpainting with Stability AI¶

# Stability AI Inpainting - mask marks edit region
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F mask=@edit_mask.png \
  -F prompt="A beautiful sunset" \
  -F model="stability.stable-image-inpaint-v1:0"

# Outpainting - extend image beyond borders
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@photo.png \
  -F prompt="Extend with a forest landscape" \
  -F model="stability.stable-outpaint-v1:0"

Style Guide¶

# Extract and apply style from reference
curl -X POST "$BASE/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@content.png \
  -F prompt="Apply impressionist style" \
  -F model="stability.stable-image-style-guide-v1:0"

Next steps¶

Next: Models API · Images Generation API · Images Variations API · Files API

Images API - Image Editing¶

At a glance¶

Endpoints¶

Feature compatibility¶

Models¶

Amazon Models¶

Stability AI Models¶

Image-to-Image Models¶

Upscale Models¶

Edit Models¶

Control Models¶

Style Models¶

Working with the editing endpoint¶

Request Formats¶

Multipart Form-Data (Binary Uploads)¶

JSON Body (Files API or URL References) ¶

How Image Editing Works¶

Image-to-Image (Stability AI Models)¶

Upscale (Stability AI)¶

Style Transfer (Stability AI)¶

Inpainting with Masks (Amazon Models and Stability AI)¶

Provider-Specific Parameters¶

Amazon Nova Canvas¶

Amazon Titan Image Generator¶

Stability AI Models¶

Limits and behaviour to know¶

Request headers¶

Try it¶

Image-to-Image with Stability AI¶

Upscale with Stability AI¶

Style Transfer with Stability AI¶

Search & Replace with Stability AI¶

Search & Recolor with Stability AI¶

Erase Object with Stability AI¶

Remove Background with Stability AI¶

Prompt-Driven Transformation Without a Mask (Amazon Models)¶

Inpainting with an Explicit Mask¶

Base64 Response Format¶

Multiple Edited Images¶

Streaming the Edit¶

The image[] Array Parameter¶

Generate from Sketch or Structure (Control Models)¶

Inpainting & Outpainting with Stability AI¶

Style Guide¶

Next steps¶

The `image[]` Array Parameter¶