The messages API: your first real calls

The shape of a Claude request

Every call to the Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → is built from a few required parts:

• `model`: which Claude you want (a Sonnet, Opus, or Haiku variant). Sonnet is the everyday workhorse, Opus is the most capable for hard reasoning, Haiku is the fast and cheap one.
• `max_tokens`: the ceiling on how many tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → Claude may generate in its reply. This is an upper bound, not a target. It does not pad the response; it just caps it.
• `messages`: the conversation, as a list of turns. Each turn has a role (user or assistant) and content.
• `system` (optional but important): a top-level parameter, separate from the messages list. This is where role, tone, and rules go.

That last point is the first thing that trips people coming from other APIs. In the Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, the system prompt is not a message with role: "system". It is its own field on the request. Anthropic models are trained around this structure, and keeping standing instructions in system rather than stuffing them into a user turn measurably improves how reliably Claude follows them.

A tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition →, as a reminder, is the chunk of text the model reads and writes in (roughly a few characters). You pay per tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → in and per tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → out, so max_tokens is also a cost control.

Your first real call

Here is a complete, runnable call. Install the SDK with pip install anthropic and set your key as the ANTHROPIC_API_KEY environment variable first.

Walk through what comes back. The response is an object, not a raw string. Its content is a list of content blocks, because a single reply can contain more than one kind of block (text, and later, tool-use requests). For a plain text answer you read response.content[0].text. You also get response.usage with input and output tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → counts, and response.stop_reason, which tells you *why* Claude stopped: end_turn means it finished naturally, max_tokens means it hit your ceiling and got cut off. Always check stop_reason in production. A truncated answer that you treated as complete is a silent bug.

Check the current model names and parameters in the official Messages API reference before you ship, since model IDs roll forward over time.

The conversation is yours to carry

The APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → is stateless. Claude does not remember your last call. *You* hold the conversation by appending each turn to the messages list and sending the whole thing back.

A multi-turn exchange is just an alternating list:

Two rules to internalize. First, turns must alternate user and assistant; you cannot send two user turns in a row. Second, you can seed the assistant's reply by ending your messages list on an assistant turn with partial content. Claude will continue from exactly where you left it. This trick, called prefilling, is genuinely useful: prefill with { to force JSON output, or with Here is the answer in three bullets: to lock the format. It is a Claude-specific lever that the chat UI never exposes to you.

Streaming for long replies

When Claude is writing a long answer, you do not want to wait for the entire thing before showing anything. Streaming sends the response back in pieces as they are generated, so text appears word by word, the way it does in the Claude app.

Flip one argument and iterate:

The stream() method returns a context manager (the with block), which guarantees the connection closes cleanly even if something fails mid-stream. The text_stream helper hands you just the text deltas, which is what you usually want for a UI. When the loop ends, get_final_message() reassembles the complete response so you still get usage and stop_reason.

Stream whenever a reply might be long or whenever a human is watching it arrive. For short background jobs where nothing is waiting on the output, the plain create() call is simpler and just as fast overall.

What makes this Claude, not just an APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →

A few behaviors are worth knowing before you build on them.

System prompts carry real weight. Because of where system sits in the request, persistent instructions there are followed more consistently than the same text buried in a user message. Put the durable stuff (role, output format, hard constraints) in system, and the per-request task in the user turn.

Long context is a feature, not just a number. Claude models support large context windows, big enough to drop in whole documents, long transcripts, or a sizable chunk of a codebase. Practically, that means you can often pass source material directly instead of building retrieval for it. Prices and exact window sizes shift, so confirm the current figures in the docs rather than memorizing them.

The same API powers tools and agents. Everything you will build later (tool use, the connectors that the Claude apps expose, MCP servers, and the Claude Agent SDK) sits on top of this exact messages.create call. Tool use is just additional content block types flowing through the same request and response shape you already understand. Learn this surface well and the rest of the Claude path becomes incremental.

Reading errors and being a good client

Real calls fail sometimes. The two you will meet first:

• `401` (authentication): your ANTHROPIC_API_KEY is missing, wrong, or not loaded into the environment. Print the variable (not the key itself) to confirm your process can see it.
• `429` (rate limit) and `529` (overloaded): you are sending too fast, or the service is briefly saturated. The fix is the same: back off and retry.

The SDK already retries certain failures with exponential backoff, but you should still wrap calls and handle the cases the SDK gives up on:

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": "One sentence on idempotency."}],
    )
    print(response.content[0].text)
except anthropic.RateLimitError:
    print("Rate limited. Slow down and retry with backoff.")
except anthropic.APIStatusError as exc:
    print(f"API error {exc.status_code}: {exc.message}")

Catch RateLimitError specifically when you want custom backoff, and fall back to APIStatusError for everything else with a non-success status. This is the difference between a script that dies on the first hiccup and a service that survives a busy afternoon.

Where to keep your keys

One operational note, because it bites people on day one. Your APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → key is a secret with billing attached. Never hardcode it in source, never commit it, never ship it inside a browser app where users can read it. Keep it in an environment variable or a secrets manager, and let the SDK read it automatically. The anthropic.Anthropic() constructor picks up ANTHROPIC_API_KEY with no argument, which is exactly why every snippet above leaves it implicit. If you need browser-side calls, route them through a small backend that holds the key, never the client.

You can generate and rotate keys in the Anthropic Console, and the SDK source lives at github.com/anthropics if you want to read how the retries and streaming are implemented.

Key Takeaways

• Put standing instructions in the top-level `system` parameter, not a user message. Claude is trained around this structure and follows it more reliably; reserve user turns for the actual task.
• Always check `stop_reason` and `usage`. A reply cut off at max_tokens looks complete but isn't, and tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → counts are your cost and budget signal.
• Carry the conversation yourself. The APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → is stateless: append each user and assistant turn to the messages