Messages API (Anthropic Compatible)¶

Generate conversational AI responses with Amazon Bedrock foundation models—including Claude, Nova, Llama, and more—through an Anthropic-compatible Messages API interface. Served under /anthropic by default; the examples below use $BASE, which includes that prefix.

At a glance¶

• One catalogue, not one vendor — name any chat model your regions serve: Anthropic Claude, Amazon Nova, Meta Llama, and every Bedrock Mantle model when Mantle is enabled.
• Multi-modal input — text, images, video and PDF documents in one conversation, from HTTP URLs, data URIs, s3:// URLs and Files API file-id: references.
• Streaming, tool use, extended thinking, prompt caching — model permitting; see Feature compatibility.
• Bedrock Guardrails and service tiers — content filtering and priority / flex latency selection per request, through request headers.
• Differs from the Anthropic API: max_tokens is optional and a 0 budget still returns one token, inference_geo and container (Agent Skills included) are accepted and ignored, and mcp_servers never opens a connection — see Limits and behaviour to know.
• Differs from the official SDK: anthropic ≥ 1.0 removed temperature, top_p and top_k from messages.create(); the gateway still accepts them on the wire, so send them through extra_body.

export BASE="https://your-host/anthropic"  # <scheme>://<host> + ANTHROPIC_ROUTES_PREFIX

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Endpoints¶

Feature compatibility¶

Models¶

All models supported by the Bedrock Converse and ConverseStream APIs 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-only Claude models are passed through to the upstream Anthropic Messages API; other Mantle models are converted to an OpenAI shape (Responses or Chat Completions). Parameter fidelity differs per path:

Claude Models Name Aliases¶

This API supports dynamic model name aliases matching the official Anthropic API. You can use Claude model names exactly as they appear in Anthropic's documentation, and they will be automatically resolved to the corresponding Bedrock model identifiers.

Examples:

• claude-opus-5 → anthropic.claude-opus-5
• claude-sonnet-5 → anthropic.claude-sonnet-5
• claude-haiku-4-5-20251001 → anthropic.claude-haiku-4-5-20251001-v1:0

For Claude 4 and later, a date-stripped shortcut (e.g. claude-haiku-4-5) is also accepted and resolves to the latest dated variant.

Aliases for non-Anthropic models are also supported as normal.

Wildcard Model Patterns¶

model also accepts a glob pattern — claude-sonnet-*, say — and the server serves the most recently released match. The response's model field always names the concrete model that served the request, streaming and non-streaming alike — never the alias or the pattern the request named.

Working with messages¶

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 without cache_control and reported in usage.cache_read_input_tokens; cache_control markers are accepted and ignored

How to Use:

Add cache_control blocks to the content you want to cache:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a helpful assistant with extensive knowledge...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "What is 2 + 2?"}
    ]
  }'

Granular Cache Control:

Enable caching for specific sections by adding cache_control blocks:

• System messages: Add to system text blocks
• Messages: Add to the last message content block you want cached
• Tools: Add to the last tool definition you want cached (Anthropic Claude only)

{
  "model": "anthropic.claude-fable-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "System instructions...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get weather data",
      "input_schema": {...},
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}

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

Usage Tracking:

Cached token usage is reported in the response:

{
  "usage": {
    "input_tokens": 300,
    "cache_creation_input_tokens": 1200,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 1200,
      "ephemeral_1h_input_tokens": 0
    },
    "cache_read_input_tokens": 0,
    "output_tokens": 100
  }
}

cache_creation splits the same total across the cache entry lifetimes, which are billed at different rates. It is present when a per-TTL split is reported.

In subsequent requests with cache hits:

{
  "usage": {
    "input_tokens": 300,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 1200,
    "output_tokens": 100
  }
}

Context Editing¶

An agent loop grows its prompt with every tool result and thinking block it replays. context_management (context editing) clears the oldest of them before the prompt reaches the model, while your client keeps sending the full history.

The request below replays three weather lookups and keeps only the latest result; a real agent would trigger on input_tokens instead, well below its context window:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 256,
    "tools": [{
      "name": "get_weather",
      "description": "Get the weather for a city",
      "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }],
    "messages": [
      {"role": "user", "content": "What is the weather in Paris, Lyon and Nice?"},
      {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Paris"}}]},
      {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01", "content": "Paris: sunny, 21 degrees, humidity 55%, wind 12 km/h from the west, UV index 5, sunrise 07:31, sunset 19:52, visibility 10 km, pressure 1016 hPa, no rain expected in the next 48 hours, overnight low 12 degrees, air quality good, pollen count moderate, tomorrow similar with a light breeze in the afternoon and scattered high clouds in the evening"}]},
      {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_02", "name": "get_weather", "input": {"city": "Lyon"}}]},
      {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_02", "content": "Lyon: cloudy, 18 degrees, humidity 55%, wind 12 km/h from the west, UV index 5, sunrise 07:31, sunset 19:52, visibility 10 km, pressure 1016 hPa, no rain expected in the next 48 hours, overnight low 12 degrees, air quality good, pollen count moderate, tomorrow similar with a light breeze in the afternoon and scattered high clouds in the evening"}]},
      {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_03", "name": "get_weather", "input": {"city": "Nice"}}]},
      {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_03", "content": "Nice: sunny, 24 degrees, humidity 55%, wind 12 km/h from the west, UV index 5, sunrise 07:31, sunset 19:52, visibility 10 km, pressure 1016 hPa, no rain expected in the next 48 hours, overnight low 12 degrees, air quality good, pollen count moderate, tomorrow similar with a light breeze in the afternoon and scattered high clouds in the evening"}]}
    ],
    "context_management": {
      "edits": [{
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "tool_uses", "value": 2},
        "keep": {"type": "tool_uses", "value": 1}
      }]
    }
  }'

The two oldest results are cleared before the model sees the prompt, and the response says so:

{
  "context_management": {
    "applied_edits": [
      {"type": "clear_tool_uses_20250919", "cleared_input_tokens": 150, "cleared_tool_uses": 2}
    ]
  }
}

Behaviour:

• Claude models apply the edits. The context-management-2025-06-27 flag the Anthropic API requires in anthropic-beta is added for you, so the header is optional here.
• Applied edits are reported in context_management.applied_edits — with the number of tool uses or thinking turns cleared, and the input tokens saved — and, when streaming, on the final message_delta event. The field is present whenever context management is enabled, including when the flag arrives only in anthropic-beta; a model that clears older thinking by default reports that as a clear_thinking_20251015 entry you did not ask for. usage.input_tokens counts the edited prompt, which is what is billed.
• Short tool results are left in place, as the Anthropic API does: a reached trigger over one-line results can still report an empty applied_edits.
• count_tokens counts the edited prompt and reports the unedited count in context_management.original_input_tokens.
• Other models accept the field and ignore it: the conversation reaches the model unedited, the response carries no context_management, and the server log records a warning. Clients such as Claude Code send the field on every turn with thinking on, so refusing it would break them.
• Batch results do not report applied_edits.
• Compaction (compact_20260112) is not available and is refused as an unknown edit type, like any other edit type the API does not define.

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.

Mid-Conversation System Messages¶

Beyond the top-level system parameter, a message may use the system role to steer the model from a specific point in the conversation onward.

{
  "model": "anthropic.claude-opus-5",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello."},
    {"role": "system", "content": "From now on, answer in one word."},
    {"role": "assistant", "content": "Hi."},
    {"role": "user", "content": "How are you?"}
  ]
}

Handling:

• Claude 4.8+, Claude 5+ and later (Opus, Sonnet and Haiku alike), Fable and Mythos (claude-opus-4-8, claude-sonnet-4-9, claude-opus-5, claude-sonnet-5, claude-haiku-5, claude-fable-5, claude-mythos-*): forwarded natively, so the directive applies from its position in the conversation.
• Claude 4.7 and earlier (Opus, Sonnet and Haiku alike) (claude-opus-4-5, claude-sonnet-4-6, claude-haiku-4-7, and every earlier generation down to Claude 2): the content is appended to the system prompt instead, keeping the same request working across every model.

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 source fields:

{
  "model": "anthropic.claude-fable-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {
          "type": "image",
          "source": {
            "type": "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:)¶

Image and document content blocks also accept the project-local file-id: URI scheme in their string-overloaded source.url and source.data fields, to reference a file previously uploaded via the Anthropic Files API:

{
  "type": "image",
  "source": {
    "type": "url",
    "url": "file-id:file_0190c51c7de7455d9b8c2efe27dfbf67"
  }
}

Document Input¶

Send documents as context for the model to analyze and reference. Supports multiple source types:

• Base64 PDF: Inline PDF documents encoded in base64
• URL PDF: PDF documents fetched from HTTP(S) URLs (downloaded server-side)
• Plain text: Raw text content as documents
• Content blocks: Structured content with text and images

Enable citations on document blocks to get precise source references in responses:

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "The capital of France is Paris."
  },
  "title": "Geography",
  "citations": {"enabled": true}
}

When the response streams, each citation arrives as a citations_delta inside a content_block_delta event and belongs to the text block it is sent on, so a streamed answer carries the same citations as the same request answered in one piece:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "citations_delta",
    "citation": {
      "type": "char_location",
      "cited_text": "The capital of France is Paris.",
      "document_index": 0,
      "document_title": "Geography",
      "start_char_index": 0,
      "end_char_index": 31
    }
  }
}

Server Tools¶

Server tools are built-in capabilities that foundation models can use directly without requiring you to implement backend integrations. Different model providers support different server tools through their native tool formats.

Amazon Nova Tools¶

Web Grounding¶

The Anthropic web_search tool is supported on models that declare web search as a system tool. When you include a web_search tool in your request, it is automatically mapped to the model's native system tool (e.g., nova_grounding for Amazon Nova 2 models).

Usage:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-lite-v1:0",
    "messages": [
      {"role": "user", "content": "What are the latest news today?"}
    ],
    "tools": [
      {"type": "web_search_20250305", "name": "web_search"}
    ]
  }'

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

Limitations:

• No citation text in response blocks: Unlike native Anthropic web_search, the web_search_tool_result content block carries only the url and title of each result — never cited_text or encrypted_index. The cited content itself is reflected only through the text content of the response.
• No streamed search metadata: the server_tool_use block is streamed as a start event with empty input, so the search terms are not visible while the answer streams. Any citation the model reports is streamed as a citations_delta event on the text block it supports.
• No search counter in usage: usage.server_tool_use is always omitted, so web_search_requests never carries a number. Count the server_tool_use blocks whose name is web_search instead — each one is a search, answered by a web_search_tool_result block carrying the same tool_use_id. Filter on the name: a model that also runs code emits server_tool_use blocks for that too, so counting them all overstates the searches.
• No search filtering on non-Claude models: Amazon's systemTool grounding has no equivalent for allowed_domains, blocked_domains, max_uses, or user_location. Requests to a system-tool web search model (e.g. Amazon Nova 2) that set any of these fields are rejected with a 400 Bad Request rather than silently running an unfiltered search. Anthropic Claude models forward these fields natively and are unaffected.
• Not served on the OpenAI GPT models: Amazon Bedrock serves their web search on the Bedrock Mantle endpoint alone, and the Messages route reaches them through bedrock-runtime. A web_search tool sent to one is rejected with a 400 Bad Request naming the two ways to route the model to Mantle, rather than reaching the model as a function tool it cannot answer.

Code Interpreter¶

Amazon Nova Code Interpreter enables models to securely execute Python code in isolated sandbox environments. Enable it by passing a code_execution tool, which is automatically mapped to the model's native nova_code_interpreter system tool.

Usage:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-lite-v1:0",
    "messages": [
      {"role": "user", "content": "Calculate the first 10 Fibonacci numbers."}
    ],
    "tools": [
      {"type": "code_execution_20250522", "name": "code_execution"}
    ]
  }'

Anthropic Claude Server Tools¶

Anthropic Claude models support server-side tools that are executed by the model provider. Declare them in their native Anthropic JSON format.

Supported Tools by Model:

On Claude 4.6 and later, a bare computer tool is promoted to the newer computer_20251124 tool type.

Usage:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Run a Python script that prints hello world."}
    ],
    "tools": [
      {"type": "bash_20250124", "name": "bash"},
      {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
    ]
  }'

Unsupported Anthropic Server Tools¶

The following Anthropic server tools are not supported via the classic Bedrock (Converse) path:

• code_execution — Code execution sandbox
• web_search — Web search (available on Amazon Nova models via nova_grounding; the OpenAI GPT-5.x family offers it on /v1/responses only)
• web_fetch — Web page fetching
• tool_search — Tool search
• container_upload — Container file upload

Requests using these tools on Converse-served Claude models will return a 400 Bad Request error. On Mantle-served Claude models (passthrough), server tools are instead forwarded verbatim to the upstream Messages API, which decides support; when a Mantle request must be converted to an OpenAI shape, server tools are rejected with 400.

Browser and Computer Toolsets¶

A toolset declares a whole tool family in a single tools entry — browser_toolset_20260801 and computer_toolset_20260801 are the current ones. The entry carries no name and no input_schema: only its type, an optional cache_control, and a configs map keyed by member name (screenshot, navigate, zoom, …) whose entries take enabled and defer_loading. A member left out of configs keeps the toolset's own default for it.

{
  "tools": [
    {
      "type": "browser_toolset_20260801",
      "configs": {"javascript_exec": {"enabled": false}}
    }
  ]
}

The whole shape validates, on POST /v1/messages, on POST /v1/messages/count_tokens and in a batch request alike:

• toolset_name on tool_use and tool_result blocks — the family a member's call belongs to — is preserved, so a replayed toolset turn stays paired.
• browser_state parts inside a tool_result — the tab inventory, plus the tab_opened, download_started, download_completed and download_failed state changes — are accepted with every field the Anthropic API defines.

Where they run. A Mantle-served Claude model is the only path that can serve them, and the gateway does not decide whether it does: the toolset and the browser_state results answering it are forwarded verbatim, and the upstream Messages API answers. A model that does not offer the toolset answers 400 itself, naming the tool types it does offer. Whether any Mantle-served model currently accepts the 2026 toolset types has not been confirmed here, so treat that path as forwarding rather than as support. Everywhere else — Converse-served models, and a Mantle model whose request is converted to an OpenAI shape — the request is refused with 400 naming the toolset, because a model answering without the browser or the desktop answers a different question. A replayed browser_state result is refused the same way on those paths, rather than being reduced to an empty tool result.

A dated toolset type newer than the two above is accepted and takes the same path, so a client tracking the API ahead of this page is never refused for its version alone.

MCP Connector¶

Anthropic's MCP connector — mcp_servers plus mcp_toolset entries in tools — asks the model to act as an MCP client and call a remote MCP server while it answers. That is not supported here: the models this API serves do not open those connections.

Rather than reject an otherwise valid request, the gateway accepts it and ignores the connector:

• mcp_servers and every mcp_toolset entry are dropped; no connection is made and none of the server's tools can be called. An authorization_token you supply is never forwarded to any backend, and never reaches the logs: not the request_params field (LOG_REQUEST_PARAMS), and not the report of a request rejected as malformed, which names the fields that failed and none of their values.
• Every other tool in tools is kept and behaves normally. A cache_control breakpoint carried by an mcp_toolset is dropped with it, so a request that marked its cache prefix there caches a shorter prefix than intended — put the breakpoint on a tool that survives.
• A tool_choice is dropped when the toolsets were the only entries in tools: the choice had nothing left to select from, and forcing a tool against an empty tools array is refused by the Messages API.
• mcp_tool_use and mcp_tool_result blocks already in the conversation — what a client records from a connector-enabled turn elsewhere, both inside the assistant turn that ran the tool — are accepted and read as an ordinary tool call and its result, so a replayed transcript keeps its meaning. Should the model call that tool again, it comes back as a normal tool_use block for you to run.

To use MCP tools with this API, run the MCP client yourself: connect to the server, declare its tools in tools, and return each result as a tool_result block.

Provider-Specific Parameters¶

Unlock advanced model capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to 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 Anthropic parameters. The API automatically forwards these to the appropriate model provider via Bedrock.

Configuration Options:

Option 1: Per-Request

Add provider-specific parameters directly in your request body.

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-4-5-20250929-v1:0": {
    "anthropic_beta": ["output-128k-2025-02-19"]
  }
}'

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 including extended thinking and reasoning.

Extended Thinking¶

Enable extended thinking with the first-class thinking request parameter, just like the official Anthropic API — no beta header is required:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-5",
    "max_tokens": 2048,
    "thinking": {"type": "adaptive", "display": "summarized"},
    "messages": [{"role":"user","content":"Solve a complex problem"}]
  }'

thinking accepts {"type": "enabled", "budget_tokens": <n>} (the budget must be less than max_tokens), {"type": "disabled"}, {"type": "adaptive"}, or {"type": "between_tools"}. Alternatively, control reasoning depth with output_config.effort (low, medium, high, xhigh, max). An effort alone turns thinking on; beside disabled or between_tools, thinking stays off and the effort only sets how much the answer spends.

display on an enabled or adaptive configuration chooses what the thinking blocks carry: summarized returns a summary of the reasoning, omitted returns empty thinking fields with their signature. Claude Opus 4.7 and later, Sonnet 5, Fable and Mythos omit the text by default, so set "display": "summarized" to read their reasoning; earlier Claude models summarize by default. The thinking tokens are billed the same either way. Other models accept the field and ignore it. The beta updates value is not available and is refused with a 400, with or without its beta header; use summarized or omitted.

On models whose reasoning depth is an effort level rather than a token budget (Amazon Nova 2, DeepSeek V3), budget_tokens turns reasoning on and the depth follows that model's own scale. Set output_config.effort to choose it.

Response with Thinking:

When extended thinking is enabled, the response includes thinking content blocks:

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me think about this step by step..."
    },
    {
      "type": "text",
      "text": "Here's the solution..."
    }
  ],
  "usage": {...}
}

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.

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

Upstream format limitation: The Anthropic Messages API does not define a video content block in its stable spec. To stay fully compatible with standard Anthropic clients, pass the video as an image content block with media_type set to the video MIME type (e.g. video/mp4) — 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/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "twelvelabs.pegasus-1-2-v1:0",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {"type": "url", "url": "s3://my-bucket/video.mp4"}
          },
          {"type": "text", "text": "Describe what happens in this video."}
        ]
      }
    ]
  }'

Limits and behaviour to know¶

inference_geo is accepted and ignored. The gateway routes to the Bedrock regions the deployment configures in AWS_BEDROCK_REGIONS, so a per-request geography cannot change where inference runs. A request that sets it is answered normally, from the configured regions; set the regions to pin data residency.

container is accepted and ignored, in both forms. The identifier string and the object carrying id and skills — the form Agent Skills requests use — both validate and both change nothing: no container is created, reused or returned, no skill is loaded, and the response carries no container object. A request naming skills is answered by the model on its own, so an answer that depends on a skill's instructions will differ from what the Anthropic API returns.

max_tokens is optional. The Anthropic API requires it; here the model's own default output limit applies when the field is absent, so a client that relies on the 400 for a missing field gets an answer instead.

max_tokens: 0 warms the prompt cache, and comes back with one token. The Anthropic API answers a zero budget with an empty completion. Here the request is accepted and the prompt is processed and written to the cache the same way, but the reply carries a single token instead of none, with stop_reason max_tokens. Budget the pre-warm call for that one output token; a negative budget is still rejected with 400. Bedrock Mantle models vary — the Claude passthrough honors the zero exactly, and answers with nothing. A pre-warm asks for no output, so what would describe output is refused with 400 — the same refusal, and the same message, the Anthropic API gives: "stream": true, a tool_choice of "tool" or "any" ("auto" is served), and output_config.format.

max_tokens is capped when only it overflows the context window. An input the window holds alone but not beside max_tokens is answered with the output limited to what the window leaves, and an answer that fills that room stops with stop_reason model_context_window_exceeded. Writer Palmyra and Google Gemma refuse such an input with 400 input length and `max_tokens` exceed context limit. A streamed request is served, or refused, the same way, before its stream starts. A max_tokens filling the window on its own is refused with a plain 400 asking to lower it.

Token counting past the context window is approximate. POST /v1/messages/count_tokens counts an input larger than the model's context window, as the Anthropic API does, and the answer is always above the window, so a client counting to learn whether a conversation still fits learns that it does not. On a model counted exactly, the figure past the window can differ slightly from the Anthropic API's: on Claude Haiku 4.5, a 300,000-token message came within 20 tokens of it, and a 300,000-token tool conversation within 0.4%.

Server tools are counted at their definition's usual size. A request offering web_search, web_fetch, code_execution, tool_search_tool_bm25 or tool_search_tool_regex is counted with the tool's definition at the size the Anthropic API gives it on Claude 4.5 and 4.6 models: a fixed size per tool version, whatever the prompt. An unknown version counts as the latest known one. A history replaying a server tool's calls, results and web search citations is counted too; the pages behind web search results are only known in encrypted form, so a count holding search results can differ from the Anthropic API's by a few percent (within 2% on Claude Haiku 4.5).

Token counting is exact for Claude up to 4.6, and an approximation that errs high elsewhere. POST /v1/messages/count_tokens answers for every text model, and the Claude models served by Bedrock Mantle are counted exactly too. What each approximation guarantees, and how far above the exact count it typically lands, is under Exact and approximate counts; the usage a response reports is always exact.

The official SDK no longer sends the sampling parameters. anthropic ≥ 1.0 removed temperature, top_p and top_k from messages.create(). The gateway still accepts all three on the wire and older clients keep working; with the current SDK, pass them as extra_body={"temperature": …}.

The MCP connector never opens a connection. mcp_servers and mcp_toolset entries are dropped before the request leaves — declare the tools in tools and run them yourself. See MCP Connector for what happens to tool_choice and to an authorization_token.

A server tool a model cannot run is refused, not silently dropped. web_search, code_execution and the Claude computer-use tools answer 400 on a model without support for them, and the Mantle-to-OpenAI conversion path rejects server tools outright — see Server Tools and Bedrock Mantle. The same holds for the browser and computer toolsets and for a replayed browser_state result: outside the models that run them, both answer 400 naming what is unavailable — see Toolsets.

Some models get their system prompt dropped. Models with no system-prompt support (mistral.mistral-7b-instruct-v0:2, mistral.mixtral-8x7b-instruct-v0:1) have system messages removed so the same request works across models; set DROP_UNSUPPORTED_SYSTEM_PROMPT=false to get an error instead.

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¶

Model-Specific Headers¶

Example with all headers:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -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",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Try it¶

Basic message:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Say hello world"}]
  }'

Streaming response:

curl -N -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about the sea."}]
  }'

Multi-modal with image:

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

With tool calling:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-fable-5",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get weather information",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {"role": "user", "content": "What is the weather in Paris?"}
    ]
  }'

Count tokens (without sending a message):

curl -X POST "$BASE/v1/messages/count_tokens" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
  }'

Response:

{"input_tokens": 29}

Next steps¶

Next: Models API · Search Models API · Files API · Message Batches API · Configuration