Overview

AWS Bedrock supports multiple model families (Claude, Nova, Mistral, Llama, Cohere, Titan) with significant structural differences from OpenAI’s format. Bifrost performs extensive conversion including:

Model family detection - Automatic routing based on model ID to handle family-specific parameters
Parameter renaming - e.g., max_completion_tokens → maxTokens, stop → stopSequences
Reasoning transformation - reasoning parameters mapped to model-specific thinking/reasoning structures (Anthropic, Nova)
Tool restructuring - Function definitions converted to Bedrock’s ToolConfig format
Message conversion - System message extraction, tool message grouping, image format adaptation (base64 only)
AWS authentication - Automatic SigV4 request signing with credential chain support
Structured output - response_format converted to specialized tool definitions
Service tier & guardrails - Support for Bedrock-specific performance and safety configurations

Model Family Support

Family	Chat	Responses	Text	Embeddings	Image Generation	Image Edit	Image Variation
Claude (Anthropic)	✅	✅	✅	❌	❌	❌	❌
Nova (Anthropic)	✅	✅	❌	❌	✅	✅	✅
Mistral	✅	✅	✅	❌	❌	❌	❌
Llama	✅	✅	❌	❌	❌	❌	❌
Cohere	✅	✅	❌	✅	❌	❌	❌
Titan	✅	✅	❌	✅	✅	✅	✅
Stability AI	❌	❌	❌	❌	✅	✅	❌

Supported Operations

Operation	Non-Streaming	Streaming	Endpoint
Chat Completions	✅	✅	`converse`
Responses API	✅	✅	`converse`
Text Completions	✅	❌	`invoke`
Embeddings	✅	-	`invoke`
Files	✅	-	S3 (via SDK)
Batch	✅	-	`batch`
List Models	✅	-	`listFoundationModels`
Image Generation	✅	❌	`invoke`
Image Edit	✅	❌	`invoke`
Image Variation	✅	❌	`invoke`
Count Tokens	✅	-	`count-tokens`
Speech (TTS)	❌	❌	-
Transcriptions (STT)	❌	❌	-

Unsupported Operations (❌): Speech (TTS) and Transcriptions (STT) are not supported by the upstream AWS Bedrock API. These return UnsupportedOperationError.Limitations: Images must be in base64 or data URI format (remote URLs not supported). Text completion streaming is not supported.

Beta Headers

For Claude models on Bedrock, Bifrost validates anthropic-beta headers and drops unsupported headers from the request. Supported: computer-use-*, structured-outputs-*, compact-*, context-management-*, interleaved-thinking-*, context-1m-* Not supported: advanced-tool-use-*, mcp-client-*, prompt-caching-scope-*, files-api-*, skills-*, fast-mode-*, redact-thinking-* You can override these defaults per provider via the Beta Headers tab in provider configuration or via beta_header_overrides. See the full support matrix in the Anthropic provider docs.

1. Chat Completions

Request Parameters

Parameter Mapping

Parameter	Transformation	Notes
`max_completion_tokens`	→ `inferenceConfig.maxTokens`	Required field in Bedrock
`temperature`, `top_p`	Direct pass-through to `inferenceConfig`
`stop`	→ `inferenceConfig.stopSequences`	Array of strings
`response_format`	→ Structured output tool (see Structured Output)	Creates `bf_so_*` tool
`tools`	Schema restructured (see Tool Conversion)
`tool_choice`	Type mapped (see Tool Conversion)
`reasoning`	Model-specific thinking config (see Reasoning / Thinking)
`user`	→ `metadata.userID` (if provided)	Bedrock-specific metadata
`service_tier`	→ `serviceModelTier` (if provided)	Performance tier selection
`top_k`	Via `extra_params` (model-specific)	Bedrock-specific sampling

Dropped Parameters

The following parameters are silently ignored: frequency_penalty, presence_penalty, logit_bias, logprobs, top_logprobs, seed, parallel_tool_calls

Extra Parameters

Use extra_params (SDK) or pass directly in request body (Gateway) for Bedrock-specific fields:

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    "messages": [{"role": "user", "content": "Hello"}],
    "guardrailConfig": {
      "guardrailIdentifier": "guardrail-id",
      "guardrailVersion": "1",
      "trace": "enabled"
    },
    "performanceConfig": {
      "latency": "optimized"
    }
  }'

resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
    Provider: schemas.Bedrock,
    Model:    "anthropic.claude-3-5-sonnet-20241022-v2:0",
    Input:    messages,
    Params: &schemas.ChatParameters{
        ExtraParams: map[string]interface{}{
            "guardrailConfig": map[string]interface{}{
                "guardrailIdentifier": "guardrail-id",
                "guardrailVersion": "1",
                "trace": "enabled",
            },
            "performanceConfig": map[string]interface{}{
                "latency": "optimized",
            },
        },
    },
})

Available Extra Parameters:

guardrailConfig - Bedrock guardrail configuration with guardrailIdentifier, guardrailVersion, trace
performanceConfig - Performance optimization with latency (“optimized” or “standard”)
additionalModelRequestFieldPaths - Pass-through for model-specific fields not in standard schema
promptVariables - Variables for prompt templates (if using prompt caching)
requestMetadata - Custom metadata for request tracking

Cache Control

Prompt caching is supported via cache control directives:

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "This context will be cached",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      }
    ],
    "system": [
      {
        "type": "text",
        "text": "You are a helpful assistant",
        "cache_control": {"type": "ephemeral"}
      }
    ]
  }'

resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
    Provider: schemas.Bedrock,
    Model:    "anthropic.claude-3-5-sonnet-20241022-v2:0",
    Input: []schemas.ChatMessage{
        {
            Role: schemas.ChatMessageRoleUser,
            Content: &schemas.ChatMessageContent{
                ContentBlocks: []schemas.ChatContentBlock{
                    {
                        Text: schemas.Ptr("This context will be cached"),
                        CacheControl: &schemas.CacheControl{
                            Type: schemas.Ptr("ephemeral"),
                        },
                    },
                },
            },
        },
    },
    SystemMessages: []schemas.ChatMessage{
        {
            Role: schemas.ChatMessageRoleSystem,
            Content: &schemas.ChatMessageContent{
                ContentBlocks: []schemas.ChatContentBlock{
                    {
                        Text: schemas.Ptr("You are a helpful assistant"),
                        CacheControl: &schemas.CacheControl{
                            Type: schemas.Ptr("ephemeral"),
                        },
                    },
                },
            },
        },
    },
})

Reasoning / Thinking

Documentation: See Bifrost Reasoning Reference Reasoning/thinking support varies by model family:

Anthropic Claude Models

Parameter Mapping:

reasoning.effort → thinkingConfig.type = "enabled" (always enabled when reasoning present)
reasoning.max_tokens → thinkingConfig.budgetTokens (token budget for thinking)

Critical Constraints:

Minimum budget: 1024 tokens required; requests below this fail with error
Dynamic budget: -1 is converted to 1024 automatically

// Request
{"reasoning": {"effort": "high", "max_tokens": 2048}}

// Bedrock conversion
{"thinkingConfig": {"type": "enabled", "budgetTokens": 2048}}

Anthropic Nova Models

Parameter Mapping:

reasoning.effort → reasoningConfig.thinkingLevel (“low” → low, “high” → high)
reasoning.max_tokens → Max reasoning tokens (affects inference configuration)

// Request
{"reasoning": {"effort": "high", "max_tokens": 10000}}

// Bedrock conversion
{"reasoningConfig": {"type": "enabled", "thinkingLevel": "high"}}

Message Conversion

Critical Caveats

System message extraction: System messages are removed from messages array and placed in separate system field
Tool message grouping: Consecutive tool messages are merged into single user message with tool result content blocks
Image format: Only base64/data URI supported; remote image URLs are not supported by Bedrock Converse API
Document support: Bifrost’s Bedrock conversion path currently supports PDF, CSV, DOC, DOCX, XLS, XLSX, HTML, TXT, MD formats

Supported Chat Content Blocks

The Chat Completions request format is OpenAI-compatible for standard blocks (type: "text", type: "image_url", type: "file"). Bifrost converts these blocks to Bedrock Converse blocks internally. Bedrock-specific extensions (for example, standalone cachePoint) are also accepted when using the Bedrock provider.

Block Type	Request Shape (Bifrost/OpenAI)	Bedrock Handling	Support
Text	`{"type":"text","text":"..."}`	Converted to Bedrock `text` block	✅
Image	`{"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}`	Converted to Bedrock `image.source.bytes`	✅ (base64/data URI only)
File	`{"type":"file","file":{...}}`	Converted to Bedrock `document` block	✅
Input audio	`{"type":"input_audio",...}`	Returns `audio input not supported in Bedrock Converse API`	❌
Standalone cache point	`{"cachePoint":{"type":"default"}}` (no outer `type` field)	Converted to Bedrock `cachePoint` marker	✅ (Bedrock-specific extension)

Image Conversion

Request shape (client → Bifrost): type: "image_url" with image_url.url set to a data URI/base64 image
Internal Bedrock shape (Bifrost → Bedrock): Converted to image: { format, source: { bytes } }
URL images: ❌ Not supported - Will fail if attempted
Documents: Converted to document content blocks with MIME types

Image Block Example (`image_url`)

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      }
    ]
  }'

// Note: In the Go SDK, ChatContentBlockTypeImage maps to the OpenAI-compatible "image_url" block.
resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
    Provider: schemas.Bedrock,
    Model:    "anthropic.claude-3-5-sonnet-20241022-v2:0",
    Input: []schemas.ChatMessage{
        {
            Role: schemas.ChatMessageRoleUser,
            Content: &schemas.ChatMessageContent{
                ContentBlocks: []schemas.ChatContentBlock{
                    {
                        Type: schemas.ChatContentBlockTypeText,
                        Text: schemas.Ptr("What is in this image?"),
                    },
                    {
                        Type: schemas.ChatContentBlockTypeImage,
                        ImageURLStruct: &schemas.ChatInputImage{
                            URL: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
                        },
                    },
                },
            },
        },
    },
})

File Block Example (`file` → Bedrock `document`)

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Summarize this document."},
          {
            "type": "file",
            "file": {
              "file_data": "JVBERi0xLjQKJcfs...",
              "filename": "report.pdf",
              "file_type": "application/pdf"
            }
          }
        ]
      }
    ]
  }'

resp, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
    Provider: schemas.Bedrock,
    Model:    "anthropic.claude-3-5-sonnet-20241022-v2:0",
    Input: []schemas.ChatMessage{
        {
            Role: schemas.ChatMessageRoleUser,
            Content: &schemas.ChatMessageContent{
                ContentBlocks: []schemas.ChatContentBlock{
                    {
                        Type: schemas.ChatContentBlockTypeText,
                        Text: schemas.Ptr("Summarize this document."),
                    },
                    {
                        Type: schemas.ChatContentBlockTypeFile,
                        File: &schemas.ChatInputFile{
                            FileData: schemas.Ptr("JVBERi0xLjQKJcfs..."),
                            Filename: schemas.Ptr("report.pdf"),
                            FileType: schemas.Ptr("application/pdf"),
                        },
                    },
                },
            },
        },
    },
})

Note: file_data is raw base64-encoded content (no data: URI prefix, unlike image_url). Formats currently supported by Bifrost’s Bedrock document conversion path: pdf, txt, md, html, csv, doc, docx, xls, xlsx.

Standalone Cache Point Example (Bedrock-specific)

{
  "role": "system",
  "content": [
    {"type": "text", "text": "Long context to cache"},
    {"cachePoint": {"type": "default"}}
  ]
}

This standalone cachePoint block is a Bifrost/Bedrock extension (not OpenAI-standard) and should be used only with the Bedrock provider.

Unsupported Block Notes

input_audio blocks are not supported by Bedrock Converse and return an error.
For chat content conversion, use file.file_data for document payloads. file_url and file_id are not the documented Bedrock chat-content path here.

Cache Control Locations

Cache directives supported on:

System content blocks (entire system message)
User message content blocks (specific parts)
Tool definitions within tool configuration

Tool Conversion

Tool definitions are restructured:

function.name → name (preserved)
function.parameters → inputSchema (Schema format)
function.strict → Dropped (not supported by Bedrock)

Tool Choice Mapping

OpenAI	Bedrock
`"auto"`	`auto` (default)
`"none"`	Omitted (not explicitly supported)
`"required"`	`any`
Specific tool	`{type: "tool", name: "X"}`

Tool Call Handling

Tool calls are converted between formats:

Bifrost → Bedrock: Tool call arguments converted from JSON object to input field
Bedrock → Bifrost: Tool use results with toolUseId, converted back to Bifrost format
Tool results: Merged consecutive tool messages into single user message

Structured Output

Structured output uses a special tool-based approach:

// Request with structured output
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "response",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "number"}
        }
      }
    }
  }
}

// Bedrock conversion (internal)
{
  "tools": [{
    "name": "bf_so_response",
    "description": "Structured output tool",
    "inputSchema": {
      "type": "object",
      "properties": {...}
    }
  }],
  "toolChoice": {"type": "tool", "name": "bf_so_response"}
}

// Response extraction
// Tool use input is extracted and returned as contentStr

Response Conversion

Field Mapping

stopReason → finish_reason: endTurn/stopSequence → stop, maxTokens → length, toolUse → tool_calls
usage.inputTokens + usage.cacheReadInputTokens + usage.cacheWriteInputTokens → prompt_tokens (all cache counts rolled into the total)
Cache token breakdown surfaced in prompt_tokens_details:
- usage.cacheReadInputTokens → prompt_tokens_details.cached_read_tokens
- usage.cacheWriteInputTokens → prompt_tokens_details.cached_write_tokens
usage.outputTokens → completion_tokens
reasoning/thinking blocks → reasoning_details with index, type, text, and signature
Tool call input (object) → arguments (JSON string)

Structured Output Response

When structured output is detected:

Tool call with name bf_so_* is treated as structured output
input object is extracted and returned as contentStr
Removed from toolCalls array

Streaming

Chat Completions Streaming

Event sequence from Bedrock Converse Stream API:

Initial message role: contentBlockIndex and role information
Content block starts: toolUse blocks with toolUseId, name
Content block deltas:
- Text delta: Incremental text content
- Tool use delta: Accumulated tool call arguments (JSON)
- Reasoning delta: Reasoning text and optional signature
Message completion: stopReason and final token counts
Usage metrics: Token counts, cached tokens, performance metrics

Streaming event conversion:

Each Bedrock streaming event → Multiple Bifrost chunks as needed
Tool arguments accumulated across deltas and emitted on block end
Reasoning content emitted with signature if present

Text Completion Streaming

❌ Not supported - AWS Bedrock’s text completion API does not support streaming.

Responses API Streaming

Streaming responses use OpenAI-compatible lifecycle events:

response.created
response.in_progress
content_part.start
content_part.delta
content_part.done
function_call_arguments.delta
function_call_arguments.done
output_item.done

Special handling:

Tool arguments accumulated across deltas
Content block indices mapped to output indices
Synthetic events emitted for text/reasoning content

2. Responses API

The Responses API uses the same underlying converse endpoint but converts between OpenAI’s Responses format and Bedrock’s Messages format.

Request Parameters

Parameter Mapping

Parameter	Transformation
`max_output_tokens`	Renamed to `maxTokens` (via `inferenceConfig`)
`temperature`, `top_p`	Direct pass-through
`instructions`	Becomes system message
`tools`	Schema restructured (see Chat Completions)
`tool_choice`	Type mapped (see Chat Completions)
`reasoning`	Mapped to thinking/reasoning config (see Reasoning / Thinking)
`text`	Converted to `output_format` (Bedrock-specific)
`include`	Via `extra_params` (Bedrock-specific)
`stop`	Via `extra_params`, renamed to `stopSequences`
`truncation`	Auto-set to `"auto"` for computer tools

Extra Parameters

Use extra_params (SDK) or pass directly in request body (Gateway):

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
    "input": "Hello, how are you?",
    "stop": ["###"]
  }'

resp, err := client.ResponsesRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostResponsesRequest{
    Provider: schemas.Bedrock,
    Model:    "anthropic.claude-3-5-sonnet-20241022-v2:0",
    Input:    messages,
    Params: &schemas.ResponsesParameters{
        ExtraParams: map[string]interface{}{
            "stop": []string{"###"},
        },
    },
})

Input & Instructions

Input: String wrapped as user message or array converted to messages
Instructions: Becomes system message (same extraction as Chat Completions)
Cache control: Supported on instructions (system) and input messages

Response Conversion

stopReason → status: endTurn/stopSequence → completed, maxTokens → incomplete
usage.inputTokens is aggregated into input_tokens (same semantics as Chat: Bedrock’s inputTokens + cacheReadInputTokens + cacheWriteInputTokens rolled up into input_tokens); usage.outputTokens → output_tokens (preserved as-is)
Cache tokens: cacheReadInputTokens → input_tokens_details.cached_read_tokens | cacheWriteInputTokens → input_tokens_details.cached_write_tokens
Output items: text → message | toolUse → function_call | thinking → reasoning

Streaming

Event sequence: response.created → response.in_progress → content_part.start → content_part.delta → content_part.done → output_item.done

3. Text Completions (Legacy)

Legacy API using invoke endpoint. Streaming not supported. Only Claude (Anthropic) and Mistral models supported.

Request conversion:

Claude models: Uses Anthropic’s /v1/complete format with prompt wrapping
- prompt auto-wrapped with \n\nHuman: {prompt}\n\nAssistant:
- max_tokens → max_tokens_to_sample
- temperature, top_p direct pass-through
- top_k, stop via extra_params
Mistral models: Uses standard format
- max_tokens → max_tokens
- temperature, top_p direct pass-through
- stop → stop

Response conversion:

Claude: completion → choices[0].text
Mistral: outputs[].text → choices[] (supports multiple)
stopReason → finish_reason

4. Embeddings

Supported embedding models: Titan, Cohere

Request Parameters

Parameter Mapping

Parameter	Transformation	Notes
`input`	Direct pass-through	Text or array of texts
`dimensions`	⚠️ Not supported	Titan has fixed dimensions per model
`encoding_format`	Via `extra_params`	”base64” or “float”

Titan-specific:

No dimension customization
Fixed output size per model version

Cohere-specific:

Reuses Cohere format conversion
Similar parameter mapping to standard Cohere

Response Conversion

Titan: embedding → single embedding vector
Cohere: Reuses Cohere response format with embeddings array
usage.inputTokens → usage.prompt_tokens

5. Image Generation

Supported image generation models: Titan Image Generator v1, Titan Image Generator v2, Nova Canvas v1

Request Conversion

Parameter(Bifrost)	Transformation (Bedrock)
`prompt`	`textToImageParams.text`
`n`	`imageGenerationConfig.numberOfImages`
`negativePrompt`	`textToImageParams.negativeText`
`seed`	`imageGenerationConfig.seed`
`quality`	`imageGenerationConfig.quality` (see Quality Mapping)
`style`	`textToImageParams.style`
`size`	`imageGenerationConfig.width` & `imageGenerationConfig.height`

Quality Mapping

The quality parameter is automatically mapped to Bedrock’s expected format:

Input Value	Bedrock Value	Notes
`"low"`	`"standard"`	Mapped automatically
`"medium"`	`"standard"`	Mapped automatically
`"high"`	`"premium"`	Mapped automatically
`"default"`	`"standard"`	Passed through (case-insensitive)
`"premium"`	`"premium"`	Passed through (case-insensitive)

Response Conversion

Parameter(Bedrock)	Transformation (Bifrost)
`images`	`data.b64_json`

Example Request

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/amazon.nova-canvas-v1:0",
    "prompt": "A futuristic cityscape with a flying car",
    "size": "1024x1024",
    "seed": 123,
    "negative_prompt": "bikes",
    "n": 2
  }'

resp, err := client.ImageGenerationRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostImageGenerationRequest{
    Provider: schemas.Bedrock,
    Model:    "amazon.nova-canvas-v1:0",
    Input: &schemas.ImageGenerationInput{
        Prompt: "A futuristic cityscape with a flying car",
    },
    Params: &schemas.ImageGenerationParameters{
        N: schemas.Ptr(2),
        Seed: schemas.Ptr(123),
        NegativePrompt: schemas.Ptr("bikes"),
        Quality: schemas.Ptr("auto"),
        Style: schemas.Ptr("natural"),
        Size: schemas.Ptr("1024x1024"),
    },
})

Stability AI models

Supported generation models: stability.stable-image-core-v1:1, stability.stable-image-ultra-v1:1 These models use a flat JSON body (not the nested Bedrock taskType structure). Bifrost detects them automatically — any model ID containing "stability." is converted via ToStabilityAIImageGenerationRequest. Request Parameters

Parameter	Type	Required	Notes
`prompt`	string	✅	Text description of the image
`negative_prompt`	string	❌	What to exclude
`seed`	int	❌	Reproducibility seed
`aspect_ratio`	string	❌	e.g. `"16:9"`, `"1:1"`, `"21:9"` — via `aspect_ratio` param or `ExtraParams["aspect_ratio"]`
`output_format`	string	❌	`"png"`, `"jpeg"`, `"webp"` — via `output_format` param

Example Request

Gateway
Go SDK

curl -X POST http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/us.stability.stable-image-ultra-v1:1",
    "prompt": "A majestic mountain range at golden hour",
    "negative_prompt": "blurry, low quality",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "seed": 42
  }'

resp, err := client.ImageGenerationRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostImageGenerationRequest{
    Provider: schemas.Bedrock,
    Model:    "us.stability.stable-image-ultra-v1:1",
    Input: &schemas.ImageGenerationInput{
        Prompt: "A majestic mountain range at golden hour",
    },
    Params: &schemas.ImageGenerationParameters{
        NegativePrompt: schemas.Ptr("blurry, low quality"),
        AspectRatio:    schemas.Ptr("16:9"),
        OutputFormat:   schemas.Ptr("png"),
        Seed:           schemas.Ptr(42),
    },
})

6. Image Edit

Requests use multipart/form-data, not JSON.

Supported image edit models: Titan Image Generator v1, Titan Image Generator v2, Nova Canvas v1 Bedrock supports three image edit task types: INPAINTING, OUTPAINTING, and BACKGROUND_REMOVAL. The type field is required and must be one of these values. Request Parameters

Parameter	Type	Required	Notes
`model`	string	✅	Model identifier (must be Titan or Nova Canvas model)
`type`	string	✅	Edit type: `"inpainting"`, `"outpainting"`, or `"background_removal"`
`prompt`	string	❌	Text description of the edit (required for inpainting/outpainting)
`image[]`	binary	✅	Image file(s) to edit (only first image used)
`mask`	binary	❌	Mask image file (for inpainting/outpainting)
`n`	int	❌	Number of images to generate (1-10, for inpainting/outpainting only)
`size`	string	❌	Image size: `"WxH"` format (e.g., `"1024x1024"`, for inpainting/outpainting only)
`quality`	string	❌	Image quality (for inpainting/outpainting only). See Quality Mapping for supported values.
`cfgScale`	float	❌	CFG scale (via `ExtraParams["cfgScale"]`, for inpainting/outpainting only)
`negative_text`	string	❌	Negative prompt (via `ExtraParams["negative_text"]`, for inpainting/outpainting only)
`mask_prompt`	string	❌	Mask prompt (via `ExtraParams["mask_prompt"]`, for inpainting/outpainting only)
`return_mask`	bool	❌	Return mask in response (via `ExtraParams["return_mask"]`, for inpainting/outpainting only)
`outpainting_mode`	string	❌	Outpainting mode (via `ExtraParams["outpainting_mode"]`, outpainting only): `"DEFAULT"` or `"PRECISE"`

Request Conversion

Task Type Mapping: Params.Type is mapped to taskType:
- "inpainting" → "INPAINTING"
- "outpainting" → "OUTPAINTING"
- "background_removal" → "BACKGROUND_REMOVAL"
- Any other value returns an error: "unsupported type for Bedrock"
Image Conversion: First image in Input.Images is converted to base64: image.Image → base64 string
Task-Specific Parameters:
- INPAINTING: Uses inPaintingParams:
  - prompt → inPaintingParams.text
  - image (base64) → inPaintingParams.image
  - mask (if present) → inPaintingParams.maskImage (base64)
  - negative_text (via ExtraParams) → inPaintingParams.negativeText
  - mask_prompt (via ExtraParams) → inPaintingParams.maskPrompt
  - return_mask (via ExtraParams) → inPaintingParams.returnMask
- OUTPAINTING: Uses outPaintingParams:
  - prompt → outPaintingParams.text
  - image (base64) → outPaintingParams.image
  - mask (if present) → outPaintingParams.maskImage (base64)
  - negative_text (via ExtraParams) → outPaintingParams.negativeText
  - mask_prompt (via ExtraParams) → outPaintingParams.maskPrompt
  - return_mask (via ExtraParams) → outPaintingParams.returnMask
  - outpainting_mode (via ExtraParams, validated to "DEFAULT" or "PRECISE") → outPaintingParams.outPaintingMode
- BACKGROUND_REMOVAL: Uses backgroundRemovalParams:
  - image (base64) → backgroundRemovalParams.image
  - No other parameters supported
Image Generation Config (for INPAINTING and OUTPAINTING only):
- n → imageGenerationConfig.numberOfImages
- size → imageGenerationConfig.width and imageGenerationConfig.height (parsed from "WxH" format)
- quality → imageGenerationConfig.quality (see Quality Mapping)
- cfgScale (via ExtraParams["cfgScale"]) → imageGenerationConfig.cfgScale

Response Conversion

Uses the same response structure as image generation: BedrockImageGenerationResponse → BifrostImageGenerationResponse
Response includes:
- images[]: Array of base64-encoded images
- maskImage: Base64-encoded mask image (if return_mask was true)
- error: Error message (if present)

Endpoint: Same as image generation: invoke endpoint Streaming: Image edit streaming is not supported by Bedrock.

Stability AI models

Requests use multipart/form-data, not JSON.

Stability AI edit models are automatically detected by their model ID (contains "stability."). The task type is inferred from the model name by default, but you can also set the type field explicitly — useful when using deployment aliases. See Type values for explicit task selection below.

Supported models

Model ID	Task	Images required	Prompt
`stability.stable-image-inpaint-v1:0`	inpaint	1 + mask	✅
`stability.stable-outpaint-v1:0`	outpaint	1 (optional mask)	✅
`stability.stable-image-search-recolor-v1:0`	recolor	1	✅
`stability.stable-image-search-replace-v1:0`	search-replace	1	✅
`stability.stable-image-erase-object-v1:0`	erase-object	1 + mask	❌
`stability.stable-image-remove-background-v1:0`	remove-bg	1	❌
`stability.stable-image-control-sketch-v1:0`	control-sketch	1	✅
`stability.stable-image-control-structure-v1:0`	control-structure	1	✅
`stability.stable-image-style-guide-v1:0`	style-guide	1	✅
`stability.stable-style-transfer-v1:0`	style-transfer	2 required	✅
`stability.stable-creative-upscale-v1:0`	upscale-creative	1	✅
`stability.stable-conservative-upscale-v1:0`	upscale-conservative	1	✅
`stability.stable-fast-upscale-v1:0`	upscale-fast	1	❌

Common parameters

Parameter	Type	Required	Notes
`model`	string	✅	Stability AI model ID (see table above)
`image[]`	binary	✅	Input image(s). `style-transfer` requires exactly 2.
`prompt`	string	task-dependent	Required for all tasks except `remove-bg`, `upscale-fast`, and `erase-object`. For these no-prompt operations, set `type` to `remove_background`, `upscale_fast`, or `erase_object` to skip prompt validation at the gateway level.
`negative_prompt`	string	❌	Not applied for: `remove-bg`, `upscale-fast`, `erase-object`
`seed`	int	❌	Not applied for: `remove-bg`, `upscale-fast`
`mask`	binary	task-dependent	Required for: `inpaint`, `erase-object`; ignored for others

Task-specific extra parameters

Pass these via extra_params (Go SDK) or as top-level form fields (Gateway).

Extra parameter	Type	Task(s)
`output_format`	string	All — `"png"`, `"jpeg"`, `"webp"`
`style_preset`	string	inpaint, outpaint, recolor, search-replace, control-sketch, control-structure, style-guide, upscale-creative
`grow_mask`	int	inpaint, recolor, search-replace, erase-object
`left`, `right`, `up`, `down`	int	outpaint — pixels to expand in each direction
`creativity`	float	upscale-creative, upscale-conservative, outpaint
`select_prompt`	string	recolor — which region to recolor
`search_prompt`	string	search-replace — what object to find and replace
`control_strength`	float	control-sketch, control-structure — 0.0–1.0
`aspect_ratio`	string	style-guide — output aspect ratio
`fidelity`	float	style-guide — 0.0–1.0
`style_strength`	float	style-transfer — 0.0–1.0
`composition_fidelity`	float	style-transfer — 0.0–1.0
`change_strength`	float	style-transfer — 0.0–1.0

Style-transfer image order matters. The first image (image[0]) becomes init_image (the content to transform) and the second (image[1]) becomes style_image (the artistic reference). Both images must be non-empty.

Type values for explicit task selection

You can set the type field to override model-name inference. This is especially useful with deployment aliases where the alias name may not contain the Stability AI model pattern.

`type` value	Stability AI task
`inpainting` or `inpaint`	inpaint
`outpainting` or `outpaint`	outpaint
`background_removal` or `remove_background` or `remove_bg`	remove-bg
`erase_object`	erase-object
`upscale_fast`	upscale-fast
`upscale_creative`	upscale-creative
`upscale_conservative`	upscale-conservative
`recolor`	recolor
`search_replace`	search-replace
`control_sketch`	control-sketch
`control_structure`	control-structure
`style_guide`	style-guide
`style_transfer`	style-transfer

Example requests

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-image-inpaint-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "[email protected];type=image/png" \
  -F "prompt=A beautiful garden replacing the masked area" \
  -F "negative_prompt=ugly, blurry" \
  -F "output_format=png"

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-style-transfer-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "image[][email protected];type=image/png" \
  -F "prompt=Apply the artistic style to the content image" \
  -F "style_strength=0.8" \
  -F "composition_fidelity=0.5" \
  -F "change_strength=0.4" \
  -F "output_format=png"

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-outpaint-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "prompt=Extend the scene naturally" \
  -F "left=200" \
  -F "right=200" \
  -F "output_format=png"

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-image-remove-background-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "output_format=png"

No prompt required. Set type=erase_object to skip gateway prompt validation.

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-image-erase-object-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "[email protected];type=image/png" \
  -F "type=erase_object" \
  -F "output_format=png"

No prompt required. Set type=upscale_fast to skip gateway prompt validation.

curl -X POST http://localhost:8080/v1/images/edits \
  -F "model=bedrock/us.stability.stable-fast-upscale-v1:0" \
  -F "image[][email protected];type=image/png" \
  -F "type=upscale_fast" \
  -F "output_format=png"

Endpoint: invoke endpoint (same as all other Bedrock image operations) Streaming: Not supported.

7. Image Variation

Requests use multipart/form-data, not JSON.

Supported image variation models: Titan Image Generator v1, Titan Image Generator v2, Nova Canvas v1 Request Parameters

Parameter	Type	Required	Notes
`model`	string	✅	Model identifier (must be Titan or Nova Canvas model)
`image`	binary	✅	Image file to create variations from (supports multiple images via `image[]`)
`n`	int	❌	Number of images to generate (1-10)
`size`	string	❌	Image size: `"WxH"` format (e.g., `"1024x1024"`)
`quality`	string	❌	Image quality. See Quality Mapping for supported values.
`cfgScale`	float	❌	CFG scale (via `ExtraParams["cfgScale"]`)
`prompt`	string	❌	Prompt/text for variation (via `ExtraParams["prompt"]`)
`negativeText`	string	❌	Negative prompt (via `ExtraParams["negativeText"]`)
`similarityStrength`	float	❌	Similarity strength (via `ExtraParams["similarityStrength"]`): Range 0.2 to 1.0

Request Conversion

Task Type: taskType is set to "IMAGE_VARIATION"
Image Conversion: All images are converted to base64 strings:
- Primary image: Input.Image.Image → base64 string → imageVariationParams.images[0]
- Additional images: ExtraParams["images"] (stored as [][]byte by HTTP handler) → base64 strings → appended to imageVariationParams.images[]
Image Variation Parameters:
- prompt (via ExtraParams["prompt"]) → imageVariationParams.text
- negativeText (via ExtraParams["negativeText"]) → imageVariationParams.negativeText
- similarityStrength (via ExtraParams["similarityStrength"]) → imageVariationParams.similarityStrength (validated to range [0.2, 1.0])
Image Generation Config:
- n → imageGenerationConfig.numberOfImages
- size → imageGenerationConfig.width and imageGenerationConfig.height (parsed from "WxH" format)
- quality (via ExtraParams["quality"]) → imageGenerationConfig.quality (see Quality Mapping)
- cfgScale (via ExtraParams["cfgScale"]) → imageGenerationConfig.cfgScale

Response Conversion

Uses the same response structure as image generation: BedrockImageGenerationResponse → BifrostImageGenerationResponse
Response includes:
- images[]: Array of base64-encoded image variations
- error: Error message (if present)

Endpoint: Same as image generation: invoke endpoint Streaming: Image variation streaming is not supported by Bedrock.

8. Batch API

Request formats: requests array (CustomID + Params) or input_file_id Pagination: Cursor-based with afterId, beforeId, limit Endpoints:

POST /batch - Create batch
GET /batch - List batches
GET /batch/{batch_id} - Retrieve batch
POST /batch/{batch_id}/cancel - Cancel batch

Response: JSONL format with {recordId, modelOutput: {...}} or {recordId, error: {...}} Status mapping:

Bedrock Status	Bifrost Mapping
`Submitted`, `Validating`	`Validating`
`InProgress`	`InProgress`
`Completed`	`Completed`
`Failed`, `PartiallyCompleted`	`Failed`
`Stopping`	`Cancelling`
`Stopped`	`Cancelled`
`Expired`	`Expired`

Note: RFC3339Nano timestamps converted to Unix timestamps, multi-key retry supported

9. Files API

S3-backed file operations. Files are stored in S3 buckets integrated with Bedrock.

Upload: Multipart/form-data with file (required) and filename (optional) Field mapping:

id (file ID)
filename
size_bytes (from S3 object size)
created_at (Unix timestamp from S3 LastModified)
mime_type (derived from content or explicitly set)

Endpoints:

POST /v1/files - Upload
GET /v1/files - List (cursor pagination)
GET /v1/files/{file_id} - Retrieve metadata
DELETE /v1/files/{file_id} - Delete
GET /v1/files/{file_id}/content - Download content

Note: File purpose always "batch", status always "processed"

10. List Models

Request: GET /v1/models (no body) Field mapping:

id (model name with deployment prefix if applicable)
display_name → name
created_at (Unix timestamp)

Pagination: Token-based with NextPageToken, FirstID, LastID Filtering:

Region-based model filtering
Deployment mapping from configuration
Model allowlist support (allowed_models config)

Multi-key support: Results aggregated from all keys, filtered by allowedModels if configured

11. AWS Authentication & Configuration

Bifrost signs every Bedrock request with AWS Signature Version 4 (SigV4). Credentials are resolved in the following priority order, and STS AssumeRole can be layered on top of any of them.

Authentication Methods

1. Explicit Credentials

Provide access_key and secret_key directly in bedrock_key_config. Optionally include a session_token for pre-obtained temporary credentials.

{
  "bedrock_key_config": {
    "access_key": "your-aws-access-key",
    "secret_key": "your-aws-secret-key",
    "session_token": "optional-session-token",
    "region": "us-east-1"
  }
}

2. Default Credential Chain (IAM Role / Instance Profile)

Leave access_key and secret_key empty (or omit them). Bifrost calls AWS LoadDefaultConfig which automatically resolves credentials from the environment in this order:

Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
EKS IRSA (AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN)
ECS task role
EC2 instance profile (IMDS)
~/.aws/credentials default profile

{
  "bedrock_key_config": {
    "region": "us-east-1"
  }
}

3. STS AssumeRole

Set role_arn to assume an IAM role before signing requests. AssumeRole requires a valid source identity — it works when credentials are available either via explicit access_key/secret_key in key config, or via the default credential chain (environment variables, EC2 instance profile, ECS task role, EKS IRSA, etc.). If no credentials are available from either source, AssumeRole will fail.

{
  "bedrock_key_config": {
    "role_arn": "arn:aws:iam::123456789012:role/BedrockRole",
    "external_id": "optional-external-id",
    "session_name": "my-session",
    "region": "us-east-1"
  }
}

Field	Required	Default	Notes
`role_arn`	Yes (for STS)	-	IAM role ARN to assume
`external_id`	No	-	Required when the role’s trust policy demands it
`session_name`	No	`bifrost-session`	Identifies the session in CloudTrail logs

Setup & Configuration

How to Use ARNs and Application Inference Profiles

When using AWS Bedrock inference profiles or application inference profiles, you must split the configuration correctly to avoid UnknownOperationException:

Field	Purpose
`arn`	The ARN prefix (everything before the final `/resource-id`). Required for URL formation when using inference profiles.
`deployments`	Map logical model names to the model ID or inference profile resource ID only — not the full ARN.

Do not put the full ARN in the deployments mapping. The resource ID (e.g., abc12xyz) goes in deployments; the ARN prefix goes in the dedicated arn field. Putting the full ARN in deployments causes malformed URLs and UnknownOperationException.

Application inference profiles — use the resource ID (short alphanumeric suffix) in deployments:

{
  "bedrock_key_config": {
    "access_key": "your-aws-access-key",
    "secret_key": "your-aws-secret-key",
    "session_token": "optional-session-token",
    "region": "eu-west-1",
    "arn": "arn:aws:bedrock:eu-west-1:123456789012:application-inference-profile",
    "deployments": {
      "claude-opus-4-6": "ghi56rst",
      "claude-sonnet-4-5": "jkl78mno"
    }
  }
}

Cross-region inference profiles — use the model identifier (e.g., us.anthropic.claude-3-5-sonnet-v1:0) in deployments:

{
  "bedrock_key_config": {
    "access_key": "your-aws-access-key",
    "secret_key": "your-aws-secret-key",
    "session_token": "optional-session-token",
    "region": "us-east-1",
    "arn": "arn:aws:bedrock:us-east-1:123456789012:inference-profile",
    "deployments": {
      "claude-sonnet": "us.anthropic.claude-3-5-sonnet-v1:0"
    }
  }
}

For detailed instructions on setting up AWS Bedrock authentication including credentials, IAM roles, regions, and deployment mapping, see the quickstart guides:

Gateway
Go SDK

See Provider-Specific Authentication - AWS Bedrock in the Gateway Quickstart for configuration steps using Web UI, API, or config.json.

Endpoints

Runtime API: bedrock-runtime.{region}.amazonaws.com/model/{path}
Control Plane: bedrock.{region}.amazonaws.com (list models)
Batch API: Via bedrock-runtime

12. Error Handling

HTTP Status Mapping:

Status	Bifrost Error Type	Notes
400	`invalid_request_error`	Bad request parameters
401	`authentication_error`	Invalid/expired credentials
403	`permission_denied_error`	Access denied to model/resource
404	`not_found_error`	Model or resource not found
429	`rate_limit_error`	Rate limit exceeded
500	`api_error`	Server error
529	`overloaded_error`	Service overloaded

Error Response Structure:

type BifrostError struct {
    IsBifrostError bool
    StatusCode     *int
    Error: {
        Type:    string    // Error classification
        Message: string    // Human-readable message
        Error:   error     // Underlying error
    }
}

Special Cases:

Context cancellation → RequestCancelled
Request timeout → ErrProviderRequestTimedOut
Streaming errors → Sent via channel with stream end indicator
Response unmarshalling → ErrProviderResponseUnmarshal

Caveats

Image Format Restriction

Severity: High Behavior: Only base64/data URI images supported; remote URLs not supported Impact: Requests with URL-based images fail Code: chat.go:image handling

Minimum Reasoning Budget (Claude)

Severity: High Behavior: reasoning.max_tokens must be >= 1024 Impact: Requests with lower values fail with error Code: chat.go:reasoning validation

System Message Extraction

Severity: High Behavior: System messages removed from array, placed in separate system field Impact: Message array structure differs from input Code: chat.go:message conversion

Tool Message Grouping

Severity: High Behavior: Consecutive tool messages merged into single user message Impact: Message count and structure changes Code: chat.go:tool message handling

Model Family-Specific Parameters

Severity: Medium Behavior: Reasoning/thinking config varies significantly by model family Impact: Parameter mapping differs for Claude vs Nova vs other families Code: chat.go, utils.go:model detection

Text Completion Streaming Not Supported

Severity: Medium Behavior: Text completion streaming returns error Impact: Streaming not available for legacy completions API Code: text.go:streaming

Structured Output via Tool

Severity: Low Behavior: response_format converted to special bf_so_* tool Impact: Tool call count and structure changes internally Code: chat.go:structured output handling

Deployment Region Prefix Handling

Severity: Low Behavior: Model IDs with region prefixes matched against deployment config Impact: Model availability depends on deployment configuration Code: models.go:deployment matching

Overview

Quick Start

SDK Integrations

Providers & Guides

MCP Gateway

Custom plugins

Open Source Features

Enterprise Features

​Overview

​Model Family Support

​Supported Operations

​Beta Headers

​1. Chat Completions

​Request Parameters

​Parameter Mapping

​Dropped Parameters

​Extra Parameters

​Cache Control

​Reasoning / Thinking

​Anthropic Claude Models

​Anthropic Nova Models

​Message Conversion

​Critical Caveats

​Supported Chat Content Blocks

​Image Conversion

​Image Block Example (image_url)

​File Block Example (file → Bedrock document)

​Standalone Cache Point Example (Bedrock-specific)

​Unsupported Block Notes

​Cache Control Locations

​Tool Conversion

​Tool Choice Mapping

​Tool Call Handling

​Structured Output

​Response Conversion

​Field Mapping

​Structured Output Response

​Streaming

​Chat Completions Streaming

​Text Completion Streaming

​Responses API Streaming

​2. Responses API

​Request Parameters

​Parameter Mapping

​Extra Parameters

​Input & Instructions

​Response Conversion

​Streaming

​3. Text Completions (Legacy)

​4. Embeddings

​Request Parameters

​Parameter Mapping

​Response Conversion

​5. Image Generation

​Request Conversion

​Quality Mapping

​Response Conversion

​Example Request

​Stability AI models

​Example Request

​6. Image Edit

​Stability AI models

​Supported models

​Common parameters

​Task-specific extra parameters

​Type values for explicit task selection

​Example requests

​7. Image Variation

​8. Batch API

​9. Files API

​10. List Models

​11. AWS Authentication & Configuration

​Authentication Methods

​1. Explicit Credentials

​2. Default Credential Chain (IAM Role / Instance Profile)

​3. STS AssumeRole

​Setup & Configuration

​How to Use ARNs and Application Inference Profiles

​Endpoints

​12. Error Handling

Overview

Model Family Support

Supported Operations

Beta Headers

1. Chat Completions

Request Parameters

Parameter Mapping

Dropped Parameters

Extra Parameters

Cache Control

Reasoning / Thinking

Anthropic Claude Models

Anthropic Nova Models

Message Conversion

Critical Caveats

Supported Chat Content Blocks

Image Conversion

Image Block Example (`image_url`)

File Block Example (`file` → Bedrock `document`)

Standalone Cache Point Example (Bedrock-specific)

Unsupported Block Notes

Cache Control Locations

Tool Conversion

Tool Choice Mapping

Tool Call Handling

Structured Output

Response Conversion

Field Mapping

Structured Output Response

Streaming

Chat Completions Streaming

Text Completion Streaming

Responses API Streaming

2. Responses API

Request Parameters

Parameter Mapping

Extra Parameters

Input & Instructions

Response Conversion

Streaming

3. Text Completions (Legacy)

4. Embeddings

Request Parameters

Parameter Mapping

Response Conversion

5. Image Generation

Request Conversion

Quality Mapping

Response Conversion

Example Request

Stability AI models

Example Request

6. Image Edit

Stability AI models

Supported models

Common parameters

Task-specific extra parameters

Type values for explicit task selection

Example requests

7. Image Variation

8. Batch API

9. Files API

10. List Models

11. AWS Authentication & Configuration

Authentication Methods

1. Explicit Credentials

2. Default Credential Chain (IAM Role / Instance Profile)

3. STS AssumeRole

Setup & Configuration

How to Use ARNs and Application Inference Profiles

Endpoints

12. Error Handling

Caveats