Introduction

Claude is a powerful AI assistant that you can integrate into your own applications, workflows, and products. Whether you're building a chatbot, a code assistant, or an autonomous agent, the Claude API gives you direct access to the same models that power claude.ai.

This guide will take you from zero to your first production-ready integration. You'll learn how to get an API key, make your first call using the Python SDK, understand the core concepts of the Messages API, and decide when to use Managed Agents instead.

By the end, you'll have a solid foundation to build, evaluate, and ship applications powered by Claude.

Prerequisites

Before you start, make sure you have:

• A Claude API account (sign up is free and includes some initial credits)
• Python 3.7+ installed on your machine
• Basic familiarity with Python and REST APIs

Step 1: Get Your API Key

• Log in to the Anthropic Console
• Navigate to API Keys in the left sidebar
• Click Create Key and give it a name (e.g., "My Dev Key")
• Copy the key and store it securely — you won't be able to see it again

Security tip: Never hardcode your API key in source code. Use environment variables or a secrets manager.

Step 2: Choose Your Model

Claude offers three model tiers, each optimized for different use cases:

For your first experiments, start with Sonnet 4.6 — it offers the best balance of capability and speed.

Step 3: Install the Python SDK

Anthropic provides first-party SDKs for Python, TypeScript, Go, Java, Ruby, PHP, and C#. We'll use Python here.

pip install anthropic

Step 4: Make Your First API Call

Create a new Python file (e.g., hello_claude.py) and add the following code:

import anthropic
Initialize the client with your API key
client = anthropic.Anthropic(
    api_key="YOUR_API_KEY_HERE"  # Better: use os.environ["ANTHROPIC_API_KEY"]
)
Send a message
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude! What can you help me build today?"}
    ]
)
Print the response
print(message.content[0].text)

Run it:

python hello_claude.py

You should see Claude's friendly response printed to your terminal.

Understanding the Messages API

The messages.create() method is the core of the Claude API. Here's what each parameter does:

• model: The model ID you want to use (e.g., claude-sonnet-4-6)
• max_tokens: The maximum number of tokens Claude can generate in the response
• messages: An array of conversation turns. Each turn has a role ("user" or "assistant") and content (the text)

Multi-turn conversations

To continue a conversation, simply append new messages to the array:

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-6",
    max_tokens=512,
    messages=messages
)

Advanced Features to Explore

Once you've mastered the basics, the Claude API offers several powerful capabilities:

Extended Thinking

For complex reasoning tasks, you can enable Claude to show its step-by-step thinking:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{"role": "user", "content": "Solve this math problem step by step: 15 * 24 + 7"}]
)

Vision (Image Input)

Claude can analyze images. Pass image data as base64 or use a URL:

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-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What does this chart show?"},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}}
        ]
    }]
)

Tool Use (Function Calling)

Give Claude the ability to call external functions or APIs:

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-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)

Structured Outputs

Request JSON-formatted responses for easier programmatic consumption:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "List three programming languages and their primary use cases as JSON."}]
)

Managed Agents: The Alternative Path

If you don't want to manage conversation state, tool loops, or session history yourself, consider Managed Agents. This is a fully managed infrastructure where you define an agent, and Claude handles the rest.

# Conceptual example — check the API reference for exact syntax
agent = client.agents.create(
    name="Customer Support Bot",
    model="claude-sonnet-4-6",
    instructions="You are a helpful support agent for an e-commerce store.",
    tools=[search_knowledge_base, check_order_status]
)
Start a session
session = agent.sessions.create()
response = session.send_message("I need help with my order #12345")

Managed Agents are ideal for:

• Customer support bots
• Long-running autonomous tasks
• Applications where you want minimal code overhead

Best Practices for Production

1. Use Environment Variables

import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

2. Handle Errors Gracefully

try:
    response = client.messages.create(...)
except anthropic.APIError as e:
    print(f"API error: {e}")
except anthropic.RateLimitError as e:
    print(f"Rate limited, retrying after {e.retry_after} seconds")

3. Implement Prompt Caching

For repeated system prompts or large context, enable caching to reduce costs and latency:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{"type": "text", "text": "You are a coding assistant.", "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "Write a Python function to reverse a string."}]
)

4. Monitor Usage and Costs

Use the Anthropic Console to track:

• Token usage per model
• Cost per request
• Rate limits and errors

Next Steps

Now that you've made your first API call, here's what to explore next:

• Try the Workbench in the Anthropic Console for interactive experimentation
• Review the API Reference for all available parameters
• Check the Cookbook for code samples and patterns
• Explore Quickstarts for deployable starter apps

Key Takeaways

• The Claude API is accessible via simple HTTP calls or first-party SDKs (Python, TypeScript, Go, Java, Ruby, PHP, C#)
• Choose your model based on your use case: Opus for complex reasoning, Sonnet for balanced production workloads, Haiku for high-speed tasks
• The Messages API gives you full control over conversation state and tool loops
• Managed Agents provide a fully managed alternative for autonomous, stateful applications
• Always use environment variables for API keys, implement error handling, and monitor your usage in the Anthropic Console