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
`n` (number of images)		Generate multiple images per request
`size` (WIDTHxHEIGHT)		Supported dimensions vary by model; some may approximate requested sizes
`quality`		`low`, `medium`, `high` + model specific quality levels
`style`		Some models support style parameters
`output_compression`		Supported on all input formats
`background`		Only opaque is supported
`moderation`		Only `auto` is supported
Extra model-specific params		Extra model-specific parameters not supported by the OpenAI API
Output
URL response format		Temporary URLs to generated images
Base64 JSON format		Inline base64-encoded images
PNG format		Lossless image output
JPEG format		Compressed image output
WebP format		Modern compressed format
Streaming
SSE streaming		Real-time generation updates
Partial images		Progressive previews when available
Usage tracking
Input text tokens		Estimated for reference
Output image tokens		Image count (billing unit)
Other
`user`		Logged

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

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"},
}

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.