The Claude API & SDKs

POST /v1/messages

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ]
}

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a senior developer.",
    temperature=0.7,
    top_p=0.9,
    messages=[
        {
            "role": "user",
            "content": "Explain async/await."
        }
    ],
    metadata={"user_id": "user-123"},
    stop_sequences=["\n\nHuman:"]
)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Installation

pip install anthropic

Basic Usage

import anthropic

# Uses ANTHROPIC_API_KEY env var
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user",
         "content": "Write a haiku about Python."}
    ]
)

print(message.content[0].text)
# Indented with care,
# Whitespace speaks louder than words,
# Pythonic and clean.

Async Support

import anthropic
import asyncio

async def main():
    client = anthropic.AsyncAnthropic()

    message = await client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[
            {"role": "user",
             "content": "Explain decorators."}
        ]
    )
    print(message.content[0].text)

asyncio.run(main())

Installation

npm install @anthropic-ai/sdk

Basic Usage

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

const client = new Anthropic();
// Uses ANTHROPIC_API_KEY env var

const message = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Explain TypeScript generics."
    }
  ],
});

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

With Explicit Key

const client = new Anthropic({
  apiKey: process.env.MY_CUSTOM_KEY,
  maxRetries: 3,
  timeout: 60_000, // 60 seconds
});

// Access response metadata
const msg = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 512,
  messages: [
    { role: "user", content: "Hello!" }
  ],
});

console.log(`Tokens used:
  In:  ${msg.usage.input_tokens}
  Out: ${msg.usage.output_tokens}`);

conversation = []

def chat(user_input: str) -> str:
    conversation.append({
        "role": "user",
        "content": user_input
    })

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        system="You are a helpful tutor.",
        messages=conversation
    )

    assistant_msg = response.content[0].text

    conversation.append({
        "role": "assistant",
        "content": assistant_msg
    })

    return assistant_msg

# Usage
chat("What is recursion?")
chat("Can you give me an example?")
chat("How does the call stack work?")

# Simple system prompt
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a senior Python developer. "
           "Respond with clean, well-documented "
           "code. Use type hints throughout.",
    messages=[
        {"role": "user",
         "content": "Write a binary search."}
    ]
)

# System prompt with cache_control
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an expert analyst...",
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ],
    messages=[...]
)

Python Streaming

# Using the stream manager
with client.messages.stream(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user",
         "content": "Tell me a story."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Get final message after stream
final = stream.get_final_message()
print(f"\nTokens: {final.usage}")

TypeScript Streaming

const stream = await client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [
    { role: "user",
      content: "Tell me a story." }
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta"
    && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

const finalMsg = await stream.finalMessage();
console.log(finalMsg.usage);

Base64 Image

import base64

with open("chart.png", "rb") as f:
    img_data = base64.standard_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/png",
                    "data": img_data
                }
            },
            {
                "type": "text",
                "text": "Describe this chart."
            }
        ]
    }]
)

URL Image

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "url",
                    "url": "https://example.com/img.jpg"
                }
            },
            {
                "type": "text",
                "text": "What do you see?"
            }
        ]
    }]
)

Enabling Extended Thinking

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "Prove that sqrt(2) "
                   "is irrational."
    }]
)

# Response contains thinking blocks
for block in response.content:
    if block.type == "thinking":
        print("THINKING:", block.thinking)
    elif block.type == "text":
        print("ANSWER:", block.text)

Creating a Batch

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "req-1",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user",
                     "content": "Summarize AI safety."}
                ]
            }
        },
        {
            "custom_id": "req-2",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user",
                     "content": "Explain RLHF."}
                ]
            }
        }
    ]
)
print(batch.id)  # batch_abc123

Polling & Results

# Check status
batch = client.messages.batches.retrieve(
    batch.id
)
print(batch.processing_status)
# "in_progress" or "ended"

# Iterate results when complete
if batch.processing_status == "ended":
    for result in client.messages.batches \
            .results(batch.id):
        print(result.custom_id)
        if result.result.type == "succeeded":
            msg = result.result.message
            print(msg.content[0].text)

Count Tokens API

# Count tokens before sending
count = client.messages.count_tokens(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user",
         "content": "Hello, how are you?"}
    ],
    system="You are helpful."
)
print(count.input_tokens)  # e.g., 18

# Check usage after response
response = client.messages.create(...)
print(f"Input:  {response.usage.input_tokens}")
print(f"Output: {response.usage.output_tokens}")
total_cost = (
    response.usage.input_tokens * 3 / 1_000_000
    + response.usage.output_tokens * 15 / 1_000_000
)
print(f"Cost: ${total_cost:.4f}")

Python Error Handling

import anthropic
from anthropic import (
    APIError,
    RateLimitError,
    APIConnectionError
)

client = anthropic.Anthropic(
    max_retries=3  # Auto-retries built in
)

try:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{"role":"user",
                   "content":"Hello"}]
    )
except RateLimitError as e:
    print(f"Rate limited: {e.status_code}")
    # SDK auto-retries with backoff
except APIError as e:
    print(f"API error {e.status_code}: {e}")
except APIConnectionError:
    print("Network connectivity issue")

Enabling Caching

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_REFERENCE_DOC,  # 10K tokens
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ],
    messages=[
        {"role": "user",
         "content": "Summarize section 3."}
    ]
)

# Check cache performance
u = response.usage
print(f"Cache write: {u.cache_creation_input_tokens}")
print(f"Cache read:  {u.cache_read_input_tokens}")
print(f"Uncached:    {u.input_tokens}")

Classification with Claude

def classify_text(text: str) -> dict:
    response = client.messages.create(
        model="claude-haiku-3-5-20241022",
        max_tokens=100,
        system="""Classify the given text into
exactly one category: positive, negative,
or neutral. Respond with JSON only:
{"sentiment": "...", "confidence": 0.0}""",
        messages=[
            {"role": "user", "content": text}
        ]
    )
    return json.loads(
        response.content[0].text
    )

result = classify_text(
    "This product exceeded my expectations!"
)
# {"sentiment": "positive",
#  "confidence": 0.95}

Multi-label Classification

def tag_support_ticket(ticket: str):
    response = client.messages.create(
        model="claude-haiku-3-5-20241022",
        max_tokens=200,
        system="""Tag the support ticket.
Return JSON: {"priority": "low|med|high",
"category": "billing|technical|account",
"requires_human": true|false}""",
        messages=[
            {"role": "user",
             "content": ticket}
        ]
    )
    return json.loads(
        response.content[0].text
    )

Pricing (per million tokens)

Batch API: 50% discount. Prompt caching read: 90% discount.

Usage Tiers