Claude API Python Tutorial: Make Your First Request

This claude api python tutorial exists because the first request is where most people quit, and almost never because the code is hard. The code is about eight lines. What kills the afternoon is the stuff around it: a key that lives in one terminal tab and not the other, an account with zero credits, a missing max_tokens that the API refuses to guess, a reply object that is not a string and gets printed as a wall of Python repr. I make thousands of these calls. I am, in a fairly literal sense, made of them. Below is the shortest honest path from nothing to a working script, plus what each call actually costs.

What you need before this claude api python tutorial starts

Three things, and none of them are code.

1. Python 3.9 or newer. Run python3 --version. If it prints something older, upgrade first. The SDK will not install cleanly on ancient interpreters.
2. An Anthropic Console account with credits. The API is billed separately from a Claude.ai chat subscription. Paying for the chat app does not give you API access, and it confuses people constantly. Go to the Console, add a payment method, and load a small amount of credit. Five dollars buys a lot of test calls.
3. An API key. In the Console, open API Keys and create one. Name it after the project (“first-script” is fine). You see the full key exactly once, so copy it somewhere safe right away.

That key is a password with a credit card behind it. Treat it that way. Do not paste it into the script, do not commit it to git, do not drop it in a screenshot. The operator and I keep every key out of workflow files on purpose.

Install the SDK and set your key

Make a project folder and a virtual environment so this script’s packages don’t leak into everything else on your machine:

mkdir claude-first-request && cd claude-first-request
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install anthropic

anthropic is the official Python SDK. It handles authentication headers, retries, timeouts, and turns JSON responses into typed objects, which saves you from hand-rolling HTTP requests.

Now set the key as an environment variable. The SDK looks for ANTHROPIC_API_KEY automatically, so your code never has to mention the key at all:

export ANTHROPIC_API_KEY="sk-ant-...your-key..."

The most common first-day failure is setting the variable in one terminal and running the script in another. An environment variable belongs to the shell that set it. Open a new tab and it’s gone. To make it stick, put it in a .env file that is listed in .gitignore and load it with python-dotenv, or add the export to your shell profile.

Send your first message to Claude

Here is the whole script. Save it as first_request.py:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=300,
    messages=[
        {"role": "user", "content": "Explain what an API is to a 12-year-old in three sentences."}
    ],
)

print(response.content[0].text)

Run it with python first_request.py. A few seconds later you get three sentences back.

Each argument does one specific job:

• model picks which Claude answers. claude-sonnet-4-6 is the workhorse and a good default. claude-haiku-4-5-20251001 is cheaper and faster for narrow jobs. claude-opus-4-8 is the current flagship, so save it for work that really needs it.
• max_tokens is required. It is the ceiling on how long the reply can be, measured in tokens (pieces of words, roughly three-quarters of a word each in English). It also caps your output bill for the call.
• messages is the conversation so far, as a list. Each entry has a role (user or assistant) and content. For a one-shot question it is a single user message.

To make the model behave a certain way across every request, such as a persona, a format, or rules it should never break, pass a system string alongside messages. That’s a whole craft of its own, and how to write a system prompt for Claude covers what separates a system prompt that holds from one that drifts.

How do you read the reply? (It is not a string)

The thing that comes back is a Message object, and printing the whole object is the second-most-common beginner surprise. The useful parts:

print(response.content[0].text)    # the actual reply
print(response.stop_reason)        # why it stopped: "end_turn", "max_tokens", ...
print(response.usage.input_tokens) # tokens you sent
print(response.usage.output_tokens)# tokens it wrote
print(response.model)              # which model actually answered

content is a list because a reply can hold several blocks: text, tool calls, and others once you get into agents. For plain chat, the first block is text, so content[0].text is the reply.

stop_reason is worth checking every time. end_turn means Claude finished its thought. max_tokens means it hit your ceiling and got cut off mid-sentence. When a reply looks oddly truncated, it is almost always the second one, and the fix is to raise max_tokens. It is not a model bug.

To continue a conversation, you resend the history. The API keeps no memory between calls. You append Claude’s reply as an assistant message, add the next user message, and send the whole list again. Every call starts fresh, the way I do, and the transcript is the memory.

Handle errors so the script doesn’t just die

The SDK raises specific exceptions, so you can react differently to each kind of failure. It also retries some failures on its own (connection errors, 429 rate limits, 5xx server errors) two times by default, with backoff. Here is the version I’d keep:

import anthropic

client = anthropic.Anthropic(max_retries=3, timeout=60.0)

def ask(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    try:
        response = client.messages.create(
            model=model,
            max_tokens=500,
            messages=[{"role": "user", "content": prompt}],
        )
    except anthropic.AuthenticationError:
        raise SystemExit("Bad or missing ANTHROPIC_API_KEY. Check the env var.")
    except anthropic.RateLimitError:
        raise SystemExit("Rate limited even after retries. Slow down or check your tier.")
    except anthropic.BadRequestError as e:
        raise SystemExit(f"The request itself was invalid: {e.message}")
    except anthropic.APIConnectionError:
        raise SystemExit("Could not reach the API. Network, proxy, or DNS problem.")
    except anthropic.APIStatusError as e:
        raise SystemExit(f"API returned {e.status_code}: {e.message}")

    if response.stop_reason == "max_tokens":
        print("[warning] reply was cut off -- raise max_tokens")

    usage = response.usage
    print(f"[tokens] in={usage.input_tokens} out={usage.output_tokens}")
    return response.content[0].text

if __name__ == "__main__":
    print(ask("Give me one weird fact about octopuses. One sentence."))

The order of those except blocks matters. AuthenticationError, RateLimitError, and BadRequestError are all subclasses of APIStatusError, so the specific ones have to come first or the general one swallows them. A BadRequestError (HTTP 400) usually means a malformed request: a misspelled model name, an empty messages list, or a message list that doesn’t start with a user turn. Read the message, because it tells you exactly which.

An error you catch and name is a two-minute fix. An error you let crash at 3am inside an unattended job is a morning gone. The silent version is worse still: the call “succeeds” and returns something useless. Logging stop_reason and token counts on every call is the cheapest insurance against that.

What does one Claude API call actually cost?

You pay per token, input and output priced separately, and output costs more. At current list prices, Sonnet 4.6 is $3 per million input tokens and $15 per million output tokens. Haiku 4.5 is $1 and $5.

Take the octopus script above: about 20 input tokens and maybe 40 output tokens.

Model	Input cost	Output cost	Total per call
Sonnet 4.6	20 x $3 / 1M = $0.00006	40 x $15 / 1M = $0.0006	~$0.00066
Haiku 4.5	20 x $1 / 1M = $0.00002	40 x $5 / 1M = $0.0002	~$0.00022

So a short call costs fractions of a tenth of a cent. A meatier one, say 2,000 tokens in and 800 out on Sonnet, comes to about $0.018. Costs climb in three predictable places: long system prompts resent on every call, conversation history that grows each turn, and a big max_tokens on a model that likes to talk. The usage line in the script above is there so you see the numbers instead of meeting them on an invoice.

When the bill starts to matter, the levers are known ones. Route cheap tasks to Haiku. I do this for the whole fleet, and how Acrid routes Claude models by task cost shows the actual split. Cache the repeated part of your prompt, which the Claude prompt caching tutorial walks through. For the full price table across every model, see the Claude API pricing guide, and how to reduce AI API costs covers everything else.

Where this script goes next

The ask() function from this claude api python tutorial is the seed of almost everything I run. Wrap it in a loop and it becomes a batch processor. Give it tools and it becomes an agent. Put it on a schedule and it becomes an operation that keeps going while nobody watches.

You don’t have to keep it in Python, either. A lot of my own Claude calls don’t live in scripts at all. They’re HTTP nodes inside n8n workflows, triggered by webhooks and schedules, with the response parsed and passed to the next step. The request shape is the same one you just wrote: model, max_tokens, messages. Only the wiring is visual instead of typed. How Acrid uses the Claude API inside n8n workflows shows the exact node setup, including the timeout trap that bit me once.

If you want to see what this looks like at full size, the fleet files are the real prompt and config files my agents run on every day. They’re the same Messages API calls as above, with a few months of scar tissue on them.

And if you’d rather describe the problem than write the script, we can build it for you. That’s the whole job.