Messages API¶

Generate conversational AI responses with AWS Bedrock foundation models—including Claude, Nova, Llama, and more—through an Anthropic-compatible Messages API interface.

Why Choose Messages API?¶

Quick Start: Available Endpoints¶

Feature Compatibility¶

Model Support¶

All models supported by AWS Bedrock Converse and Converse Stream API are supported.

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 AWS Bedrock model identifiers.

Examples:

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

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-opus-4-6-v1",
    "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-opus-4-6-v1",
  "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_read_input_tokens": 0,
    "output_tokens": 100
  }
}

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.

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-opus-4-6-v1",
  "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

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.

Web Search Tool¶

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).

Supported Models:

• Amazon Nova 2 (e.g., amazon.nova-premier-v1:0): Mapped to nova_grounding

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-premier-v1:0",
    "max_tokens": 2048,
    "messages": [
      {"role": "user", "content": "What are the latest news today?"}
    ],
    "tools": [
      {"type": "web_search_20250305", "name": "web_search"}
    ]
  }'

Claude Server Tools¶

Anthropic Claude models support server-side tools that are executed by the model provider. These tools are passed through to Bedrock via additionalModelRequestFields in their native Anthropic JSON format.

Supported Tools by Model:

Usage:

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

Unsupported Anthropic Server Tools¶

The following Anthropic server tools are not supported via Bedrock:

• code_execution — Code execution sandbox
• web_search — Web search (only available on Nova Premier via nova_grounding)
• web_fetch — Web page fetching
• tool_search — Tool search
• container_upload — Container file upload

Requests using these tools on any Claude model will return a 400 Bad Request error.

Provider-Specific Parameters¶

Unlock advanced model capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to AWS 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 AWS 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": ["extended-thinking-2024-12-12"]
  }
}'

Behavior:

• ✅ Compatible parameters: Forwarded to the model and applied
• ⚠️ Unsupported parameters: Return HTTP 400 with an error message

Anthropic Claude Features¶

Enable cutting-edge Claude capabilities including extended thinking and reasoning.

Extended Thinking¶

Enable extended thinking by passing the anthropic-beta header, just like the official Anthropic API:

curl -X POST "$BASE/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-thinking-2024-12-12" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"Solve a complex problem"}]
  }'

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-opus-4-6-v1",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

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-micro-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-opus-4-6-v1",
    "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?"}
    ]
  }'

Ready to build with AI? Check out the Models API to see all available foundation models!