Images API - Image Variations¶

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

At a glance¶

• n accepts 1 to 10 variations per request — all from a single source image, in one call, see Feature compatibility.
• Three variation modes on Amazon Nova Canvas and Titan v2 — IMAGE_VARIATION, TEXT_IMAGE conditioning and COLOR_GUIDED_GENERATION, selected with a taskType form field, see Working with the variations endpoint.
• Six Amazon Bedrock models — Amazon Nova Canvas, two Amazon Titan Image Generator versions and three Stability AI models, see Models.
• 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 image object holding a Files API ID or a URL, where the OpenAI variations API is multipart-only, see Working with the variations endpoint.
• This endpoint carries no output_format, quality, style, stream or background parameter — see Limits and behaviour to know.

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

Endpoints¶

Feature compatibility¶

Models¶

Amazon Models¶

Stability AI Models¶

Working with the variations endpoint¶

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="stability.sd3-5-large-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": "stability.sd3-5-large-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": "stability.sd3-5-large-v1:0",
    "image": {"image_url": "https://example.com/photo.png"},
    "response_format": "b64_json"
  }'

image object fields:

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": "stability.sd3-5-large-v1:0", "image": "data:image/png;base64,..."}

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:

TaskType-Specific Parameter Mapping:

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"

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:

TaskType-Specific Parameter Mapping:

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"

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:

Model-Specific Features:

Limits and behaviour to know¶

• The request body is image, model, n, size, response_format and user. There is no output_format, quality, style, stream or background parameter on this endpoint, so the response is PNG unless a supporting model is given the provider-specific output_format extra parameter.
• 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. Stability AI models produce each variation with a separate Bedrock call.
• Prompt text is not a standard parameter here. The TEXT_IMAGE and COLOR_GUIDED_GENERATION task types take their text through the provider-specific textToImageParams[text] and colorGuidedGenerationParams fields — see Working with the variations endpoint.
• 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/variations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Amzn-Bedrock-Service-Tier: priority" \
  -F image=@input.png \
  -F model="stability.sd3-5-large-v1:0"

Try it¶

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="stability.sd3-5-large-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="stability.sd3-5-large-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="stability.sd3-5-large-v1:0" \
  -F response_format="b64_json"

Next steps¶

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