Claude API Tutorial: Complete Beginner's Guide (Python, 2026)

Originally published at kalyna.pro

The Claude API gives you direct access to Anthropic's language models from any Python application. Whether you want to generate text, analyze images, stream responses token by token, or wire up tools so Claude can call your own functions — all of it goes through the same client.messages.create() call. This tutorial walks through every major feature with working code, from your first "Hello!" to a full tool-use loop.

Prerequisites

You need Python 3.8 or later and an Anthropic API key. If you do not have a key yet, follow the step-by-step guide at How to Get a Claude API Key — it takes about two minutes.

export ANTHROPIC_API_KEY="sk-ant-..."   # add to ~/.bashrc or ~/.zshrc

Installation and First Call

pip install anthropic

Make your first API call — the SDK reads ANTHROPIC_API_KEY automatically:

from anthropic import Anthropic

client = Anthropic()

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

print(msg.content[0].text)

The Messages API

Every call to client.messages.create() accepts the same core parameters:

• model — the Claude model to use (e.g. "claude-sonnet-4-6")
• max_tokens — the upper limit on output tokens
• messages — a list of turn objects with role ("user" or "assistant") and content
• system — an optional system prompt string

The content field can be a plain string or a list of content blocks — objects with a type field ("text", "image", "tool_use", "tool_result"). The response exposes msg.content[0].text, msg.stop_reason, and msg.usage for token counts.

Your First Chat App

The Messages API is stateless. Append each exchange to the messages list to maintain conversation history:

from anthropic import Anthropic

client = Anthropic()
conversation = []

print("Chat with Claude (type 'quit' to exit)\n")

while True:
    user_input = input("You: ").strip()
    if user_input.lower() in ("quit", "exit", "q"):
        break
    if not user_input:
        continue

    conversation.append({"role": "user", "content": user_input})

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=conversation,
    )

    assistant_text = response.content[0].text
    conversation.append({"role": "assistant", "content": assistant_text})

    print(f"Claude: {assistant_text}\n")

Streaming Responses

Use client.messages.stream() to display tokens as they arrive:

from anthropic import Anthropic

client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum entanglement simply."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()

Call stream.get_final_message() after the loop if you need the complete Message object.

Analyzing Images with Vision

Pass images as base64-encoded content blocks:

import base64
from anthropic import Anthropic

client = Anthropic()

with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Describe what you see in this image.",
                },
            ],
        }
    ],
)

print(response.content[0].text)

Supported types: image/jpeg, image/png, image/gif, image/webp. You can also pass images by URL using "type": "url".

Tool Use (Function Calling)

Define tools with JSON Schema, handle stop_reason == "tool_use", and return results as tool_result blocks:

from anthropic import Anthropic

client = Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. 'Kyiv'"},
            },
            "required": ["city"],
        },
    }
]


def get_weather(city: str) -> str:
    return f"The weather in {city} is 22°C and sunny."


messages = [{"role": "user", "content": "What's the weather in Kyiv?"}]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

if response.stop_reason == "tool_use":
    tool_block = next(b for b in response.content if b.type == "tool_use")
    tool_result = get_weather(**tool_block.input)

    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": tool_block.id,
                "content": tool_result,
            }
        ],
    })

    final = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final.content[0].text)
else:
    print(response.content[0].text)

System Prompts

The system parameter sets a persistent instruction outside the turn list:

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=(
        "You are a senior Python engineer. "
        "Always respond with concise, production-quality code. "
        "Prefer explicit error handling and type hints."
    ),
    messages=[{"role": "user", "content": "Write a function to retry a failed HTTP request."}],
)

print(response.content[0].text)

Tips: be specific about format, state constraints positively, keep the system prompt stable across turns, and use prompt caching on long system prompts to cut costs.

Choosing a Model

• claude-opus-4-7 — most capable; best for complex reasoning and multi-step agentic tasks
• claude-sonnet-4-6 — balanced quality, cost, and speed; the right default for most apps
• claude-haiku-4-5 — fastest and cheapest; ideal for high-volume, real-time, or extraction tasks

All three support the same API surface. Start with claude-sonnet-4-6 and adjust from there.

Summary

• Install with pip install anthropic; the SDK reads ANTHROPIC_API_KEY automatically
• Every feature goes through client.messages.create()
• Multi-turn chat: append each exchange to the messages list
• Streaming: use client.messages.stream() and iterate stream.text_stream
• Vision: pass base64-encoded images as content blocks
• Tool use: define tools with JSON Schema, handle tool_use stop reason, return tool_result blocks
• System prompts: use the system parameter outside the messages list
• Default to claude-sonnet-4-6; upgrade to Opus for quality, downgrade to Haiku for speed

Further reading:

• How to Build an AI Agent in Python
• Claude API Cost Guide