Your First API Call

The trap is thinking your first API call is about connectivity. Every tutorial starts the same way: install the SDK, paste your key, send "Hello, world," get a response, celebrate. You've proven the wire works. Congratulations — you have accomplished the equivalent of plugging in a lamp and confirming that electricity exists. The real question was never whether the API responds. It's whether you've structured the request so Claude reasons rather than recites.

I've seen teams spend weeks building a product on top of the Claude API and never once think about what they're actually sending. They copy the minimal example from the docs, swap "Hello" for their real prompt, and wonder why the output feels generic. The gap between a working API call and a good API call is the same gap between asking a brilliant colleague "what do you think?" and handing them a brief with constraints, context, and a definition of done.

This chapter is about closing that gap from the first line of code you write.

The Setup: Getting Connected

Before you write a single line of application code, you need three things: the Anthropic Python SDK, an API key, and an environment that keeps the key out of your source code. The order matters.

Start with the SDK:

pip install anthropic

If you're using a virtual environment (and you should be), activate it first. The SDK pulls in its own dependencies — httpx for HTTP, pydantic for data validation — and you don't want those polluting your system Python.

Next, get your API key from the Anthropic Console at console.anthropic.com. The key starts with sk-ant-. You'll use it for every API call, and it's tied to your billing — anyone who has it can spend your money.

The right way to store it:

# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Or in a .env file in your project root
echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' > .env
echo '.env' >> .gitignore

If you use the .env approach, install python-dotenv and load it at the top of your script:

from dotenv import load_dotenv
load_dotenv()

The Anthropic SDK reads ANTHROPIC_API_KEY from the environment automatically. You never need to pass the key as a parameter to the client constructor — anthropic.Anthropic() picks it up. This is intentional: it keeps keys out of code and makes deployment simpler (production environments set environment variables through their own mechanisms, not .env files).

I've seen teams skip this setup and hardcode the key directly in their Python files. It works until someone pushes to GitHub, a bot scrapes the key in seconds, and the team discovers they've been funding someone else's API calls. Set up the environment correctly once. It takes two minutes and saves you from a class of problems you never want to debug.

What the API Actually Gives You

The Claude API is not a chat window with a different skin. It's a programmable interface to the same model — but with levers the chat interface doesn't expose. You control the model variant, the token budget, the system prompt, the temperature, and the exact sequence of messages. Those levers matter because they determine whether Claude approaches your request as a creative brainstorm, a precise data extraction, or a careful analysis.

Here's what changes when you move from the chat interface to the API:

• Model selection becomes explicit. You pick the exact model and version: claude-sonnet-4-5-20250514, claude-haiku-4-5-20250514, or whatever fits your latency and cost constraints. In the chat interface, that choice is made for you.
• System prompts become first-class. The system prompt isn't a suggestion — it's an instruction layer that shapes every response. You can make Claude behave as a strict JSON service, a code reviewer, a medical triage assistant, or a technical writer without changing a single line of the user message.
• Token budgets become your responsibility. You set max_tokens, and if the response exceeds that budget, it gets truncated. No warning, no graceful summary — just a chopped sentence. Understanding this parameter saves you from debugging "incomplete responses" for an afternoon.
• Every request is stateless. The API does not remember your last call. Each request is self-contained. This is the single most misunderstood property of the API, and it's the foundation of everything in the next chapter.

Anatomy of a Request

A Claude API request is a JSON payload sent over HTTPS. The Python SDK wraps the raw HTTP call, but understanding the structure matters because every parameter you omit falls back to a default — and defaults are opinions someone else chose for your use case.

Here's the minimal request that actually teaches you something:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    system="You are a senior Python developer. Be direct. When you spot a mistake, say so plainly.",
    messages=[
        {
            "role": "user",
            "content": "Review this function and tell me what's wrong:\n\ndef get_user(id):\n    user = db.query(f'SELECT * FROM users WHERE id = {id}')\n    return user[0]"
        }
    ]
)

print(response.content[0].text)

The SDK reads your API key from the ANTHROPIC_API_KEY environment variable automatically — no need to pass it explicitly. Set it once in your shell or .env file and forget about it.

Let me walk through what each piece does.

model — This is not a formality. Different models have different latencies, costs, and reasoning depths. I default to claude-sonnet-4-5-20250514 for development because it's the best balance of speed and capability. When I need deep reasoning — multi-step analysis, complex code generation, architectural decisions — I reach for Opus. When I need speed and the task is straightforward — classification, extraction, simple rewrites — Haiku cuts the cost by an order of magnitude.

max_tokens — The ceiling on how many tokens Claude can generate. Set it too low and your response gets truncated mid-sentence. Set it too high and you pay for headroom you never use (though you only pay for tokens actually generated). I start with 1024 for focused responses and go to 4096 for longer outputs.

system — The system prompt. This is the most underused parameter in every codebase I've reviewed. Teams leave it empty or set it to "You are a helpful assistant" — which is like hiring a specialist and then telling them to be generally useful. A good system prompt defines the role, the constraints, and the output expectations.

messages — An array of message objects, each with a role ("user" or "assistant") and content. For your first call, this is a single user message. We'll build multi-turn conversations in the next chapter.

The Response Object

Claude's response is not a string. It's a structured object, and understanding its shape saves you from the most common integration bugs.

import anthropic

client = anthropic.Anthropic()

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

# The response object
print(f"Model: {response.model}")
print(f"Stop reason: {response.stop_reason}")
print(f"Input tokens: {response.usage.input_tokens}")
print(f"Output tokens: {response.usage.output_tokens}")
print(f"Content: {response.content[0].text}")

The fields that matter:

• response.content — A list of content blocks. For text responses, you almost always want response.content[0].text. But it's a list because Claude can return multiple blocks (text, tool use, images). Hardcoding [0] works for simple cases; production code should iterate.
• response.stop_reason — Tells you why Claude stopped generating. "end_stop" means it finished naturally. "max_tokens" means it hit your token ceiling and got cut off. If you're seeing "max_tokens" in production, your responses are being silently truncated. Always check this field.
• response.usage — Token counts for billing and debugging. input_tokens is what you sent; output_tokens is what Claude generated. You pay for both. This is how you catch runaway costs before they hit your invoice.

The System Prompt Is Not Optional

I've reviewed dozens of Claude API integrations. The single most common pattern I see is an empty system prompt with all the instructions crammed into the user message. It works — Claude is forgiving — but it's like writing every email with the subject line blank and the context buried in paragraph four.

The system prompt is a separate instruction channel for a reason. It persists across every turn of a conversation. It shapes Claude's persona, constraints, and output style without competing with the user's actual request. When you put instructions in the user message, Claude has to figure out which part is the task and which part is the meta-instruction. When you put them in the system prompt, there's no ambiguity.

import anthropic

client = anthropic.Anthropic()

# Weak: instructions mixed with the request
weak_response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "You are a strict code reviewer. Only point out bugs, not style issues. Review this code: def add(a, b): return a + b"
        }
    ]
)

# Strong: clean separation of instruction and task
strong_response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    system="You are a strict code reviewer. Only point out bugs, not style issues. Ignore formatting and naming conventions entirely.",
    messages=[
        {
            "role": "user",
            "content": "Review this code:\n\ndef add(a, b): return a + b"
        }
    ]
)

The second version is cleaner, but the real advantage shows up in multi-turn conversations. The system prompt applies to every exchange without being resent in the message history. The user message stays focused on what the user actually wants.

Error Handling That Doesn't Embarrass You

Your first API call will succeed. Your hundredth might not. Network failures, rate limits, invalid parameters, expired keys — the API surface has real failure modes, and ignoring them means your application crashes in front of users with a raw stack trace.

The Anthropic SDK raises specific exceptions for each failure class. Handle them individually:

import anthropic

client = anthropic.Anthropic()

def ask_claude(prompt: str, system: str = "") -> str:
    try:
        response = client.messages.create(
            model="claude-sonnet-4-5-20250514",
            max_tokens=1024,
            system=system,
            messages=[{"role": "user", "content": prompt}]
        )
        return response.content[0].text

    except anthropic.AuthenticationError:
        return "ERROR: Invalid API key. Check your ANTHROPIC_API_KEY."

    except anthropic.RateLimitError:
        return "ERROR: Rate limit exceeded. Back off and retry."

    except anthropic.APIConnectionError:
        return "ERROR: Cannot reach the API. Check your network."

    except anthropic.APIStatusError as e:
        return f"ERROR: API returned status {e.status_code}: {e.message}"

The pattern I use in production goes further: exponential backoff on rate limits, structured logging for every error, and a circuit breaker that stops hammering the API when it's clearly down. But this foundation handles the cases that matter for your first integration.

Choosing the Right Model

Model selection is a cost-performance tradeoff, and most teams get it wrong by defaulting to the most powerful model for every request. That's like taking a taxi to the corner store.

My rule of thumb: start with Sonnet. If the task is simple enough that a junior developer could do it (classification, extraction, summarization of short text), drop to Haiku. If the task is complex enough that you'd want a senior architect reviewing it (system design, nuanced code review, multi-step reasoning), upgrade to Opus. Measure the output quality at each tier before committing.

The cost differences are not marginal. As of this writing, Haiku costs roughly one-twentieth of Opus per token. For a classification pipeline processing 10,000 items a day, that's the difference between a $30 monthly API bill and a $600 one — for output that may be functionally identical. I've watched teams burn through their trial credits in a week because they hardcoded Opus into a batch job that Haiku could have handled. The model parameter is a financial decision as much as a technical one.

The Temperature Parameter

Temperature deserves its own discussion because it's the most misunderstood parameter in the API. It controls randomness in Claude's output — technically, it adjusts the probability distribution over the next token.

Temperature 0 makes Claude deterministic: given the same input, you get the same (or very nearly the same) output every time. Temperature 1 increases variability — Claude considers more diverse word choices and phrasings.

I use temperature 0 for extraction, classification, and any task where consistency matters. I use temperature 0.5–0.7 for creative writing, brainstorming, and generating diverse examples. I almost never use temperature above 0.8 in production because the outputs start to feel unfocused.

import anthropic

client = anthropic.Anthropic()

# Deterministic: same input → same output
response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=256,
    temperature=0,
    messages=[{"role": "user", "content": "Classify this email as spam or not spam: 'You've won a free iPad!'"}]
)
print(response.content[0].text)

Most developers never set temperature explicitly and get the default (which is 1). For analytical tasks, that's leaving quality on the table. For creative tasks, the default is usually fine. The point is to make it a conscious choice, not an accident.

Monday-Morning Moves