Images API - Image Variations¶

Create variations of existing images using Amazon Bedrock image models through an OpenAI-compatible interface.

Why Choose the Image Variations API?¶

Multiple Variations
Generate diverse versions of an existing image while maintaining composition.
Artistic Exploration
Explore different artistic interpretations and styles.
Quick Iterations
Rapidly create variations without manual editing.
Flexible Models
Amazon Titan, Amazon Nova Canvas, and Stability AI SD3.5 — each with unique variation modes (standard variation, text-guided conditioning, color-guided generation).

Available Endpoints¶

Endpoint	Method	What It Does	Powered By	MCP Tool
`/v1/images/variations`	`POST`	Create variations of an existing image	Amazon Bedrock Image Models	`openai_image_variation`

Feature Compatibility¶

Feature	Status	Notes
Variations
Image-to-image (`/variations`)		Create variations of existing images
Parameters
`image`		Source image file (required)
`model`		Required parameter
`n` (number of images)		Multiple variations per request; accepted range is 1-10 (default: 1), 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)
`response_format`		`url` or `b64_json` (default: `url`)
Output
URL response format		Temporary download URLs, valid for 60 minutes (requires AWS_S3_BUCKET)
Base64 JSON format		Inline base64-encoded images
PNG format		Default output format
JPEG format		Via the provider-specific `output_format` extra parameter on supporting models (`/variations` has no `output_format` parameter)
WebP format		Via the provider-specific `output_format` extra parameter on supporting models (`/variations` has no `output_format` parameter)
Usage tracking
Input image tokens		Count of input images (always 1 for variations)
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
JSON body request format		Reference images via Files API ID or URL instead of file upload

Legend:

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

Model Support¶

Amazon Models¶

Model	Supported Task Types	Notes
amazon.nova-canvas-v1:0 (legacy)	`IMAGE_VARIATION`, `TEXT_IMAGE`, `COLOR_GUIDED_GENERATION`	Supports standard variations plus text-guided conditioning and color-guided generation with 8 style presets
amazon.titan-image-generator-v1 (legacy)	`IMAGE_VARIATION`	Basic variation support with similarity control
amazon.titan-image-generator-v2:0 (legacy)	`IMAGE_VARIATION`, `TEXT_IMAGE`, `COLOR_GUIDED_GENERATION`	Enhanced with text-guided conditioning (CANNY_EDGE, SEGMENTATION) and color-guided generation

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.

Stability AI Models¶

Model	Notes
stability.sd3-5-large-v1:0	Image-to-image transformation
stability.stable-image-core-v1:1	Image-to-image transformation, balanced quality and speed
stability.stable-image-ultra-v1:1	Image-to-image transformation, premium quality and detail

No Built-In Aliases for OpenAI Image Model Names

OpenAI's default image model names (dall-e-2, dall-e-3, gpt-image-1) have no built-in alias, so requests using them fail with a model-not-found error — the most common first-call issue. Pass one of the model IDs above, or map the OpenAI names to your preferred models with MODEL_ALIASES.

Configuration Required

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

Advanced Features¶

Request Formats¶

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

Multipart Form-Data (Binary Uploads)¶

The classic format — upload an image file directly via the image field.

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0"

JSON Body (Files API or URL References) ¶

Reference an image already stored in the Files API or accessible via URL. Send Content-Type: application/json with an image object containing either file_id or image_url:

# Variation from a Files API file ID
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "image": {"file_id": "file-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    "n": 2,
    "size": "1024x1024"
  }'

# Variation from an HTTP URL
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "image": {"image_url": "https://example.com/photo.png"},
    "response_format": "b64_json"
  }'

image object fields:

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; if both are given, file_id takes precedence. image may also be a plain reference string (equivalent to image_url) — the shape MCP clients derive from the tool schema:

{"model": "amazon.nova-canvas-v1:0", "image": "data:image/png;base64,..."}

Workflow Integration

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

Provider-Specific Parameters¶

Amazon Nova Canvas¶

Basic Usage (Standard OpenAI Parameters):

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0"

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`image`	Depends on `taskType`	See taskType-specific mapping below
`size`	`imageGenerationConfig.width/height`	Flexible (320-4096)
`style`	`textToImageParams.style`	Not a standard variations field — pass via extra param `textToImageParams[style]` (TEXT_IMAGE task)
`n`	`imageGenerationConfig.numberOfImages`	1-5 variations

TaskType-Specific Parameter Mapping:

taskType	`image` maps to
`IMAGE_VARIATION` (default)	`imageVariationParams.images`
`TEXT_IMAGE`	`textToImageParams.conditionImage`
`COLOR_GUIDED_GENERATION`	`colorGuidedGenerationParams.referenceImage`

Advanced Variation Modes (with form fields):

Default taskType is "IMAGE_VARIATION".

Available task types:

"IMAGE_VARIATION" - Standard image variations
"TEXT_IMAGE" - Text-guided generation with condition image
"COLOR_GUIDED_GENERATION" - Color palette-based variations

# Text-to-Image with Condition
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="TEXT_IMAGE" \
  -F "textToImageParams[text]=Photorealistic version"

# Color-Guided Variations
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0" \
  -F taskType="COLOR_GUIDED_GENERATION" \
  -F "colorGuidedGenerationParams[colors][]=#FF6B35" \
  -F "colorGuidedGenerationParams[colors][]=#F7931E" \
  -F "colorGuidedGenerationParams[colors][]=#FDC830"

Full Parameter Reference

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

Amazon Titan Image Generator¶

Basic Usage (Standard OpenAI Parameters):

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.titan-image-generator-v2:0"

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`image`	Depends on `taskType`	See taskType-specific mapping below
`size`	`imageGenerationConfig.width/height`	Fixed sizes (512-2048)
`n`	`imageGenerationConfig.numberOfImages`	1-5 variations

TaskType-Specific Parameter Mapping:

taskType	`image` maps to
`IMAGE_VARIATION` (default)	`imageVariationParams.images`
`TEXT_IMAGE`	`textToImageParams.conditionImage`
`COLOR_GUIDED_GENERATION`	`colorGuidedGenerationParams.referenceImage`

Advanced Variation Modes (with form fields):

Default taskType is "IMAGE_VARIATION".

Available task types:

"IMAGE_VARIATION" - Standard image variations
"TEXT_IMAGE" - Text-guided generation with condition image
"COLOR_GUIDED_GENERATION" - Color palette-based variations

# Text-Guided Condition Image
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.titan-image-generator-v2:0" \
  -F taskType="TEXT_IMAGE" \
  -F "textToImageParams[text]=Photorealistic version"

# Color-Guided Variations
curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.titan-image-generator-v2:0" \
  -F taskType="COLOR_GUIDED_GENERATION" \
  -F "colorGuidedGenerationParams[colors][]=#FF6B6B" \
  -F "colorGuidedGenerationParams[colors][]=#4ECDC4" \
  -F "colorGuidedGenerationParams[colors][]=#45B7D1"

Full Parameter Reference

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

Stability AI Models¶

Basic Usage (Standard OpenAI Parameters):

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="stability.sd3-5-large-v1:0"

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`image`	`image` (base64)	Source image for variation
`size`	`aspect_ratio`	Inferred from size (e.g., 1024x1024 → "1:1")
`n`	Multiple calls	Each variation is a separate request

Model-Specific Features:

Model	Output Formats	Notes
stability.sd3-5-large-v1:0	png, jpeg, webp	Image-to-image transformation

Full Parameter Reference

For all Stability AI parameters, see Stability AI documentation

Available 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/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Amzn-Bedrock-Service-Tier: priority" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0"

Try It Now¶

Create a simple variation:

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0"

Create multiple variations:

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0" \
  -F n=3

Base64 response format:

curl -X POST "$BASE/v1/images/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F image=@input.png \
  -F model="amazon.nova-canvas-v1:0" \
  -F response_format="b64_json"

Ready to explore new versions of your images? Discover available image models in the Models API.