Anthropic Python SDK

The official Python library for the Anthropic REST API, providing type-safe access to Claude AI models with both sync and async support.

Package Information

• Package Name: anthropic
• Package Type: Python SDK
• Language: Python 3.8+
• Installation: pip install anthropic
• Repository: https://github.com/anthropics/anthropic-sdk-python
• License: MIT

Installation

pip install anthropic

Platform-specific extras:

• pip install anthropic[bedrock] - AWS Bedrock
• pip install anthropic[vertex] - Google Vertex AI
• pip install anthropic[aiohttp] - Alternative async client

Quick Start

Basic Message

from anthropic import Anthropic

client = Anthropic()  # Reads ANTHROPIC_API_KEY from environment

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}]
)

print(message.content[0].text)

Async Message

from anthropic import AsyncAnthropic

client = AsyncAnthropic()
message = await client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Stream Response

with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a story"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Available Models

Claude 4.5 (Latest):

• claude-opus-4-5-20250929 - Most capable
• claude-sonnet-4-5-20250929 - Balanced (recommended)

Claude 3.5:

• claude-3-5-sonnet-20241022 - Previous Sonnet
• claude-3-5-haiku-20241022 - Fast and cost-effective

→ Complete model list and selection guide

Common Tasks

Choose based on your use case:

Basic Messaging

• Simple text conversations
• System prompts
• Multi-turn conversations
• Temperature control

Multimodal Input

• Image analysis (JPG, PNG, GIF, WebP)
• PDF document processing
• Mixed content (text + images + documents)

Tool Integration

• Function calling basics
• Auto-execution with tool_runner
• Async tools
• Error handling in tools

Streaming Responses

• Real-time text streaming
• Event-based processing
• Token usage tracking
• Error handling

Batch Processing

• Process thousands of requests
• 50% cost reduction
• High-throughput scenarios

API Quick Reference

Fast lookup for method signatures and parameters:

Messages API - Core message creation

• create() - Create single message
• stream() - Stream message response
• count_tokens() - Estimate token usage

Streaming API - Real-time response processing

• stream() - Context manager for streaming
• Event types and handling
• Helper methods

Tools API - Function calling

• @beta_tool decorator
• tool_runner() - Auto-execution
• Manual tool handling

Batches API - Async batch processing

• create() - Submit batch
• retrieve() - Check status
• results() - Get outputs

Models API - Model information

• retrieve() - Get model details
• list() - Browse available models

Detailed API Documentation

In-depth reference with all parameters, types, and examples:

Core APIs

• Messages API - Complete messages API reference with all parameters, types, and examples
• Streaming API - Detailed streaming architecture, events, and patterns
• Tools API - Function calling with decorators and manual definitions
• Batches API - Batch processing for high-throughput use cases
• Models API - Model information and selection
• Completions API - Legacy text completions API (deprecated, use Messages API instead)

Implementation Guides

• Getting Started - Installation, authentication, and first steps
• Multimodal Content - Working with images, documents, and PDFs
• Tool Usage - Building agentic workflows with function calling
• Streaming Guide - Advanced streaming patterns and best practices
• Batch Processing - Large-scale async message processing
• Error Handling - Robust error management and retry strategies

Platform Integrations

• AWS Bedrock - Use Claude on AWS infrastructure
• Google Vertex AI - Use Claude on GCP infrastructure
• Azure AI Foundry - Use Claude on Azure infrastructure

Reference Documentation

• Client Configuration - Client initialization, timeouts, retries, HTTP options
• Type System - Complete Pydantic type definitions
• Error Handling - Exception hierarchy and error types
• Pagination - List operation pagination patterns
• Utilities - Helper functions and utilities

Beta Features

Access experimental capabilities via client.beta namespace:

Beta Overview - Introduction to beta features

Message Enhancement Features:

• Extended Thinking - Long-form reasoning with budget control
• Citations - Source attribution for document-based responses
• Web Search - Real-time web information retrieval
• Code Execution - Python sandbox execution
• Computer Use - GUI interaction capabilities
• MCP Integration - Model Context Protocol tools

→ All Message Features

Resource Management:

• Skills API - Create and manage reusable capabilities
• Files API - Upload and manage document files
• Beta Batches - Batch processing with beta features

Client Configuration

Basic Setup

from anthropic import Anthropic

# Environment variable (recommended)
client = Anthropic()  # Uses ANTHROPIC_API_KEY

# Explicit API key
client = Anthropic(api_key="your-api-key")

# Context manager (automatic cleanup)
with Anthropic() as client:
    message = client.messages.create(...)

Common Configurations

import httpx

# Custom timeout
client = Anthropic(timeout=120.0)

# Granular timeout
client = Anthropic(
    timeout=httpx.Timeout(
        connect=10.0,
        read=60.0,
        write=10.0,
        pool=10.0
    )
)

# Retry configuration
client = Anthropic(max_retries=5)

# Custom headers
client = Anthropic(
    default_headers={"X-Custom": "value"}
)

→ Complete configuration reference

Error Handling

Basic Pattern

from anthropic import APIError, RateLimitError

try:
    message = client.messages.create(...)
except RateLimitError as e:
    retry_after = e.response.headers.get("retry-after")
    print(f"Rate limited. Retry after {retry_after}s")
except APIError as e:
    print(f"API error: {e.message}")

Exception Hierarchy

AnthropicError
├── APIError
│   ├── APIStatusError
│   │   ├── BadRequestError (400)
│   │   ├── AuthenticationError (401)
│   │   ├── PermissionDeniedError (403)
│   │   ├── NotFoundError (404)
│   │   ├── RateLimitError (429)
│   │   ├── InternalServerError (≥500)
│   ├── APIConnectionError
│   ├── APITimeoutError
│   └── APIResponseValidationError

→ Complete error reference and retry patterns

→ Error handling guide with advanced patterns

Environment Variables

• ANTHROPIC_API_KEY - API key for authentication (required)
• ANTHROPIC_BASE_URL - Override base URL (optional)
• ANTHROPIC_AUTH_TOKEN - Bearer token alternative (optional)

Platform-specific variables documented in platform guides.

SDK Architecture

Client Hierarchy

• Anthropic / AsyncAnthropic - Main clients for direct API access
• AnthropicBedrock / AsyncAnthropicBedrock - AWS Bedrock integration
• AnthropicVertex / AsyncAnthropicVertex - Google Vertex AI integration
• AnthropicFoundry / AsyncAnthropicFoundry - Azure AI Foundry integration

Resource Structure

client.messages          # Messages resource
  .create()              # Create message
  .stream()              # Stream message
  .count_tokens()        # Count tokens
  .batches               # Batches sub-resource
    .create()            # Create batch
    .retrieve()          # Get batch status
    .list()              # List batches
    .cancel()            # Cancel batch
    .delete()            # Delete batch
    .results()           # Get batch results

client.beta              # Beta features namespace
  .messages              # Beta messages with additional features
    .create()            # Create with beta features
    .stream()            # Stream with beta features
    .tool_runner()       # Auto-execute tools
  .skills                # Skills management
  .files                 # File management

client.models            # Models information
  .retrieve()            # Get model info
  .list()                # List models

Type System

All requests and responses use Pydantic models for type safety:

class Message(BaseModel):
    id: str
    type: Literal["message"]
    role: Literal["assistant"]
    content: list[ContentBlock]
    model: str
    stop_reason: StopReason | None
    usage: Usage

ContentBlock = Union[TextBlock, ToolUseBlock]
StopReason = Literal["end_turn", "max_tokens", "stop_sequence", "tool_use"]

→ Complete type definitions

Decision Guide for Common Scenarios

"I need to send a message to Claude"

→ Basic Messaging or Messages API

"I need to process images or PDFs"

→ Multimodal Input or Multimodal Guide

"I need Claude to call functions/use tools"

→ Tool Integration or Tools API

"I need real-time streaming output"

→ Streaming Responses or Streaming API

"I need to process thousands of messages"

→ Batch Processing Guide or Batches API

"I'm getting errors"

→ Error Reference or Error Handling Guide

"I need extended reasoning/thinking"

→ Beta Overview → Extended Thinking

"I need web search or code execution"

→ Beta Overview → Message Features

"I'm using AWS/GCP/Azure"

→ Platform Integrations → Choose your platform

Package Constants

# Client Configuration Constants
DEFAULT_TIMEOUT: float = 600.0  # 10 minutes default timeout for requests
DEFAULT_MAX_RETRIES: int = 2  # Default number of retry attempts
DEFAULT_CONNECTION_LIMITS: httpx.Limits  # Default HTTP connection pool limits

# Legacy Text Completion Prompt Constants
HUMAN_PROMPT: str = "\n\nHuman:"  # Legacy prompt marker for human messages
AI_PROMPT: str = "\n\nAssistant:"  # Legacy prompt marker for AI responses

# Sentinel Values
NOT_GIVEN: NotGiven  # Sentinel indicating parameter not provided

Note: HUMAN_PROMPT and AI_PROMPT are legacy constants for the deprecated Text Completions API. Use the Messages API instead for new applications.

Support Resources

• API Documentation: https://docs.anthropic.com
• SDK Repository: https://github.com/anthropics/anthropic-sdk-python
• Model Pricing: https://anthropic.com/pricing
• Rate Limits: https://docs.anthropic.com/rate-limits