Chat Completions API¶

This OpenAI-compatible endpoint provides access to AWS Bedrock foundation models—including Claude, Nova, and more—through a familiar interface.

Why Choose Chat Completions?¶

Quick Start: Available Endpoint¶

Feature Compatibility¶

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:

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-sonnet-4-5-20250929-v1:0",
    "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-sonnet-4-5-20250929-v1:0",
  "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

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

In this example, 1,200 tokens were retrieved from cache, with only 300 tokens requiring processing.

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-sonnet-4-5-20250929-v1:0",
  "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

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¶

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-sonnet-4-5-20250929-v1:0",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

AWS Bedrock System Tools¶

AWS Bedrock system tools are built-in capabilities that foundation models can use directly without requiring you to implement backend integrations. Access any AWS Bedrock system tool by adding the systemTool_ prefix to its name—this works for current tools and any future system tools AWS releases.

How to Use:

Add system tools to your tools array using the systemTool_ prefix followed by the tool name. System tools don't require parameter definitions—just specify the tool name and the model will handle the rest.

As AWS releases new system tools, simply use the same systemTool_ prefix pattern to access them.

Amazon Nova 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:

curl -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-premier-v1:0",
    "messages": [
      {
        "role": "user",
        "content": "What are the current AWS Regions and their locations?"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "systemTool_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"
          }
        }
      ]
    }
  }]
}

Use Cases:

• Current Events: Get up-to-date information about news, weather, stock prices, or sports scores
• Dynamic Data: Query information that changes frequently like AWS service availability or product prices
• Verification: Cross-reference facts with current web sources for improved accuracy
• Knowledge Extension: Supplement model training data with real-time information

Benefits:

• Zero Integration: No need to implement or maintain web search APIs
• Automatic Invocation: Models intelligently decide when to use web grounding
• Enhanced Accuracy: Reduce hallucinations with real-time information retrieval
• OpenAI-Compatible: Works seamlessly with standard tool calling patterns

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 OpenAI parameters. The API automatically forwards these to the appropriate model provider via AWS Bedrock.

Examples:

Top K Sampling:

{
  "model": "anthropic.claude-sonnet-4-5-20250929-v1:0"",
  "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-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.

Beta Feature Flags¶

Enable experimental Claude features like extended thinking by adding the anthropic_beta array to your request:

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

Reasoning Control¶

This API supports two different approaches to control AWS 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. Both approaches work with all AWS Bedrock models that support reasoning capabilities.

Option 1: OpenAI-Style Reasoning (reasoning_effort)

Use the reasoning_effort parameter with predefined effort levels. This approach works with all AWS Bedrock models that support reasoning, providing a simple way to control reasoning depth.

Available Levels:

• minimal - Quick responses with minimal reasoning (25% of max tokens)
• low - Light reasoning for straightforward tasks (50% of max tokens)
• medium - Balanced reasoning for most use cases (75% of max tokens)
• high - Deep reasoning for complex problems (100% of max tokens)

Example:

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

Option 2: Qwen-Style Reasoning (enable_thinking + thinking_budget)

Use explicit parameters for fine-grained control over thinking mode. This approach works with all AWS Bedrock models that support reasoning, offering precise control over reasoning behavior and token budgets.

Parameters:

• enable_thinking (boolean): Enable or disable thinking mode
  • Default: Model-specific (usually false)
  • Some models have reasoning always enabled
• 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-4-5-20250929-v1:0",
    "enable_thinking": true,
    "thinking_budget": 2000,
    "messages": [{"role": "user", "content": "Solve this complex problem..."}]
  }'

Using Python SDK:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://your-endpoint/v1"
)

# OpenAI-style reasoning (predefined effort levels)
response = client.chat.completions.create(
    model="anthropic.claude-sonnet-4-5-20250929-v1:0",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "Complex problem..."}]
)

# Qwen-style reasoning (fine-grained control)
response = client.chat.completions.create(
    model="anthropic.claude-sonnet-4-5-20250929-v1:0",
    messages=[{"role": "user", "content": "Complex problem..."}],
    extra_body={
        "enable_thinking": True,
        "thinking_budget": 2000
    }
)

DeepSeek Reasoning Support¶

DeepSeek models with reasoning capabilities are automatically handled—their chain-of-thought reasoning appears in reasoning_content fields without any special configuration, just like DeepSeek's native chat completions endpoint.

What You Get:

• Automatic reasoning: DeepSeek reasoning models automatically include their thinking process
• reasoning_content field: Receive visible reasoning text in assistant messages
• Streaming support: Get choices[].delta.reasoning_content chunks in real-time as the model thinks
• Compatible format: Uses the same DeepSeek-compatible response format

How It Works:

• When using DeepSeek reasoning models, the API automatically surfaces their chain-of-thought
• Non-reasoning models simply omit the reasoning_content field
• No special parameters needed—just use the model and reasoning appears automatically

Try It Now¶

Basic chat completion:

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

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-4-5-20250929-v1:0",
    "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"
    }
  }]
}

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