Chat Completions API¶

Generate conversational AI responses with Amazon Bedrock foundation models—including Claude, Nova, Llama, and more—through an OpenAI-compatible interface.

At a glance¶

• Every Amazon Bedrock chat model behind one schema — Anthropic Claude, Amazon Nova, Meta Llama and the rest of the Converse catalogue, plus the Bedrock Mantle models (OpenAI GPT-5.x, xAI Grok, Google Gemma 4) where it is enabled.
• Multi-modal messages. Images, video, documents and audio alongside text, referenced by HTTPS URL, data URI, s3:// URI, or a file_id from the Files API.
• Reasoning in the dialect your client speaks. reasoning_effort (OpenAI), enable_thinking and thinking_budget (Qwen), thinking (Moonshot) and the OpenRouter reasoning object all reach the same control.
• Prompt caching and stored completions. Cache breakpoints map to Amazon Bedrock cachePoints, and store: true keeps the completion in Amazon Bedrock session storage in your own AWS account.
• Content safety per request. An Amazon Bedrock guardrail applies through a request header or the moderation parameter, on requests served by the Converse API.
• Web search where the model runs one. web_search_options grounds the answer in a live search and cites it in the message annotations — see Web Grounding.
• Differs from OpenAI: logprobs is rejected with 400 while top_logprobs keeps working, n > 1 is not available with streaming, and web_search_options needs a model that runs a web search — it is rejected elsewhere rather than answered ungrounded.

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "messages": [{"role": "user", "content": "Say hello world"}]
  }'

Endpoints¶

Feature compatibility¶

Two outcomes are possible for a parameter no model behind this API can honor, and the Notes column below says which one applies. A parameter that only tunes an answer you can still use — a quality or latency hint, a telemetry opt-in — is accepted and ignored, so a client setting it on every request keeps working. A parameter that is the request — an output format, a modality, or a safety restriction that would silently disappear — is rejected with a 400 naming it, because the alternative is returning something you did not ask for.

Models¶

All models supported by the Amazon Bedrock Converse and Converse Stream API are supported, plus every model served by Bedrock Mantle when enabled — including OpenAI GPT-5.x, xAI Grok, and Google Gemma 4. Requests to Mantle models are passed through natively or converted automatically depending on the model's upstream API support — see Bedrock Mantle below.

Bedrock Mantle¶

Mantle-served requests follow one of three paths, each with its own parameter fidelity:

Model Name Aliases¶

This API supports dynamic model name aliases matching official provider APIs. Models like OpenAI and Anthropic provide dynamic aliases in their official APIs—this gateway supports the same model names, automatically resolving them to Amazon Bedrock model identifiers.

Examples (OpenAI GPT OSS models supported by Bedrock):

• gpt-oss-20b → openai.gpt-oss-20b-1:0

Working with the Chat Completions API¶

Prompt Caching¶

Reduce costs and improve response times by caching frequently-used prompt components across multiple requests. This feature is particularly effective for applications with consistent system prompts, tool definitions, or conversation contexts.

Supported Models:

• Anthropic Claude: Full support for system, messages, and tools caching
• Amazon Nova: Support for system and messages caching
• Moonshot Kimi K3 and OpenAI GPT-6: Automatic — a repeated prompt prefix is cached with no parameter at all, and the cached tokens are reported in usage.prompt_tokens_details.cached_tokens. Cache breakpoints are accepted and ignored. prompt_cache_key is ignored too, except on GPT-6 served by Bedrock Mantle (its default where a configured Region offers it), where it is forwarded to the model as a cache routing key

How to Use:

Set the prompt_cache_key parameter to enable caching:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "prompt_cache_key": "default",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant with extensive knowledge..."
      },
      {"role": "user", "content": "What is 2 + 2?"}
    ]
  }'

Granular Cache Control:

Enable caching for specific prompt sections using dot-separated values:

• "system" - Cache system messages only
• "messages" - Cache conversation history
• "tools" - Cache tool/function definitions (Anthropic Claude only)
• "system.messages" - Cache both system and messages
• "system.tools" - Cache system and tools
• "messages.tools" - Cache messages and tools
• "system.messages.tools" - Cache all components
• Any other non-empty value - Cache all components

{
  "model": "anthropic.claude-fable-5",
  "prompt_cache_key": "system.tools",
  "messages": [...],
  "tools": [...]
}

Benefits:

• Cost Reduction: Cached tokens are billed at a lower rate than regular input tokens
• Lower Latency: Cached prompts eliminate reprocessing time
• Automatic Management: The API handles cache invalidation and updates

Cache Retention (TTL):

Control how long cached prompts persist using the prompt_cache_retention parameter:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "prompt_cache_key": "default",
    "prompt_cache_retention": "24h",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant..."
      },
      {"role": "user", "content": "What is 2 + 2?"}
    ]
  }'

Available Retention Values:

• "in_memory" - Short-term caching (mapped to 5 minutes on Amazon Bedrock)
• "24h" - Long-term caching (mapped to 1 hour on Amazon Bedrock)
• Additional Amazon Bedrock values: "1h", "5m" (provider-specific)

The OpenAI prompt_cache_options object is also accepted: its ttl ("30m") is mapped to a 1 hour Amazon Bedrock retention on Anthropic models (other models use the default 5 minute TTL) when prompt_cache_retention is not set.

Explicit Cache Breakpoints:

Instead of relying on the prompt_cache_key section heuristics, mark the exact cache boundaries with prompt_cache_breakpoint on any content part (text, image_url, input_audio, file, refusal). Each marked part is followed by an Amazon Bedrock cachePoint, so the prompt prefix ending with that part is cached:

{
  "model": "anthropic.claude-fable-5",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "Long reusable instructions...",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "What is 2 + 2?"}
  ]
}

• "mode": "explicit" caches only the marked parts: the prompt_cache_key heuristics are disabled for that request.
• "mode": "implicit" (default) keeps the prompt_cache_key heuristics and honors the marked parts.
• At most 4 cache points are sent per request (Amazon Bedrock limit); the oldest ones are dropped when more are requested.
• Breakpoints on models without prompt caching support are accepted and ignored, as are breakpoints on tool result messages — those never become a cache point, whatever the model — and a cache point that would directly follow a reasoning block, which Amazon Bedrock refuses.

Usage Tracking:

Cached token usage is reported in the response:

{
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 100,
    "total_tokens": 1600,
    "prompt_tokens_details": {
      "cached_tokens": 1200,
      "cache_write_tokens": 300
    }
  }
}

In this example, 1,200 tokens were retrieved from cache and the remaining 300 tokens were processed and written to the cache. cache_write_tokens (an extra field beyond the OpenAI API) reports the tokens written to the cache when the model reports them, on both non-streaming responses and the trailing stream_options.include_usage chunk; it is omitted when no cache write occurred.

System Prompt¶

System prompts define the AI assistant's behavior, personality, and instructions (e.g., "You are a helpful assistant"). Most models support system prompts.

S3 Image Support¶

Access images directly from your S3 buckets without generating pre-signed URLs or downloading files locally.

Supported Formats:

• Images: JPEG, PNG, GIF, WebP

How to Use:

Simply reference your S3 images using the s3:// URI scheme in image_url fields:

{
  "model": "anthropic.claude-fable-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {
          "type": "image_url",
          "image_url": {"url": "s3://my-bucket/images/photo.jpg"}
        }
      ]
    }
  ]
}

Benefits:

• No pre-signed URLs - Direct S3 access without generating temporary URLs
• Security - Images stay in your AWS account with IAM-controlled access
• Performance - Optimized data transfer within AWS infrastructure
• Large images - No size limitations of data URIs or base64 encoding

Files API References (file-id:)¶

The string-overloaded image_url.url, file.file_data, and input_audio.data fields also accept the project-local file-id: URI scheme to reference files previously uploaded via the Files API:

{
  "model": "anthropic.claude-fable-5",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image_url", "image_url": {"url": "file-id:file-0190c51c7de7455d9b8c2efe27dfbf67"}}
    ]
  }]
}

Server Tools¶

Amazon Bedrock system tools are built-in capabilities that foundation models can use directly, without requiring you to implement backend integrations.

How to Use:

Add system tools to your tools array as normal. System tools don't require parameter definitions—just specify the tool name and the model will handle the rest.

Amazon Nova Tools¶

Web Grounding¶

Amazon Nova Web Grounding enables models to search the web for current information, helping answer questions requiring real-time data like news, weather, product availability, or recent events. The model automatically determines when to use web grounding based on the user's query.

Usage: set web_search_options, the standard OpenAI parameter for a grounded answer. An empty object is enough.

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-lite-v1:0",
    "messages": [
      {
        "role": "user",
        "content": "What are the current AWS Regions and their locations?"
      }
    ],
    "web_search_options": {}
  }'

Naming nova_grounding as a function tool does the same thing, and is what a client that only speaks tools can send. Sending both declares the search once.

{"tools": [{"type": "function", "function": {"name": "nova_grounding"}}]}

Response Format:

When using web grounding, the API response includes annotations with URL citations in non-streaming mode:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "The AWS Regions include...",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://aws.amazon.com/about-aws/global-infrastructure/",
            "title": "AWS Global Infrastructure"
          }
        }
      ]
    }
  }]
}

Limitations:

• No streaming citations: URL citation annotations are not emitted in streaming responses.
• web_search_options sub-fields: search_context_size is accepted and ignored — the search runs with the amount the model applies. user_location is rejected with 400: the search cannot be restricted to a location, and running it worldwide would answer something other than what was asked.
• Models without a web search: web_search_options is rejected with 400 on every model that runs no web search of its own, including Mantle-served ones. Use one of the models above, or the web_search tool of the Responses API.

export AWS_BEDROCK_MODEL_REGION_RESTRICT='{"amazon.nova-": ["us-east-1"]}'

Anthropic Claude Server Tools¶

Anthropic Claude models support server-side tools (bash, text editor, memory) that are executed by the model provider. Declare them using the standard OpenAI function tool format: set type to "function" and function.name to the tool name.

Supported Tools by Model:

Usage:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Run a Python script that prints hello world."}
    ],
    "tools": [
      {"type": "function", "function": {"name": "bash"}},
      {"type": "function", "function": {"name": "str_replace_based_edit_tool"}}
    ]
  }'

Tool Parameters:

Some Claude server tools accept additional configuration. Pass tool-specific parameters inside function.parameters:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Edit the file hello.py to print hello world."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "str_replace_based_edit_tool",
          "parameters": {"type": "object", "max_characters": 5000}
        }
      }
    ]
  }'

Reasoning Control¶

This API supports several approaches to control Amazon Bedrock reasoning behavior. Reasoning enables foundation models to break down complex tasks into smaller steps ("chain of thought"), improving accuracy for multi-step analysis, math problems, and complex reasoning tasks. All approaches work with all Amazon Bedrock models that support reasoning capabilities.

OpenAI and DeepSeek API-Compatible Reasoning Parameters¶

Use the reasoning_effort parameter with predefined effort levels. This format is shared by the OpenAI and DeepSeek Chat Completions APIs and works with all Amazon Bedrock models supporting reasoning.

Available Levels:

• none - Disable reasoning (sent as between_tools, their lowest setting, to Claude Sonnet 5.5 and later; accepted but not honored on Claude Opus 5.5 and later, Fable and Mythos, which always reason: the model's default adaptive mode is used, the response still carries reasoning content and its output tokens are still billed; the same applies to OpenAI GPT-6 Astra and GPT-6.1 and later, which reason at their default level, and to gpt-oss, except on Bedrock Mantle, where gpt-oss receives none as sent)
• minimal - Quick responses with minimal reasoning (sent as low to the models without a minimal level: OpenAI GPT-5.x and GPT-6 wherever they are served, and gpt-oss and Moonshot Kimi outside Bedrock Mantle)
• low - Light reasoning for straightforward tasks
• medium - Balanced reasoning for most use cases
• high - Deep reasoning for complex problems
• xhigh - Maximum reasoning for complex problems
• max - Its own (higher) effort tier on Claude Sonnet/Opus 4.6 and later, Fable and Mythos, and on OpenAI GPT-5.x, GPT-6 and Moonshot Kimi K3, which receive it unchanged; collapsed onto the model's top reasoning tier on the fixed-scale models (Claude 3.7 - 4.5, Amazon Nova 2, DeepSeek, Kimi K2, gpt-oss). Claude 4.6 maps xhigh down to high. OpenAI GPT-5.x and GPT-6 get the minimal and none handling above wherever they are served; other models served through Bedrock Mantle receive the level as sent

What You Get:

• reasoning_content field (DeepSeek API-compatible): models include their thinking process in the response. The field name is an operator setting (CHAT_COMPLETIONS_REASONING_FIELD): reasoning_content by default, reasoning for clients written against OpenRouter or vLLM, or none to keep responses strictly OpenAI-shaped.
• Streaming support: choices[].delta.reasoning_content chunks in real time
• No text from recent Claude models: Claude Opus 4.7 and later, Sonnet 5, Fable and Mythos reason without returning the text unless asked for a summary, which this API cannot request, so their reasoning field stays empty while its tokens are billed. Read their reasoning through Messages thinking.display or Responses reasoning.summary

Example:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "reasoning_effort": "high",
    "messages": [{"role": "user", "content": "Solve this complex problem..."}]
  }'

Qwen API-Compatible Reasoning Parameters¶

Use explicit enable_thinking & thinking_budget parameters for fine-grained control over thinking mode. This is a Qwen API-compatible format that works with all Amazon Bedrock models supporting reasoning.

Parameters:

• enable_thinking (boolean): Enable or disable thinking mode
  • Default: Model-specific (usually false)
• thinking_budget (integer): Maximum thinking process length in tokens
  • Only effective when enable_thinking is true
  • Passed to the model as budget_tokens
  • Default: Model's maximum chain-of-thought length

Example:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "enable_thinking": true,
    "thinking_budget": 2000,
    "messages": [{"role": "user", "content": "Solve this complex problem..."}]
  }'

Moonshot API-Compatible Thinking Control¶

The thinking parameter provides a Moonshot API-compatible format for controlling thinking/reasoning on models that support it.

Parameters:

• thinking={"type": "enabled"} — Enable thinking mode
• thinking={"type": "disabled"} — Disable thinking mode

This format is accepted for all reasoning-capable models. Models that don't support this parameter will ignore it.

OpenRouter API-Compatible Reasoning Object¶

The reasoning object groups the same controls into a single field, and include_reasoning toggles whether the reasoning text is returned.

Parameters:

• reasoning.effort (string): Effort level, exactly as reasoning_effort
• reasoning.max_tokens (integer): Reasoning token budget, exactly as thinking_budget (implies enabled)
• reasoning.enabled (boolean): Enable reasoning, exactly as enable_thinking
• reasoning.exclude (boolean): Omit the reasoning text from the response
• include_reasoning (boolean): false is equivalent to reasoning: {"exclude": true}

Example:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "reasoning": {"effort": "high", "exclude": true},
    "messages": [{"role": "user", "content": "Solve this complex problem..."}]
  }'

Replaying Reasoning in a Multi-Turn Conversation¶

Appending the assistant message you just received to messages — the standard multi-turn idiom, and what the DeepSeek API asks for after a tool call — is always accepted, reasoning_content included.

Anthropic Claude models only continue from a thinking passage they can recognise as their own, which a replayed text field is not, so their reasoning is left out of that turn instead. The message content, tool calls and refusal are sent unchanged and the conversation continues normally; only the earlier chain of thought is no longer visible to the model. Every other model family receives the replayed reasoning as-is.

What this does not affect, measured on Claude Haiku 4.5:

• Reasoning on the new turn. The model still thinks, and still returns reasoning_content — the reasoning setting for the turn being generated is independent of the history. It re-derives rather than continuing the earlier chain.
• Tool-call continuations. A turn that carried a tool call is answered correctly with the earlier reasoning left out.
• Prompt caching. Cache hits are unaffected, including when the cache point sits inside the conversation immediately after the turn whose reasoning is left out — measured across three turns, each one reading the previous turn's cache in full and extending it. The omission is the same on every turn, so the cached prefix stays identical and keeps growing.

Provider-Specific Parameters¶

Unlock advanced model 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 foundation model provider.

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.

Examples:

Top K Sampling:

{
  "model": "anthropic.claude-fable-5",
  "messages": [{"role": "user", "content": "Write a poem"}],
  "top_k": 50,
  "temperature": 0.7
}

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='{
  "anthropic.claude-sonnet-5": {
    "anthropic_beta": ["context-management-2025-06-27"]
  }
}'

Behavior:

• Compatible parameters: Forwarded to the model and applied
• Unsupported parameters: Return HTTP 400 with an error message
• Reserved names: model_id and additional_request_fields collide with the gateway's own request-building parameters and are rejected with a 400 invalid_request_error naming the key, instead of being forwarded

Anthropic Claude Features¶

Enable cutting-edge Claude capabilities through Anthropic beta feature flags.

Beta Feature Flags¶

Enable experimental Claude features like interleaved thinking by adding the anthropic_beta array to your request (extended thinking itself is controlled through the reasoning parameters, not a beta flag):

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "messages": [{"role":"user","content":"Summarize the news headline."}],
    "anthropic_beta": ["interleaved-thinking-2025-05-14"]
  }'

Stored Chat Completions¶

Set store: true to persist a chat completion in Amazon Bedrock session storage — same mechanism, region, and KMS setting as stored responses. The returned id then works with the full stored-completion surface:

• GET /v1/chat/completions — list stored completions, sorted by creation time (order, after, limit), filterable by model and by metadata pairs. Metadata filters accept either one metadata[key]=value parameter per key (what the OpenAI SDKs send) or a single metadata={"key": "value"} JSON object of string values, for clients that can only send a whole object in one query parameter. A bare metadata in any other shape is rejected with 400 naming both accepted forms.
• GET /v1/chat/completions/{completion_id} — retrieve the stored completion.
• POST /v1/chat/completions/{completion_id} — replace its metadata (null clears it).
• GET /v1/chat/completions/{completion_id}/messages — list its input messages.
• DELETE /v1/chat/completions/{completion_id} — delete it and its backing session.

store defaults to false on this implementation and is ignored with stream=true or when the server lacks the session storage IAM permissions (a warning is recorded in the request log). Listings scan a capped number of sessions (1,000) in the primary Bedrock region; accounts beyond the cap may see incomplete listings.

Model-Specific Features¶

TwelveLabs Pegasus¶

twelvelabs.pegasus-1-2-v1:0 is a video-understanding model. Because Pegasus accepts exactly one video and one text prompt per call, this API adapts the conversation automatically:

• The latest video found anywhere in the conversation (any role, any position) is forwarded as the video input.
• The latest contiguous run of user text (back to the previous assistant or tool turn) is concatenated and forwarded as the text prompt.
• temperature and max_tokens are forwarded.
• response_format: json_schema is forwarded as Pegasus's structured output.

Silently ignored (no error): system prompts, tools, top_p, stop sequences, and prompt caching.

Upstream format limitation: The OpenAI Chat Completions API has no video_url content part type. To stay fully compatible with standard OpenAI clients, pass the video as an image_url content part — the server detects the video MIME type automatically and routes it to Pegasus correctly.

Video input formats: data:video/mp4;base64,…, https://…, s3://bucket/key, or file-id:…. Videos above 18.75 MB are automatically uploaded to S3.

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "twelvelabs.pegasus-1-2-v1:0",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {"url": "s3://my-bucket/video.mp4"}
          },
          {"type": "text", "text": "Describe what happens in this video."}
        ]
      }
    ]
  }'

Limits and behaviour to know¶

What is rejected with a 400. logprobs when enabled, web_search_options on a model that runs no web search (and its user_location on every model), translation_options, custom (free-form) tools, tool_choice: {"type": "allowed_tools"}, a whitespace-only stop sequence (an Amazon Bedrock limitation), audio output combined with stream: true, and n > 1 combined with stream: true. Each error names the parameter it refuses.

What is accepted and ignored. prediction and verbosity are latency and length hints the Converse API has no equivalent for, the message name participant field has no Converse Message author field to land in, web_search_options.search_context_size only tunes a search that still runs, and stream_options.include_obfuscation never pads the stream. prediction, verbosity, name and stream_options.include_obfuscation are forwarded verbatim on Mantle passthrough models, where the upstream API decides what to do with them.

temperature above 1.0 is served at 1.0. The documented 0–2 range is accepted in full: a higher value is applied at the maximum Amazon Bedrock accepts rather than refused, so 1.5 and 2.0 sample as 1.0 does. Mantle passthrough models receive the value as sent.

What changes on a Mantle-served model. An Amazon Bedrock guardrail is not applied to a Mantle-served request, the moderation and web_search_options parameters are rejected with 400 (ask for the search with the web_search tool of the Responses API instead), and audio synthesis from text output is not performed. Where the model is not chat-native, the request is converted to the Responses or Messages API and a documented set of parameters is dropped or clamped — the three serving paths and their exact parameter fidelity are tabled under Bedrock Mantle.

Reasoning tokens are not split out on Converse-served models. completion_tokens_details is not populated and reasoning tokens are billed inside completion_tokens; Mantle-native models report whatever split their upstream API returns.

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 all headers:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id" \
  -H "X-Amzn-Bedrock-GuardrailVersion: 1" \
  -H "X-Amzn-Bedrock-Trace: enabled" \
  -H "X-Amzn-Bedrock-Service-Tier: priority" \
  -H "X-Amzn-Bedrock-PerformanceConfig-Latency: optimized" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Try it¶

Streaming response:

curl -N -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about the sea."}]
  }'

Multi-modal with image:

{
  "model": "amazon.nova-micro-v1:0",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }
  ]
}

With reasoning:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "reasoning_effort": "low",
    "messages": [{"role": "user", "content": "Solve 12*13"}]
  }'

Response with reasoning:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "reasoning_content": "12 × 10 = 120, plus 12 × 3 = 36 → 156",
      "content": "156"
    }
  }]
}

Next steps¶

Next: Responses API · Models API · Files API · Moderations API