Introduction

Anthropic's Claude represents a new generation of AI models designed for safe, capable, and reliable text and code generation. Whether you're building a custom chatbot, an agentic coding assistant, or an enterprise workflow automation, the Claude API gives you direct programmatic access to Claude's intelligence.

This guide covers everything you need to go from zero to a working Claude integration. We'll walk through environment setup, the core Messages API, model selection, and the most impactful features—tool use, streaming, and structured outputs.

Prerequisites

Before you start, you'll need:

• An Anthropic Console account
• An API key (generated in Console under API Keys)
• Python 3.8+ or Node.js 18+ installed

Step 1: Make Your First API Call

Let's start by setting up your environment and sending your first message to Claude.

Install the SDK

Python:

pip install anthropic

TypeScript/JavaScript:

npm install @anthropic-ai/sdk

Set Your API Key

Set your API key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Send Your First Message

Python example:

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

TypeScript example:

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
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();

If everything is set up correctly, you'll see Claude's friendly response printed to your console.

Step 2: Understand the Messages API

The Messages API is the primary way to interact with Claude programmatically. It's designed for multi-turn conversations, system prompts, and flexible content types.

Core Request Structure

A request to the Messages API has three essential components:

• model: The Claude model identifier (e.g., claude-sonnet-4-20250514)
• max_tokens: The maximum number of tokens Claude can generate in the response
• messages: An array of message objects, each with a role (user or assistant) and content

Multi-Turn Conversations

To continue a conversation, include the full message history:

messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is its population?"}
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=512,
    messages=messages
)

System Prompts

Use the system parameter to set Claude's behavior and persona:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="You are a helpful coding tutor. Explain concepts simply and provide code examples.",
    messages=[
        {"role": "user", "content": "Explain what a closure is in JavaScript."}
    ]
)

Stop Reasons

Every response includes a stop_reason field that tells you why Claude stopped generating:

• "end_turn": Claude finished naturally
• "max_tokens": The response hit the token limit
• "stop_sequence": Claude encountered a custom stop sequence
• "tool_use": Claude wants to call a tool (more on this later)

Step 3: Choose the Right Model

Anthropic offers several Claude models optimized for different use cases:

Recommendation: Start with claude-sonnet-4-20250514 for most applications. It offers the best balance of intelligence, speed, and cost. Upgrade to Opus for tasks requiring deep reasoning, and switch to Haiku for high-throughput, low-latency scenarios.

Step 4: Explore Key Features

Streaming Responses

For a better user experience, stream responses token by token instead of waiting for the full response:

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

Tool Use (Function Calling)

Claude can call external tools and APIs. Define tools using a JSON schema:

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

Structured Outputs

Force Claude to return valid JSON with a specific schema:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Extract the name, age, and city from this text: John is 30 and lives in New York."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "city": {"type": "string"}
                },
                "required": ["name", "age", "city"]
            }
        }
    }
)
print(response.content[0].text)

Vision (Image Processing)

Claude can analyze images. Pass images as base64-encoded data:

import base64
with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this chart in detail."},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                }
            ]
        }
    ]
)
print(response.content[0].text)

Best Practices

• Set appropriate max_tokens: Don't set it too high for simple tasks—this wastes tokens and increases latency.
• Use system prompts effectively: Be specific about Claude's role, tone, and constraints.
• Handle errors gracefully: Always wrap API calls in try/catch blocks and handle rate limits (HTTP 429) with exponential backoff.
• Cache common responses: Use prompt caching for frequently used system prompts to reduce costs and latency.
• Monitor token usage: Use the usage field in responses to track input and output tokens for cost management.

Next Steps

Now that you have a working Claude integration, explore these advanced topics:

• Extended Thinking: Enable Claude to "think" before responding for complex reasoning tasks.
• Batch Processing: Send multiple requests asynchronously for high-throughput applications.
• Prompt Caching: Reduce latency and cost by caching repeated system prompts or large context.
• Managed Agents: Use Claude Managed Agents for long-running, asynchronous tasks.

Key Takeaways

• The Claude API is accessed via the Messages API, which supports multi-turn conversations, system prompts, and flexible content types.
• Choose your model based on task complexity: Opus for deep reasoning, Sonnet for balanced performance, Haiku for speed and cost efficiency.
• Key features like streaming, tool use, structured outputs, and vision enable powerful, production-ready applications.
• Always handle stop reasons (end_turn, max_tokens, tool_use) to build robust conversational flows.
• Start with the Python or TypeScript SDK, set your API key as an environment variable, and use the Anthropic Console for testing and monitoring.