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.

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

Why Choose the Messages API?¶

Available Endpoints¶

Feature Compatibility¶

Model Support¶

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.

Advanced Features¶

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

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

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

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 streaming citation data: Citation information is not emitted in streaming events. The server_tool_use block is streamed as a start event with empty input — no citation delta is produced.
• 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 — except on Claude Opus 5 and later, which support no computer-use tool version: there, computer is passed through as a regular custom tool instead of a server 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": "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.

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": "enabled", "budget_tokens": 1024},
    "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"}, or {"type": "adaptive"}. Alternatively, control reasoning depth with output_config.effort (low, medium, high, xhigh, max).

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": {...}
}

Available Request Headers¶

This endpoint supports standard Bedrock headers for enhanced control over your requests. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

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

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

Try It Now¶

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-fable-5",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
  }'

Response:

{"input_tokens": 13}

Ready to build with AI? Check out the Anthropic Models API to see all available foundation models, or the Models Search API for richer filtering.