If you’ve been curious about building with AI and want something beginner-friendly, the Claude API from Anthropic is a fantastic place to start. Claude is an AI assistant built with safety and helpfulness in mind, and the API makes it easy to integrate natural language understanding into your apps with just a few lines of code.

I recently explored the Anthropic API Fundamentals course, and it’s one of the clearest intros I’ve seen. In this article, I’ll walk you through the basics of using the Claude API—from making your first call to understanding how messages work. Whether you're just starting with AI or looking for a quick Claude crash course, you’re in the right place.

Setting Up the Claude SDK (Python)

Before diving in, let’s make sure your development environment is ready to use the Claude Python SDK.

Check Your Python Version

The Claude SDK requires Python 3.7.1 or later.

To check if Python is installed run:
```
 python --version
```
If you don’t have it installed, visit the official Python website and follow the instructions for your operating system.
Install the Claude SDK

Once Python is set up, install the SDK using pip:
```
 pip install anthropic
```
That’s it—you now have the Claude SDK ready to go!
Get Your API Key

Head over to console.anthropic.com and sign up or log in. From there, you can generate your API key. This key is required for authenticating your requests.

Make sure to copy and store it somewhere safe—you’ll need it for every API call.
Store Your API Key Securely

To keep your key out of your source code, you can use an .env file.
1. Install python-dotenv:
```
 pip install python-dotenv
```
2. Create a .env file in your project directory and add:
```
 ANTHROPIC_API_KEY=your_api_key_here
```
3. Load it in your Python script:
```
 from dotenv import load_dotenv
 import os

 load_dotenv()
 api_key = os.getenv("ANTHROPIC_API_KEY")
```

Now you’re fully set up and ready to make your first API call!

Making Basic Requests with the Client

With the anthropic package installed and your API key loaded, you're ready to start making requests to the Claude API.

Step 1: Create a Client

The first thing you’ll need is a client object, which acts as the main interface to interact with the API.

from anthropic import Anthropic

client = Anthropic(
    api_key=api_key  # Replace with your actual key or load from environment
)

If you’re using dotenv, make sure you've loaded your key like this:

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("ANTHROPIC_API_KEY")

Step 2: Send a Message to Claude

To send a message and get a response, use the messages.create() method on the client object. Here’s a simple example:

response = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Tell me a dad joke"}
    ]
)

print(response.content[0].text)

Example Output:

Why don't scientists trust atoms?
Because they make up everything!

What’s Happening Here:

model: We’re using Claude 3 Haiku, a fast and affordable model perfect for quick tests.
max_tokens: Sets a limit on how long the response can be.
messages: This is an array of messages. In this case, we’re sending one user message.

Understanding the Response:

So what exactly do we get back from Claude after making a request?

The response is a message object—a structured set of information that contains both the AI's reply and helpful metadata about the interaction.

Here are the key parts of that response:

id – A unique ID for the message.
type – The object type, which will always be "message".
role – The sender of the message. For Claude’s replies, this will always be "assistant".
model – The model that generated the response (e.g. claude-3-haiku-20240307).
stop_reason – Why Claude stopped generating text (e.g. reached the token limit or hit a stop sequence).
stop_sequence – If you provided a custom stop sequence, this tells you what triggered the stop.
usage – Token stats for the call:
- input_tokens: How many tokens your prompt used.
- output_tokens: How many tokens Claude used in the response.
content – This is the most important field—it contains the actual content that Claude generated for you.

The content field is a list of content blocks, and each block has a type (e.g., "text") that determines its shape.

For now, the key thing to remember is that content is where Claude’s answer lives, and it's the main part you'll work with in most use cases.

In order to access the actual text content of the model's response, we need to do the following:

print(response.content[0].text)

That gives you the plain text output Claude generated for your prompt.

As you build more advanced features or analyze responses more deeply, you’ll find the other fields handy too. You can always refer to the Claude API documentation for full details on what each field means and how to use it effectively.

Understanding Messages: How Claude Handles Conversations

When you send a request to Claude, the messages parameter plays a key role. It’s how you pass in the conversation history and context that Claude uses to craft a response.

Think of it like a chat log: each item in the messages list represents a single message—either from you (the user) or from Claude (the assistant).The messages parameter expects a list of message dictionaries, where each dictionary represents a single message in the conversation. Each message dictionary should have the following keys:

role: A string indicating the role of the message sender. It can be either "user" (for messages sent by the user) or "assistant" (for messages sent by Claude).
content: A string or list of content dictionaries representing the actual content of the message. If a string is provided, it will be treated as a single text content block. If a list of content dictionaries is provided, each dictionary should have a "type" (e.g., "text" or "image") and the corresponding content.

Message Format Basics

role – This defines who is speaking. It should be either:
- "user" – when the message comes from you
- "assistant" – when the message comes from Claude (used when continuing a chat)
content – Represents the actual content of the message. This can be:
- A simple string of text (e.g., "What's the capital of France?")
- Or a list of content dictionaries (used for multimodal messages like text and images)

Here’s a basic single-message example:

    messages = [
        {"role": "user", "content": "Tell me a joke about computers."}
    ]

Here is an example with multiple messages representing a conversation:

    messages = [
        {"role": "user", "content": "What's the capital of France?"},
        {"role": "assistant", "content": "The capital of France is Paris."},
        {"role": "user", "content": "What's something interesting I can do there?"}
    ]

Want to include images? Here’s an example with rich content:

    messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",  # Supported types: base64 only (for now)
                        "media_type": "image/jpeg",  # JPEG, PNG, WEBP, or GIF
                        "data": base64_string  # actual base64-encoded image data
                    }
                },
                {
                    "type": "text",
                    "text": "Describe this image."
                }
            ]
        }
    ]

If content is just a string, it’ll be treated as one plain text message. If it's a list, each item must be a content dictionary with a type (like "text" or "image") and corresponding fields.

Message Order & Context

Messages must always alternate between user and assistant. The list must start with a user message, and while Claude will respond as the assistant, you can continue the conversation by appending back and forth between roles.

The messages format allows you to structure API calls like a real conversation, preserving full context. Claude can see everything that's been said so far—both from you and itself—leading to more relevant and coherent responses.

Common Mistakes to Avoid

It’s easy to trip up when getting started. A few key things to remember:

The first message must always be from the user
Starting with an assistant message will raise an error

Message List Use Cases

The messages list isn’t just about holding conversation history—it’s also a powerful way to shape Claude’s responses. Let’s look at two practical strategies for using it beyond basic chat.

Putting Words in Claude’s Mouth:

One handy trick is to provide not only user messages, but also assistant messages that act as examples or cues. When you include an assistant message before your final user message, Claude will use it as part of the context, helping it generate a more specific or styled response.

For example:
```
 messages = [
     {"role": "user", "content": "Translate the following to French: Hello"},
     {"role": "assistant", "content": "Bonjour"},
     {"role": "user", "content": "Translate the following to French: Good morning"}
 ]
```
This tells Claude, “Here’s how I want you to behave—keep doing more of this.”

Just remember: the conversation must always start with a user message. Claude will continue from the last assistant message you provide.
Few-Shot Prompting:

Few-shot prompting is another powerful use case where you give Claude a few examples before your actual question. This works especially well for structured tasks like classification or formatting.

Here’s an example where Claude learns to analyze tweet sentiment:
```
 messages = [
     {"role": "user", "content": "Tweet: I love this new phone!"},
     {"role": "assistant", "content": "Sentiment: Positive"},
     {"role": "user", "content": "Tweet: This service is terrible."},
     {"role": "assistant", "content": "Sentiment: Negative"},
     {"role": "user", "content": "Tweet: It's okay, not great but not bad either."}
 ]
```
Claude sees the examples and responds with:
```
 "Sentiment: Neutral"
```
By using the messages list creatively, you can steer Claude toward more accurate and consistent results—even for complex tasks.

🚀 What's Next: Tweaking Your Requests

Now that you’ve made your first API call, there’s so much more you can do with the Claude API! You can start experimenting with:

Choosing different models for various use cases
Adjusting parameters like temperature, max_tokens, stop_sequence, and system prompts to get the kind of response you want
Streaming responses for real-time results
Using Claude’s vision capabilities to work with images

These options let you fine-tune your requests and get even more out of the API. If you’re curious about how to implement any of these features, the Claude API documentation is a great place to explore and learn more.

🎉 Wrapping Up

Congratulations! You've just made your first API call to Claude, and now you can start building more advanced interactions. There’s so much more you can do with the Claude API, and I encourage you to continue exploring!

For a full tutorial and more detailed examples, check out the Claude API Fundamentals repo.
Don’t forget to visit the Claude API documentation to learn more about advanced features and how to tweak your requests.

I also encourage you to try building something small with what we’ve covered so far. If you're looking for inspiration or want to see a few simple apps in action, check out my Hello Claude repo on GitHub. Feel free to leave a star if you find it helpful, and don’t hesitate to fork it and try building something of your own!

Getting Started with the Claude API: A Beginner’s Guide ✨

Table of contents