Skip to main content

AI and machine learning · Beginner · 18 min

How to Call a Large Language Model API from Python

By Padding · Updated 15 Nov 2026
Python 3.15 · anthropic SDK 2.8.0 · Claude Sonnet 5.5

You will store an API key safely, install Anthropic's Python SDK 2.8.0, send Claude Sonnet 5.5 a first request, give it instructions and a conversation history, handle the errors an API call can raise, and work out what each call costs.

On this page

A large language model (LLM) API is a web API: you send text, it sends text back, and you pay for the amount of text in each direction. This tutorial uses Anthropic's official Python SDK, anthropic, to call Claude. The ideas carry over to other providers, whose SDKs also give you a client object, a model name and a list of messages, although the names differ.

You will write four short scripts. One makes a request, one gives the model instructions and a conversation, one handles failures, and one reports what each call cost. The model is claude-sonnet-5-5, which Anthropic describes as the best mix of speed and intelligence in the current line-up. Anthropic's model overview lists the other current IDs, such as claude-haiku-5-5 for cheap, fast work and claude-opus-5-5 for harder tasks.

Every call costs money, and the API has rate limits. A short prompt costs a fraction of a cent. A script with a bug in a loop can cost far more, so the last step covers limits you can set.

Step 1 · Create an API key and keep it private

In the Claude Console at platform.claude.com, open the API keys page, create a key and copy it. The key is shown once. Treat it like a password: anyone who has it can spend your money.

Keep the key out of your code, out of Git and off the command line, where it would land in your shell history and in the process list. Store it in a file only you can read. install -m 600 creates the file private from the start, so it is never briefly readable by others:

Bash
mkdir -p ~/.config/llm-demo
install -m 600 /dev/null ~/.config/llm-demo/env

Now add the key. read -s does not echo what you paste, and printf is a shell built-in, so the key does not appear in any process list:

Bash
read -rsp "Paste your API key: " key; echo
printf 'ANTHROPIC_API_KEY=%s\n' "$key" >> ~/.config/llm-demo/env
unset key

Confirm the permissions. The listing must start with -rw-------:

Bash
ls -l ~/.config/llm-demo/env

The SDK reads the key from the ANTHROPIC_API_KEY environment variable. Load the file into your current terminal with set -a, which exports every variable the file defines. Do this in each new terminal before you run the scripts:

Bash
set -a
. ~/.config/llm-demo/env
set +a

Check it worked

Check that the variable is set, without printing it:

Bash
test -n "$ANTHROPIC_API_KEY" && echo "key is set"

The output is key is set.

Step 2 · Create a project and install the SDK

Create a project folder and add the SDK. The range keeps you on the 2.x line, so a future major release cannot change the code under you:

Bash
mkdir -p ~/llm-demo
cd ~/llm-demo
uv init --no-package
uv add "anthropic>=2,<3"

Check it worked

Bash
uv run python -c "import anthropic; print(anthropic.__version__)"

The command prints 2.8.0, or a later 2.x release.

Step 3 · Send your first request

A request has three required parts: the model, a max_tokens limit on the length of the reply, and a list of messages. Create first.py:

Bash
cat > first.py <<'PY'
import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain what an HTTP 404 status means, in two sentences."},
    ],
)

text = "".join(block.text for block in message.content if block.type == "text")
print(text or "(no text in the reply)")
print("stop reason:", message.stop_reason)
print("tokens in/out:", message.usage.input_tokens, message.usage.output_tokens)
PY
uv run first.py

anthropic.Anthropic() builds a client that reads ANTHROPIC_API_KEY from the environment. message.content is a list of blocks, because a reply can hold more than plain text, such as tool calls or thinking. The line that builds text keeps only the text blocks and joins them, which stays correct if a model adds other blocks before its answer. max_tokens is a ceiling on the reply, not a target. A token is a piece of a word, roughly three-quarters of an English word on average.

Claude Sonnet 5.5 uses adaptive thinking: on each request the model decides whether to reason before it answers, and a simple question may get no thinking at all. Anthropic's documentation says that thinking tokens count toward max_tokens, that they are billed as output tokens, and that usage.output_tokens is the inclusive total. Because of that, give max_tokens real headroom. A ceiling of 1,024 or more is a sensible start for short answers, while 300 can be used up by thinking before any text appears. Thinking is on by default, and lowering the effort level, with output_config={"effort": "low"}, is how Anthropic's "Steering thinking" page says to get less of it.

Check it worked

The output has three parts: the model's answer, stop reason: end_turn, and a token line such as tokens in/out: 24 180. The output count can be several times the length of the answer you see, because it includes any thinking. Your numbers and wording differ, because the model writes a new answer each time. end_turn means the model finished by itself. A stop reason of max_tokens means your ceiling cut the reply off. When thinking used the whole ceiling, the reply has no text block at all, and the script then prints (no text in the reply). Raise max_tokens when you see that.

Troubleshooting

An AuthenticationError with status 401 means the key is missing or wrong. Check that you ran the set -a step in this terminal. A NotFoundError with status 404 usually means a mistyped model ID: copy the ID from Anthropic's model overview. If the process hangs, see the timeouts in the error-handling step.

Step 4 · Give the model instructions and a conversation

The API keeps no memory between calls. To hold a conversation you send the whole history each time, as alternating user and assistant messages. A system prompt holds standing instructions that apply to the whole conversation. Create chat.py:

Bash
cat > chat.py <<'PY'
import anthropic

client = anthropic.Anthropic()
SYSTEM = "You are a patient tutor. Answer in at most two sentences and use plain words."

history = []


def ask(question):
    history.append({"role": "user", "content": question})
    message = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        system=SYSTEM,
        messages=history,
    )
    answer = "".join(b.text for b in message.content if b.type == "text")
    if message.stop_reason == "max_tokens":
        history.pop()  # drop the question so a retry does not leave two user turns in a row
        raise RuntimeError("the reply was cut off by max_tokens: raise it and ask again")
    history.append({"role": "assistant", "content": answer})
    return answer


print(ask("What is a database index?"))
print(ask("Give me an everyday comparison."))
print("messages sent on the last call:", len(history) - 1)
PY
uv run chat.py

ask appends your question, sends the history, then appends the model's answer so the next call includes it. The second question, "Give me an everyday comparison", makes sense to the model only because the first exchange travels with it.

Check it worked

The output is two short answers, the second one comparing an index to something familiar, then messages sent on the last call: 3. Every call resends the earlier turns, so input tokens, and the cost, grow with the length of the conversation. Trim or summarise old turns in long chats.

Step 5 · Handle the errors a call can raise

Three things go wrong with API calls: the request is refused, the service is busy, or the network fails. The SDK raises a different exception for each. They all inherit from anthropic.APIError, and the ones that carry an HTTP status inherit from anthropic.APIStatusError:

  • anthropic.AuthenticationError for a bad key (401) and anthropic.PermissionDeniedError for a key that may not do this (403).
  • anthropic.RateLimitError for a 429, which means you are over a limit and should slow down.
  • anthropic.APIConnectionError when the request never reached the service, and anthropic.APITimeoutError, a subclass of it, when it took too long.

The SDK already retries connection errors, 429 responses and server errors 2 times with a short delay, so you rarely need your own loop. Raise the count with max_retries on the client. The default timeout is 10 minutes to read a reply, which is long enough to hide a stuck call: set your own with timeout. Create errors.py, which provokes two of these failures on purpose:

Bash
cat > errors.py <<'PY'
import anthropic


def try_call(client, label):
    try:
        client.messages.create(
            model="claude-sonnet-5-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": "Say hello."}],
        )
        print(label, "worked")
    except anthropic.AuthenticationError as err:
        print(label, "-> wrong key, status", err.status_code)
    except anthropic.RateLimitError as err:
        print(label, "-> slow down, retry after", err.response.headers.get("retry-after"))
    except anthropic.APIConnectionError:
        print(label, "-> could not reach the service")
    except anthropic.APIStatusError as err:
        print(label, "-> the API refused the request, status", err.status_code)


try_call(anthropic.Anthropic(api_key="not-a-real-key", max_retries=0), "bad key")
try_call(anthropic.Anthropic(base_url="http://127.0.0.1:9", max_retries=0, timeout=5.0), "no service")
PY
uv run errors.py

The except clauses run from most specific to most general, because APIStatusError would also catch the first two. The first client uses a key the service rejects. The second points at port 9 on your own machine, where nothing listens.

Check it worked

The output is bad key -> wrong key, status 401 and no service -> could not reach the service.

On a RateLimitError, wait for the number of seconds in the retry-after response header before you try again. Anthropic measures limits in requests, input tokens and output tokens per minute for each model, and your limits depend on your account tier. The Rate limits page in the Console shows yours. Anthropic's rate limits page also says that an account that reaches its monthly spend cap gets a 429 with no retry-after header, and retrying will not help until the cap resets or is raised.

Step 6 · Count what each call costs

Every response reports usage: the tokens you sent and the tokens the model wrote. Anthropic bills by the million tokens, with a different price for input and output. At the time of writing, Claude Sonnet 5.5 costs $2 per million input tokens and $10 per million output tokens. Check the pricing page before you rely on these numbers, because prices change. Create cost.py:

Bash
cat > cost.py <<'PY'
import anthropic

INPUT_USD_PER_MILLION = 2.00
OUTPUT_USD_PER_MILLION = 10.00

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Name three uses of a hash table."}],
)

usage = message.usage
cost = (
    usage.input_tokens * INPUT_USD_PER_MILLION
    + usage.output_tokens * OUTPUT_USD_PER_MILLION
) / 1_000_000
print(f"input tokens: {usage.input_tokens}")
print(f"output tokens (including any thinking): {usage.output_tokens}")
print(f"cost: ${cost:.6f}")
PY
uv run cost.py

Check it worked

The output is the two token counts and a cost such as $0.002000. Output tokens include any thinking the model did, and they cost five times as much as input tokens, so a reply of a few hundred tokens costs a fraction of a cent. Do not size your budget from the visible answer alone, because the thinking you cannot see is billed too. A thousand calls like this one typically cost a few dollars. The worst case is a reply that uses the whole 1,024-token ceiling: 1,024 output tokens at $10 per million is about a cent, so about $10 per thousand calls, plus the small input cost.

Three habits keep the bill predictable. Set max_tokens high enough for thinking plus the answer, but not higher than the task needs. Use a cheaper model, such as claude-haiku-5-5, for simple jobs like classification. Set a monthly spend limit below your tier's cap on the Spend limits page of the Console, so a bug in a loop cannot spend without bound. Batch jobs that can wait are half price through Anthropic's Message Batches API.

Step 7 · Clean up

Delete the demo project. The key file stays, because the next tutorials in this section load the same key:

Bash
cd ~
rm -rf ~/llm-demo

When you are finished with all the LLM tutorials, delete the key file too, and revoke the key in the Console:

Bash
rm -rf ~/.config/llm-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

AI-Integrated Solutions

Get new tutorials

New tutorials, about twice a month.