Introduction

Welcome to the Claude API! Whether you're building a chatbot, an AI assistant, or an automated content generator, Claude's powerful language model is ready to help. This guide will take you from zero to your first API call in minutes, then show you the core patterns you'll use in every integration.

By the end of this article, you'll have:

• An Anthropic Console account with API access
• Your first successful API call under your belt
• A clear understanding of the Messages API structure
• A roadmap for exploring more advanced features

Prerequisites

Before you start, you'll need:

• An Anthropic Console account (free to sign up)
• An API key (generated in the Console)
• Basic familiarity with command line or a programming language (Python, TypeScript, or Java)

Step 1: Get Your API Key

• Go to the Anthropic Console
• Sign up or log in
• Navigate to API Keys in the sidebar
• Click Create Key and copy your new key

Security Tip: Treat your API key like a password. Never share it publicly or commit it to version control. Use environment variables instead.

Step 2: Make Your First API Call

Let's start with the simplest possible call: sending a single message and getting a response.

Using cURL (Quick Test)

Open your terminal and run:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Replace $ANTHROPIC_API_KEY with your actual key or set it as an environment variable.

Using Python

First, install the Anthropic SDK:

pip install anthropic

Then create a file called hello_claude.py:

import anthropic
client = anthropic.Anthropic(
    api_key="YOUR_API_KEY"  # Better: use environment variable
)
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=100,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(message.content[0].text)

Run it:

python hello_claude.py

Using TypeScript

Install the SDK:

npm install @anthropic-ai/sdk

Create hello_claude.ts:

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

Run with:

npx ts-node hello_claude.ts

Understanding the Messages API Structure

The Messages API is the core interface for all Claude interactions. Every request follows this pattern:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Your message here"}
  ]
}

Key Parameters

• model: Which Claude model to use (e.g., claude-sonnet-4-20250514, claude-opus-4-20250514)
• max_tokens: Maximum number of tokens in the response
• messages: Array of message objects, each with a role and content

Message Roles

• user: Messages from the end user
• assistant: Claude's responses (used in multi-turn conversations)
• system (optional): A system prompt to set Claude's behavior

Step 3: Multi-Turn Conversations

Real applications need back-and-forth dialogue. Here's how to maintain context:

import anthropic
client = anthropic.Anthropic()
messages = [
    {"role": "user", "content": "What's the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is it known for?"}
]
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=200,
    messages=messages
)
print(response.content[0].text)

Each turn appends to the messages array. Claude uses the full history to generate coherent responses.

Step 4: Using System Prompts

System prompts let you set Claude's behavior, personality, and constraints:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=200,
    system="You are a helpful assistant that speaks like a pirate. Always answer with 'Arr!' at the start.",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)
print(response.content[0].text)
Output: "Arr! The capital of France be Paris, me hearty!"

Step 5: Handling Stop Reasons

Every response includes a stop_reason that tells you why Claude stopped generating. Common values:

• end_turn: Claude finished naturally
• max_tokens: Claude hit the token limit (increase max_tokens or continue the conversation)
• stop_sequence: Claude encountered a custom stop sequence

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=50,
    messages=[
        {"role": "user", "content": "Tell me a long story"}
    ]
)
print(f"Stop reason: {response.stop_reason}")
print(f"Content: {response.content[0].text}")

If you see max_tokens, you can continue the conversation by appending the assistant's response and asking Claude to continue.

Next Steps

You've made your first API call and learned the core patterns. Now explore:

• Models Overview: Compare Claude models by capability and cost
• Features Overview: Browse tools, context management, structured outputs, and more
• Client SDKs: Reference docs for Python, TypeScript, Java, and other libraries
• Extended Thinking: Enable Claude to "think" before responding for complex reasoning tasks
• Tool Use: Give Claude the ability to call external APIs and functions

Troubleshooting Tips

Key Takeaways

• Start with a single API call using cURL, Python, or TypeScript to verify your setup
• Master the Messages API structure: model, max_tokens, and messages array are the three essential parameters
• Use system prompts to control Claude's behavior without cluttering the conversation history
• Handle stop reasons to build robust applications that gracefully handle token limits and natural endings
• Explore further by diving into tools, extended thinking, and streaming for more advanced use cases