Images API - Image Generation¶

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

At a glance¶

• Six Amazon Bedrock image models — Amazon Nova Canvas, two Amazon Titan Image Generator versions and three Stability AI models, behind one endpoint, see Models.
• n accepts 1 to 10 images per request — alongside size, quality, style, output_format and output_compression, see Feature compatibility.
• stream: true emits image_generation.completed — each finished image arrives as its own server-sent event instead of waiting for the whole batch, see Feature compatibility.
• Served by Amazon Bedrock in your own AWS account — no GPU capacity to provision, and url responses are download links to your own AWS_S3_BUCKET valid for 60 minutes, see Models.
• gpt-image-1 and the other OpenAI image model names are not aliased — map them with MODEL_ALIASES, since an unmapped name returns a model-not-found error, see Limits and behaviour to know.
• partial_images, moderation and transparent backgrounds are not served — the parameters are accepted or refused but never change the image, see Limits and behaviour to know.

curl -X POST "$BASE/v1/images/generations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stability.stable-image-core-v1:1",
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "size": "1024x1024"
  }'

Endpoints¶

Feature compatibility¶

Models¶

Amazon Models¶

Stability AI Models¶

Working with image models¶

Provider-Specific Parameters¶

Unlock advanced image generation capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to Amazon 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 Amazon Bedrock.

Configuration Options:

Option 1: Per-Request

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

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:1": {
    "negative_prompt": "blurry, low quality, watermark"
  }
}'

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

Behavior:

Compatible parameters are forwarded to the model and applied; unsupported parameters return HTTP 400 with an error message.

Examples:

Stability AI - Negative Prompts:

{
  "model": "stability.stable-image-core-v1:1",
  "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¶

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:

TaskType-Specific Parameter Mapping:

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"]
    }
  }'

Amazon Titan Image Generator¶

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:

TaskType-Specific Parameter Mapping:

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"]
    }
  }'

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:1",
    "prompt": "A photorealistic mountain landscape at sunset"
  }'

Parameter Mapping:

Model Comparison:

A format outside the model's native set is produced by re-encoding the returned image, so any model answers output_format: "webp".

Limits and behaviour to know¶

• 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 have no batch call, so each of the n images is a separate Bedrock request.
• 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_generation.completed event.
• moderation accepts only its default auto. Any other value is rejected with an error; content filtering is configured with the guardrail request headers instead.
• background has no transparent mode. auto and opaque are accepted, transparent is not, and every response reports opaque.
• quality and style reach only the models that have the control. A model with no equivalent setting accepts the field and ignores it.
• An unsupported provider-specific parameter returns HTTP 400. Compatible ones are forwarded to Bedrock — see Provider-Specific Parameters.
• OpenAI image model names resolve only once you map them, as described in the Models section.
• An optional parameter sent as null 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 standard Bedrock headers for enhanced control over your requests. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

Performance Optimization¶

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": "stability.stable-image-core-v1:1",
    "prompt": "A serene mountain landscape at sunset"
  }'

Try it¶

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": "stability.stable-image-core-v1:1",
    "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": "stability.stable-image-core-v1:1",
    "response_format": "b64_json"
  }'

Stream generation:

Each image is sent as a single completed event; partial_images is accepted but never produces a preview.

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": "stability.stable-image-core-v1:1",
    "stream": true,
    "n": 2
  }'

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_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","output_format":"png","size":"1024x1024","usage":{...}}

Next steps¶

Next: Models API · Images Edits API · Images Variations API · IAM permissions