Introduction

The Claude API offers a rich surface area for building intelligent applications. Whether you're creating a chatbot, an automated research assistant, or a code analysis tool, understanding the API's core components is essential. This guide breaks down the five key areas of the Claude API: model capabilities, tools, context management, files and assets, and tool infrastructure. You'll learn how each area works, when to use it, and see practical code examples to get started.

1. Model Capabilities: Steering Claude's Output

Model capabilities control how Claude reasons, formats responses, and processes input. The API exposes several powerful features:

Extended Thinking with Adaptive Thinking

Claude can dynamically decide when to "think" more deeply. With the effort parameter, you control the reasoning depth. This is ideal for complex math, logic puzzles, or multi-step analysis.

Example: Using Adaptive Thinking in Python

import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    thinking={
        "type": "enabled",
        "budget_tokens": 1024,
        "effort": "high"  # Options: low, medium, high
    },
    messages=[
        {"role": "user", "content": "Solve this: A bat and a ball cost $1.10 in total. The bat costs $1.00 more than the ball. How much does the ball cost?"}
    ]
)
print(response.content)

Structured Outputs

Claude can return structured data like JSON, making it easy to integrate with your application logic.

Example: Requesting JSON Output

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "List three programming languages and their primary use cases. Return as JSON."}
    ],
    system="Always respond in valid JSON format."
)
import json
data = json.loads(response.content[0].text)
print(data)

Batch Processing for Cost Savings

Batch API calls cost 50% less than standard calls. Use batches for large-scale offline processing like data enrichment or content generation.

# Submit a batch
batch = client.batches.create(
    requests=[
        {
            "custom_id": "req-001",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 256,
                "messages": [{"role": "user", "content": "Summarize this article."}]
            }
        },
        # Add more requests...
    ]
)

2. Tools: Letting Claude Take Action

Tools extend Claude's capabilities beyond text generation. Claude can call functions, fetch web pages, execute code, and even control a computer.

How Tool Use Works

You define tools as JSON schemas. Claude decides when to call them based on the conversation.

Example: Defining a Weather Tool

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["city"]
        }
    }
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What's the weather in Tokyo?"}
    ]
)
Check if Claude wants to use a tool
if response.stop_reason == "tool_use":
    tool_call = response.content[-1]
    print(f"Calling tool: {tool_call.name}")
    print(f"Arguments: {tool_call.input}")

Built-in Tools: Web Search, Code Execution, and More

Claude provides several server-side tools:

• Web Search Tool: Fetch real-time information from the web.
• Code Execution Tool: Run Python or JavaScript code in a sandbox.
• Computer Use Tool: Control a virtual desktop environment.
• Memory Tool: Store and retrieve information across conversations.

Example: Using the Web Search Tool

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[{"type": "web_search"}],
    messages=[
        {"role": "user", "content": "What are the latest AI news from this week?"}
    ]
)

3. Context Management: Keeping Long Sessions Efficient

Claude supports context windows up to 1 million tokens. But managing that context efficiently is key to performance and cost.

Prompt Caching

Cache frequently used system prompts or large context blocks to reduce latency and cost.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant that knows everything about Python programming.",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Explain decorators in Python."}
    ]
)

Context Compaction

For very long conversations, you can compact the context to remove redundancy while preserving key information.

Token Counting

Always check token usage to stay within limits and manage costs.

# Count tokens before sending
from anthropic import Anthropic
client = Anthropic()
token_count = client.count_tokens(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello, world!"}]
)
print(f"Token count: {token_count}")

4. Files and Assets: Working with Documents

Claude can process PDFs, images, and other file types directly.

PDF Support

Upload PDFs for Claude to read, summarize, or extract data from.

import base64
with open("report.pdf", "rb") as f:
    pdf_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data
                    }
                },
                {"type": "text", "text": "Summarize this PDF."}
            ]
        }
    ]
)

Image and Vision Support

Claude can analyze images for object detection, OCR, or visual reasoning.

with open("photo.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": image_data
                    }
                },
                {"type": "text", "text": "Describe what you see in this image."}
            ]
        }
    ]
)

5. Tool Infrastructure: Orchestration at Scale

For complex applications, you need more than individual tools. Claude's tool infrastructure handles discovery, routing, and orchestration.

MCP (Model Context Protocol)

MCP allows Claude to connect to remote servers and discover tools dynamically. This is useful for enterprise environments where tools are hosted on different services.

Tool Combinations

You can combine multiple tools in a single request. For example, use web search to find data, then code execution to analyze it.

tools = [
    {"type": "web_search"},
    {
        "name": "analyze_data",
        "description": "Run Python code to analyze data",
        "input_schema": {
            "type": "object",
            "properties": {
                "code": {"type": "string", "description": "Python code to execute"}
            },
            "required": ["code"]
        }
    }
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    tools=tools,
    messages=[
        {"role": "user", "content": "Find the current population of Tokyo and calculate what 10% growth would be."}
    ]
)

Feature Availability and Lifecycle

Features on the Claude platform follow a lifecycle:

• Beta: Preview features for testing. May have limitations and breaking changes.
• GA (Generally Available): Stable and recommended for production.
• Deprecated: Still functional but not recommended; migration path provided.
• Retired: No longer available.

Always check the Claude API documentation for the latest availability status of each feature.

Best Practices

• Start simple: Begin with model capabilities and one or two tools before adding complexity.
• Use batch processing for non-real-time workloads to save 50% on costs.
• Leverage prompt caching for system prompts and large context blocks.
• Monitor token usage to avoid surprises and optimize your prompts.
• Handle tool calls gracefully — always check stop_reason and process tool outputs before continuing.

Key Takeaways

• The Claude API is organized into five areas: model capabilities, tools, context management, files, and tool infrastructure.
• Adaptive thinking and structured outputs give you fine-grained control over Claude's reasoning and response format.
• Built-in tools like web search and code execution let Claude take real-world actions.
• Prompt caching and batch processing can significantly reduce costs and latency.
• Always check feature availability (Beta vs. GA) before building production applications.