Claude API: Practical Guide with Python & TypeScript (2026)

Why Use the Claude API?

The Claude API is the most direct way to integrate Anthropic's artificial intelligence into your applications. Unlike the claude.ai web interface, the API gives you full control over:

• →The model used (Opus, Sonnet, Haiku)
• →Generation parameters (temperature, max tokens, stop sequences)
• →Advanced features (tool use, vision, extended thinking, streaming)
• →Integration architecture (real-time, batch, webhooks)

API Architecture

The Claude API is built on a simple REST architecture with a single main endpoint:

POST https://api.anthropic.com/v1/messages

Each request includes:

1. →A model (claude-sonnet-4-20250514, claude-opus-4-20250918, etc.)
2. →Messages (conversation as an array)
3. →Optional parameters (temperature, max_tokens, tools, etc.)

import anthropic

client = anthropic.Anthropic()  # Uses ANTHROPIC_API_KEY

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

Authentication and Configuration

Getting an API Key

1. →Create an account on console.anthropic.com
2. →Navigate to Settings > API Keys
3. →Click Create Key and give it a descriptive name
4. →Copy the key (it won't be displayed again)

Configuring the API Key

# Environment variable (recommended)
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Or in a .env file
echo 'ANTHROPIC_API_KEY=sk-ant-api03-...' >> .env

# Python - Automatic via environment variable
client = anthropic.Anthropic()

# Python - Explicit
client = anthropic.Anthropic(api_key="sk-ant-api03-...")

// TypeScript - Automatic via environment variable
const client = new Anthropic();

// TypeScript - Explicit
const client = new Anthropic({ apiKey: "sk-ant-api03-..." });

The Messages API in Detail

The Messages API is the core of interaction with Claude. Here is the complete structure of a request:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    temperature=0.7,
    system="You are an expert in software architecture.",
    messages=[
        {
            "role": "user",
            "content": "What are the benefits of microservices?"
        },
        {
            "role": "assistant",
            "content": "Microservices offer several key advantages..."
        },
        {
            "role": "user",
            "content": "And the drawbacks?"
        }
    ],
    stop_sequences=["\n\nHuman:"]
)

print(response.content[0].text)
print(f"Tokens: {response.usage.input_tokens} in / {response.usage.output_tokens} out")

Key Parameters

Response Structure

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Microservices offer..."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156
  }
}

Streaming

Streaming allows you to display Claude's response in real time, token by token. Essential for interactive user interfaces.

import anthropic

client = anthropic.Anthropic()

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

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

const client = new Anthropic();

const stream = client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a poem about code." }],
});

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

Streaming Events

Batch API: Bulk Processing

The Batch API lets you send up to 100,000 requests in a single batch, with a 50% cost reduction and a processing time of up to 24 hours.

import anthropic

client = anthropic.Anthropic()

# Create a batch
batch = client.batches.create(
    requests=[
        {
            "custom_id": "req-1",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Summarize this article: ..."}
                ]
            }
        },
        {
            "custom_id": "req-2",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Translate this text: ..."}
                ]
            }
        }
    ]
)

# Check status
status = client.batches.retrieve(batch.id)
print(f"Status: {status.processing_status}")

# Retrieve results when ready
if status.processing_status == "ended":
    for result in client.batches.results(batch.id):
        print(f"{result.custom_id}: {result.result.message.content[0].text}")

When to Use the Batch API?

Official SDKs

Anthropic provides SDKs for the major programming languages:

Java Example

import com.anthropic.client.AnthropicClient;
import com.anthropic.models.*;

AnthropicClient client = AnthropicClient.builder()
    .apiKey(System.getenv("ANTHROPIC_API_KEY"))
    .build();

MessageCreateParams params = MessageCreateParams.builder()
    .model("claude-sonnet-4-20250514")
    .maxTokens(1024)
    .addUserMessage("Hello Claude!")
    .build();

Message message = client.messages().create(params);
System.out.println(message.content().get(0).text());

Go Example

package main

import (
    "context"
    "fmt"
    "github.com/anthropics/anthropic-sdk-go"
)

func main() {
    client := anthropic.NewClient()

    message, err := client.Messages.New(context.Background(),
        anthropic.MessageNewParams{
            Model:     anthropic.ModelClaudeSonnet4_20250514,
            MaxTokens: 1024,
            Messages: []anthropic.MessageParam{
                anthropic.NewUserMessage(
                    anthropic.NewTextBlock("Hello Claude!"),
                ),
            },
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(message.Content[0].Text)
}

Error Handling

The Claude API uses standard HTTP codes and descriptive error messages.

Robust Error Handling

import anthropic
import time

client = anthropic.Anthropic()

def call_claude_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=1024,
                messages=messages
            )
        except anthropic.RateLimitError:
            wait = 2 ** attempt  # Exponential backoff
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
        except anthropic.APIStatusError as e:
            if e.status_code >= 500:
                time.sleep(1)
                continue
            raise
    raise Exception("Maximum number of retries reached")

Rate Limits

Rate limits protect API stability and vary based on your usage tier.

Response headers include your current limits:

anthropic-ratelimit-requests-limit: 4000
anthropic-ratelimit-requests-remaining: 3999
anthropic-ratelimit-requests-reset: 2026-03-10T12:00:30Z
anthropic-ratelimit-tokens-limit: 400000
anthropic-ratelimit-tokens-remaining: 399800

Pricing

Quick calculation: A typical conversation (500 tokens in + 500 tokens out) with Sonnet costs approximately $0.009 — less than one cent.

Common Patterns

Multi-Turn Conversation

conversation = []

def chat(user_message):
    conversation.append({"role": "user", "content": user_message})
    
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=2048,
        system="You are an expert Python development assistant.",
        messages=conversation
    )
    
    assistant_message = response.content[0].text
    conversation.append({"role": "assistant", "content": assistant_message})
    return assistant_message

# Usage
print(chat("How do I create a REST API with FastAPI?"))
print(chat("Add JWT authentication."))
print(chat("Now add tests."))

Structured Output (JSON)

import json

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": """Analyze this text and return a structured JSON:
        
        "The product is excellent, fast delivery but damaged packaging."
        
        Expected format:
        {"sentiment": "positive|negative|mixed", "aspects": [...], "score": 0-10}"""
    }]
)

result = json.loads(response.content[0].text)
print(result)
# {"sentiment": "mixed", "aspects": [...], "score": 7}

System Prompt with Context

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    system="""You are an assistant for the "TechShop" e-commerce platform.

Rules:
- Always respond in English
- Only recommend products from the catalog
- If you don't know the answer, redirect to support

Current catalog:
- MacBook Pro M4: $2,499
- iPhone 16 Pro: $1,299
- iPad Air M3: $799""",
    messages=[
        {"role": "user", "content": "Which laptop would you recommend?"}
    ]
)

Cloud Access

The Claude API is also available through major cloud providers:

Best Practices

1. →Use environment variables for API keys — never hard-code them
2. →Implement retry with exponential backoff to handle transient errors
3. →Monitor your usage via the Anthropic console to avoid surprises
4. →Use streaming for interactive user interfaces
5. →Prefer the Batch API for bulk processing (50% savings)
6. →Enable prompt caching for repetitive system prompts
7. →Choose the right model: Haiku for simple tasks, Sonnet for general use, Opus for complex reasoning

Resources

Read Next

• →Claude API Streaming: Practical Guide — Master SSE streaming for real-time responses
• →Structured Outputs and Strict Mode — Guarantee valid JSON outputs with the strict parameter