Introduction

Claude, developed by Anthropic, is a powerful AI assistant accessible via a robust API. Whether you're building a chatbot, automating workflows, or creating intelligent tools, the Claude API offers the flexibility and performance you need. This guide walks you through everything from initial setup to advanced features like tool use and streaming, with practical code examples in Python and TypeScript.

Getting Started with the Claude API

Prerequisites

• An Anthropic account with API access (sign up at console.anthropic.com)
• Your API key (keep it secure!)
• Python 3.8+ or Node.js 16+

Installation

Python:

pip install anthropic

TypeScript/JavaScript:

npm install @anthropic-ai/sdk

Your First API Call

Here's how to send a simple message to Claude:

Python:

import anthropic
client = anthropic.Anthropic(api_key="your-api-key")
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(message.content[0].text)

TypeScript:

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: 'your-api-key' });
async function main() {
  const message = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, Claude!' }]
  });
  console.log(message.content[0].text);
}
main();

Understanding the Messages API

The Messages API is the core of Claude's interaction model. It supports multi-turn conversations, system prompts, and various content types.

Key Parameters

• model: Choose from models like claude-sonnet-4-20250514 or claude-3-opus-20240229
• max_tokens: Maximum tokens in the response
• messages: Array of message objects with role (user/assistant) and content
• system: Optional system prompt to set Claude's behavior

Multi-turn Conversations

conversation = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "Tell me more about its history."}
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=conversation
)
print(response.content[0].text)

Advanced Features

Streaming Responses

Streaming allows you to receive responses token-by-token for a more interactive experience. Python:

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

TypeScript:

const stream = await client.messages.stream({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a short poem about AI.' }]
}).on('text', (text) => {
  process.stdout.write(text);
});
const finalMessage = await stream.finalMessage();

Tool Use (Function Calling)

Claude can use external tools to perform actions like fetching data or running calculations. Define a tool:

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name, e.g., San Francisco"
                }
            },
            "required": ["location"]
        }
    }
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools
)
Check if Claude wants to use a tool
if response.stop_reason == "tool_use":
    tool_call = response.content[1]  # First is text, second is tool use
    print(f"Tool requested: {tool_call.name}")
    print(f"Arguments: {tool_call.input}")

Structured Outputs

Use structured outputs to get JSON-formatted responses for easier parsing.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "List three famous scientists and their discoveries as JSON."}],
    response_format={"type": "json_object"}
)
import json
data = json.loads(response.content[0].text)
print(data)

Prompt Caching

Reduce costs and latency by caching frequently used prompts.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant specialized in Python programming.",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "Explain list comprehensions."}]
)

Best Practices

1. Handle Stop Reasons

Always check stop_reason to understand why Claude stopped:

• end_turn: Natural completion
• max_tokens: Hit token limit
• tool_use: Claude wants to use a tool
• stop_sequence: Custom stop sequence triggered

2. Manage Context Windows

Claude has a large context window (up to 200K tokens). Use prompt caching and compaction to stay efficient.

3. Reduce Hallucinations

• Use system prompts to ground Claude in facts
• Provide reference material in the prompt
• Enable citations for verifiable responses

4. Optimize for Latency

• Use streaming for real-time applications
• Keep prompts concise
• Use max_tokens to limit response length

Real-World Example: Building a Customer Support Bot

import anthropic
client = anthropic.Anthropic()
SYSTEM_PROMPT = """You are a customer support agent for a SaaS company.
Be polite, concise, and helpful. If you don't know something, say so.
"""
def handle_query(user_message, conversation_history):
    messages = conversation_history + [{"role": "user", "content": user_message}]
    
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=512,
        system=SYSTEM_PROMPT,
        messages=messages
    )
    
    assistant_reply = response.content[0].text
    messages.append({"role": "assistant", "content": assistant_reply})
    
    return assistant_reply, messages
Example usage
history = []
reply, history = handle_query("How do I reset my password?", history)
print(reply)

Conclusion

The Claude API is a versatile tool for building AI-powered applications. Start with simple messaging, then explore streaming for interactivity, tool use for external actions, and structured outputs for data processing. Remember to follow best practices for context management, latency optimization, and error handling.

Key Takeaways

• Start simple: Begin with the Messages API and basic parameters before exploring advanced features like tool use and streaming.
• Leverage streaming: For real-time applications, always use streaming to improve user experience and reduce perceived latency.
• Use tools wisely: Tool use extends Claude's capabilities but requires careful implementation of input validation and error handling.
• Optimize costs: Implement prompt caching and keep prompts concise to minimize token usage.
• Handle errors gracefully: Always check stop reasons and implement retry logic for robust applications.