Claude API

Build applications with the Anthropic Claude API and SDKs.

When to Activate

• Building applications that call the Claude API

• Code imports anthropic (Python) or @anthropic-ai/sdk (TypeScript)

• User asks about Claude API patterns, tool use, streaming, or vision

• Implementing agent workflows with Claude Agent SDK

• Optimizing API costs, token usage, or latency

Model Selection

Model

ID

Best For

Opus 4.1

claude-opus-4-1

Complex reasoning, architecture, research

Sonnet 4

claude-sonnet-4-0

Balanced coding, most development tasks

Haiku 3.5

claude-3-5-haiku-latest

Fast responses, high-volume, cost-sensitive

Default to Sonnet 4 unless the task requires deep reasoning (Opus) or speed/cost optimization (Haiku). For production, prefer pinned snapshot IDs over aliases.

Python SDK

Installation

pip install anthropic

Basic Message

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    messages=[

        {"role": "user", "content": "Explain async/await in Python"}

    ]

)

print(message.content[0].text)

Streaming

with client.messages.stream(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    messages=[{"role": "user", "content": "Write a haiku about coding"}]

) as stream:

    for text in stream.text_stream:

        print(text, end="", flush=True)

System Prompt

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    system="You are a senior Python developer. Be concise.",

    messages=[{"role": "user", "content": "Review this function"}]

)

TypeScript SDK

Installation

npm install @anthropic-ai/sdk

Basic Message

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env

const message = await client.messages.create({

  model: "claude-sonnet-4-0",

  max_tokens: 1024,

  messages: [

    { role: "user", content: "Explain async/await in TypeScript" }

  ],

});

console.log(message.content[0].text);

Streaming

const stream = client.messages.stream({

  model: "claude-sonnet-4-0",

  max_tokens: 1024,

  messages: [{ role: "user", content: "Write a haiku" }],

});

for await (const event of stream) {

  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

    process.stdout.write(event.delta.text);

  }

}

Tool Use

Define tools and let Claude call them:

tools = [

    {

        "name": "get_weather",

        "description": "Get current weather for a location",

        "input_schema": {

            "type": "object",

            "properties": {

                "location": {"type": "string", "description": "City name"},

                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}

            },

            "required": ["location"]

        }

    }

]

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    tools=tools,

    messages=[{"role": "user", "content": "What's the weather in SF?"}]

)

# Handle tool use response

for block in message.content:

    if block.type == "tool_use":

        # Execute the tool with block.input

        result = get_weather(**block.input)

        # Send result back

        follow_up = client.messages.create(

            model="claude-sonnet-4-0",

            max_tokens=1024,

            tools=tools,

            messages=[

                {"role": "user", "content": "What's the weather in SF?"},

                {"role": "assistant", "content": message.content},

                {"role": "user", "content": [

                    {"type": "tool_result", "tool_use_id": block.id, "content": str(result)}

                ]}

            ]

        )

Vision

Send images for analysis:

import base64

with open("diagram.png", "rb") as f:

    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    messages=[{

        "role": "user",

        "content": [

            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},

            {"type": "text", "text": "Describe this diagram"}

        ]

    }]

)

Extended Thinking

For complex reasoning tasks:

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=16000,

    thinking={

        "type": "enabled",

        "budget_tokens": 10000

    },

    messages=[{"role": "user", "content": "Solve this math problem step by step..."}]

)

for block in message.content:

    if block.type == "thinking":

        print(f"Thinking: {block.thinking}")

    elif block.type == "text":

        print(f"Answer: {block.text}")

Prompt Caching

Cache large system prompts or context to reduce costs:

message = client.messages.create(

    model="claude-sonnet-4-0",

    max_tokens=1024,

    system=[

        {"type": "text", "text": large_system_prompt, "cache_control": {"type": "ephemeral"}}

    ],

    messages=[{"role": "user", "content": "Question about the cached context"}]

)

# Check cache usage

print(f"Cache read: {message.usage.cache_read_input_tokens}")

print(f"Cache creation: {message.usage.cache_creation_input_tokens}")

Batches API

Process large volumes asynchronously at 50% cost reduction:

import time

batch = client.messages.batches.create(

    requests=[

        {

            "custom_id": f"request-{i}",

            "params": {

                "model": "claude-sonnet-4-0",

                "max_tokens": 1024,

                "messages": [{"role": "user", "content": prompt}]

            }

        }

        for i, prompt in enumerate(prompts)

    ]

)

# Poll for completion

while True:

    status = client.messages.batches.retrieve(batch.id)

    if status.processing_status == "ended":

        break

    time.sleep(30)

# Get results

for result in client.messages.batches.results(batch.id):

    print(result.result.message.content[0].text)

Claude Agent SDK

Build multi-step agents:

# Note: Agent SDK API surface may change — check official docs

import anthropic

# Define tools as functions

tools = [{

    "name": "search_codebase",

    "description": "Search the codebase for relevant code",

    "input_schema": {

        "type": "object",

        "properties": {"query": {"type": "string"}},

        "required": ["query"]

    }

}]

# Run an agentic loop with tool use

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Review the auth module for security issues"}]

while True:

    response = client.messages.create(

        model="claude-sonnet-4-0",

        max_tokens=4096,

        tools=tools,

        messages=messages,

    )

    if response.stop_reason == "end_turn":

        break

    # Handle tool calls and continue the loop

    messages.append({"role": "assistant", "content": response.content})

    # ... execute tools and append tool_result messages

Cost Optimization

Strategy

Savings

When to Use

Prompt caching

Up to 90% on cached tokens

Repeated system prompts or context

Batches API

50%

Non-time-sensitive bulk processing

Haiku instead of Sonnet

~75%

Simple tasks, classification, extraction

Shorter max_tokens

Variable

When you know output will be short

Streaming

None (same cost)

Better UX, same price

Error Handling

import time

from anthropic import APIError, RateLimitError, APIConnectionError

try:

    message = client.messages.create(...)

except RateLimitError:

    # Back off and retry

    time.sleep(60)

except APIConnectionError:

    # Network issue, retry with backoff

    pass

except APIError as e:

    print(f"API error {e.status_code}: {e.message}")

Environment Setup

# Required

export ANTHROPIC_API_KEY="your-api-key-here"

# Optional: set default model

export ANTHROPIC_MODEL="claude-sonnet-4-0"

Never hardcode API keys. Always use environment variables.