Images API¶

Generate images with AWS Bedrock image models like Stability AI and Amazon Nova Canvas through an OpenAI-compatible interface.

Why Choose Image Generation?¶

Quality Output
Generate photorealistic images, digital art, and illustrations.
Real-Time Streaming
Progressive generation shows partial previews as the model works for interactive applications.
Flexible Control
Choose dimensions, quality levels, and styles. From quick drafts to high-resolution finals.
Scalable Infrastructure
Generate images at scale with AWS Bedrock infrastructure. No GPU management required.

Quick Start: Available Endpoint¶

Endpoint	Method	What It Does	Powered By
`/v1/images/generations`	POST	Generate images from text prompts	AWS Bedrock Image Models

Feature Compatibility¶

Feature	Status	Notes
Generation
Text-to-image (`/generations`)		Generate images from prompts
Parameters
`prompt`		Text description for generation (required, min 1 char)
`model`		Required parameter
`n` (number of images)		Generate multiple images per request (1-10, default: 1)
`size` (WIDTHxHEIGHT)		Output dimensions (default: 1024x1024, format validated)
`response_format`		`url` or `b64_json` (default: `url`)
`quality`		Quality setting (default: `auto`, supports OpenAI & model-specific)
`style`		Model-specific style parameters
`output_format`		`png`, `jpeg`, or `webp` (model-specific)
`output_compression`		Compression level 1-100% (default: 100)
`stream`		Generate images in streaming mode with partial results
`partial_images`		Number of partial images in stream (0-3, model-specific)
`background`		Always `auto`, transparent backgrounds unsupported
`moderation`		Always `auto`, other values unsupported
Extra model-specific params		Extra model-specific parameters via JSON body
Output
URL response format		Temporary URLs to generated images (requires AWS_S3_BUCKET)
Base64 JSON format		Inline base64-encoded images
PNG format		Lossless image output
JPEG format		Lossy compression (model-specific)
WebP format		Modern format with compression (model-specific)
Streaming
SSE streaming		Server-sent events with partial and final images
Partial images		Progressive previews when available
Usage tracking
Input text tokens		Estimated from prompt using tiktoken
Output image tokens		Number of images generated (`n` parameter)
Other
`user`		Logged but not used for abuse monitoring

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

Model Support¶

Amazon Models¶

Model	Supported Task Types	Notes
amazon.nova-canvas-v1:0	`TEXT_IMAGE`, `COLOR_GUIDED_GENERATION`	Supports standard text-to-image generation and color-guided generation with 8 style presets
amazon.titan-image-generator-v1	`TEXT_IMAGE`	Basic text-to-image generation
amazon.titan-image-generator-v2:0	`TEXT_IMAGE`, `COLOR_GUIDED_GENERATION`	Enhanced text-to-image generation with color-guided generation support

Stability AI Models¶

Model	Supported Task Types	Notes
stability.sd3-5-large-v1:0	`TEXT_IMAGE`	Stable Diffusion 3.5 Large - high quality output
stability.stable-image-core-v1:0	`TEXT_IMAGE`	Stable Image Core - balanced quality and speed
stability.stable-image-ultra-v1:0	`TEXT_IMAGE`	Stable Image Ultra - premium quality and detail

Configuration Required

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

Performance Optimization

For faster image downloads, especially for high-resolution images or globally distributed users, enable S3 Transfer Acceleration by setting AWS_S3_ACCELERATE=true. This uses CloudFront edge locations to accelerate file downloads, providing 50-500% faster speeds for users far from your S3 bucket region. See S3 Transfer Acceleration configuration for setup details.

Available Request Headers¶

This endpoint supports standard Bedrock headers for enhanced control over your requests. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

Header	Purpose	Valid Values
`X-Amzn-Bedrock-GuardrailIdentifier`	Guardrail ID for content filtering	Your guardrail identifier
`X-Amzn-Bedrock-GuardrailVersion`	Guardrail version	Version number (e.g., `1`)
`X-Amzn-Bedrock-Trace`	Guardrail trace level	`disabled`, `enabled`, `enabled_full`

Performance Optimization¶

Header	Purpose	Valid Values
`X-Amzn-Bedrock-Service-Tier`	Service tier selection	`priority`, `default`, `flex`
`X-Amzn-Bedrock-PerformanceConfig-Latency`	Latency optimization	`standard`, `optimized`

Example with headers:

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-Service-Tier: priority" \
  -H "X-Amzn-Bedrock-PerformanceConfig-Latency: optimized" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "prompt": "A serene mountain landscape at sunset"
  }'

Detailed Documentation

For complete information about these headers, configuration options, and use cases, see:

Advanced Features¶

Provider-Specific Parameters¶

Unlock advanced image generation capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to AWS Bedrock and allow you to access features unique to each image model provider.

Documentation: Bedrock Image Model Parameters

How It Works:

Add provider-specific fields at the top level of your request body alongside standard OpenAI parameters. The API automatically forwards these to the appropriate model provider via AWS Bedrock.

Examples:

Stability AI - Negative Prompts:

{
  "model": "stability.stable-image-core-v1:0",
  "prompt": "A serene mountain landscape at sunset",
  "negative_prompt": "blurry, distorted, low quality, watermark"
}

Amazon Nova Canvas - Negative Prompts:

{
  "model": "amazon.nova-canvas-v1:0",
  "prompt": "An abstract watercolor painting",
  "textToImageParams": {"negativeText": "blurry, distorted, low quality, watermark"}
}

Amazon Nova Canvas Extra Features¶

Basic Usage (Standard OpenAI Parameters):

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "prompt": "A futuristic cityscape at night"
  }'

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`prompt`	Depends on `taskType`	See taskType-specific mapping below
`size`	`imageGenerationConfig.width/height`	Flexible (320-4096)
`quality`	`imageGenerationConfig.quality`	"high" → "premium"
`style`	`textToImageParams.style`	8 preset styles
`n`	`imageGenerationConfig.numberOfImages`	1-5 images

TaskType-Specific Parameter Mapping:

taskType	`prompt` maps to
`TEXT_IMAGE` (default)	`textToImageParams.text`
`COLOR_GUIDED_GENERATION`	`colorGuidedGenerationParams.text`

Advanced Generation Modes:

Default taskType is "TEXT_IMAGE".

Available task types:

"TEXT_IMAGE" - Standard text-to-image generation
"COLOR_GUIDED_GENERATION" - Generate images based on color palette

# Color-Guided Generation
curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-canvas-v1:0",
    "prompt": "A sunset landscape",
    "taskType": "COLOR_GUIDED_GENERATION",
    "colorGuidedGenerationParams": {
      "colors": ["#FF6B6B", "#FFD93D", "#6BCB77"]
    }
  }'

Full Parameter Reference

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

Amazon Titan Image Generator Extra Features¶

Basic Usage (Standard OpenAI Parameters):

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.titan-image-generator-v2:0",
    "prompt": "A beautiful landscape with mountains"
  }'

Parameter Mapping:

OpenAI Parameter	Maps to	Notes
`prompt`	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
`TEXT_IMAGE` (default)	`textToImageParams.text`
`COLOR_GUIDED_GENERATION`	`colorGuidedGenerationParams.text`

Advanced Generation Modes:

Default taskType is "TEXT_IMAGE".

Available task types:

"TEXT_IMAGE" - Standard text-to-image generation
"COLOR_GUIDED_GENERATION" - Generate images based on color palette

# Color-Guided Generation
curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.titan-image-generator-v2:0",
    "prompt": "Nature scene with colors",
    "taskType": "COLOR_GUIDED_GENERATION",
    "colorGuidedGenerationParams": {
      "colors": ["#2ECC71", "#3498DB", "#F39C12"]
    }
  }'

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/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stability.stable-image-ultra-v1:0",
    "prompt": "A photorealistic mountain landscape at sunset"
  }'

Parameter Mapping:

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

Model Comparison:

Model	Output Formats	Best For
stability.sd3-5-large-v1:0	png, jpeg, webp	High quality, versatile compositions
stability.stable-image-core-v1:0	png, jpeg	Balanced quality and speed
stability.stable-image-ultra-v1:0	png, jpeg	Premium quality and detail

Full Parameter Reference

For all Stability AI parameters, see Stability AI documentation

Configuration Options:

Option 1: Per-Request

Add provider-specific parameters directly in your request body (as shown in examples above).

Option 2: Server-Wide Defaults

Configure default parameters for specific models via the DEFAULT_MODEL_PARAMS environment variable:

export DEFAULT_MODEL_PARAMS='{
  "stability.stable-image-core-v1:0": {
    "negative_prompt": "blurry, low quality, watermark"
  }
}'

Note: Per-request parameters override server-wide defaults.

Behavior:

✅ Compatible parameters: Forwarded to the model and applied
⚠️ Unsupported parameters: Return HTTP 400 with an error message

Try It Now¶

Generate image (URL response):

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "model": "amazon.nova-canvas-v1:0",
    "size": "1024x1024",
    "quality": "high",
    "response_format": "url"
  }'

Generate with base64 encoding:

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape with flying cars, digital art style",
    "model": "amazon.nova-canvas-v1:0",
    "response_format": "b64_json"
  }'

Stream generation with partial previews:

curl -N -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An abstract watercolor painting of emotions",
    "model": "amazon.nova-canvas-v1:0",
    "stream": true,
    "partial_images": 3
  }'

Unleash your creativity! Explore available image models in the Models API.