Introduction

Claude’s API is more than just a text-in, text-out interface. It’s a rich ecosystem designed to give you fine-grained control over how Claude reasons, acts, and remembers. Whether you’re building a customer support bot, a code assistant, or a research tool, understanding the five core areas of the API surface will help you build faster, cheaper, and more reliably.

This guide is for developers who have already completed the Intro to Claude and want to go deeper. We’ll cover each area with practical code examples and best practices.

1. Model Capabilities: Steering Claude’s Output

Model capabilities let you control how Claude reasons and formats responses. The key features include:

• Extended Thinking – Claude can “think” step-by-step before answering, improving accuracy on complex tasks.
• Adaptive Thinking – Claude decides dynamically how much to think (recommended for Opus 4.7).
• Structured Outputs – Force Claude to return JSON, XML, or other structured formats.
• Citations – Ground responses in source documents with exact sentence references.
• Streaming – Receive tokens in real time for a chat-like experience.

Example: Using Extended Thinking with Structured Output

import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    thinking={"type": "enabled", "budget_tokens": 512},
    messages=[
        {"role": "user", "content": "Solve this step by step: 23 * 47"}
    ]
)
print(response.content[0].text)

Tip: Use effort parameter with adaptive thinking to control depth without hardcoding a budget.

2. Tools: Let Claude Take Action

Tools extend Claude’s capabilities beyond text generation. You can define custom tools (functions) that Claude can call, or use built-in tools like:

• Web Search Tool – Fetch real-time information.
• Code Execution Tool – Run Python or JavaScript in a sandbox.
• Computer Use Tool – Control a virtual desktop (beta).
• Memory Tool – Persist information across conversations.

Example: Defining a Custom Tool

def get_weather(location: str) -> str:
    # Simulate weather lookup
    return f"The weather in {location} is sunny, 72°F."
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"]
            }
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather in Tokyo?"}
    ]
)
Claude will respond with a tool_use block
print(response.content)

Pro tip: Use parallel tool use to let Claude call multiple tools in one turn, reducing latency.

3. Tool Infrastructure: Discovery and Orchestration

When you have many tools, you need a way to manage them. Claude’s tool infrastructure includes:

• Tool Runner (SDK) – Automatically executes tool calls and returns results.
• Strict Tool Use – Force Claude to use a specific tool.
• Tool Search – Let Claude pick from a large set of tools dynamically.
• Fine-grained Tool Streaming – Stream tool calls and results token by token.

Example: Using Tool Runner (Python SDK)

from anthropic import Anthropic
from anthropic.types import ToolUseBlock
client = Anthropic()
Define a simple tool
def add(a: int, b: int) -> int:
    return a + b
Use the tool runner (pseudo-code, check SDK docs for exact API)
response = client.beta.tools.run(
    model="claude-sonnet-4-20250514",
    tools=[add],
    messages=[{"role": "user", "content": "What is 5 + 3?"}]
)
print(response.content)

4. Context Management: Keeping Conversations Efficient

Long-running sessions can become expensive and slow. Claude provides:

• Context Windows – Up to 1M tokens for large documents.
• Prompt Caching – Cache repeated system prompts or documents to reduce cost and latency.
• Context Compaction – Summarize or prune old messages.
• Context Editing – Remove or replace specific messages in the history.

Example: Using Prompt Caching

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant. Answer concisely.",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Explain quantum computing in one sentence."}
    ]
)
Subsequent requests with the same system prompt will be faster and cheaper

Note: Caching is only available for certain models and requires the cache_control parameter.

5. Files and Assets: Working with Documents and Images

Claude can process a variety of file types:

• PDF Support – Extract text and layout from PDFs.
• Images and Vision – Analyze images with multimodal models.
• Files API – Upload and reference files in conversations.

Example: Processing a PDF

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."
                }
            ]
        }
    ]
)
print(response.content[0].text)

6. Batch Processing: Save 50% on API Costs

If you have large volumes of non-urgent requests, use the Batch API. It processes requests asynchronously and costs 50% less than standard API calls.

Example: Creating a Batch

batch_response = client.beta.messages.batches.create(
    requests=[
        {
            "custom_id": "req-001",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello"}]
            }
        },
        {
            "custom_id": "req-002",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Goodbye"}]
            }
        }
    ]
)
Poll for results
print(batch_response.id)

Important: Batch processing is not ZDR (Zero Data Retention) eligible. Do not send sensitive data.

Best Practices Summary

Key Takeaways

• Claude’s API is organized into five areas: model capabilities, tools, tool infrastructure, context management, and files. Start with model capabilities and tools, then explore the others to optimize cost and scale.
• Use extended thinking and structured outputs to improve accuracy and reliability on complex tasks.
• Leverage prompt caching and context compaction to keep long-running sessions efficient and affordable.
• Built-in tools like web search and code execution let Claude interact with the outside world without custom infrastructure.
• Batch processing cuts costs by 50% for asynchronous workloads—ideal for data processing, content generation, and evaluation pipelines.