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:
mkdir -p ~/.config/llm-demo
install -m 600 /dev/null ~/.config/llm-demo/envNow 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:
read -rsp "Paste your API key: " key; echo
printf 'ANTHROPIC_API_KEY=%s\n' "$key" >> ~/.config/llm-demo/env
unset keyConfirm the permissions. The listing must start with -rw-------:
ls -l ~/.config/llm-demo/envThe 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:
set -a
. ~/.config/llm-demo/env
set +aCheck it worked
Check that the variable is set, without printing it:
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:
mkdir -p ~/llm-demo
cd ~/llm-demo
uv init --no-package
uv add "anthropic>=2,<3"Check it worked
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:
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.pyanthropic.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:
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.pyask 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.AuthenticationErrorfor a bad key (401) andanthropic.PermissionDeniedErrorfor a key that may not do this (403).anthropic.RateLimitErrorfor a 429, which means you are over a limit and should slow down.anthropic.APIConnectionErrorwhen the request never reached the service, andanthropic.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:
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.pyThe 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:
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.pyCheck 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:
cd ~
rm -rf ~/llm-demoWhen you are finished with all the LLM tutorials, delete the key file too, and revoke the key in the Console:
rm -rf ~/.config/llm-demoNext steps
- Make the model return data your code can rely on: get reliable JSON output from an LLM.
- Give a model your own documents to answer from: start the Build a RAG app from scratch series.
- Protect an app that passes user text to a model: defend an LLM app against prompt injection.
- Anthropic's API documentation at platform.claude.com covers streaming, tool use, prompt caching and the Message Batches API.
Related tutorials
- How to Call a Web API from Python with httpxYou will install httpx 0.28, write a small local API to practise on, then call it from Python by fetching JSON, add query parameters and a reusable client, handle bad statuses, timeouts and network failures, send JSON in a POST request, and make several requests at once with async code.
- How to Use Virtual Environments and Install Packages in PythonYou will create an isolated Python 3.15 environment for a project, install a package into it with pip, record the exact versions, rebuild the environment from that record, and then manage the same project with uv.
- How to Read and Write Files and JSON in PythonYou will read and write text files with pathlib, convert Python data to JSON and back, and use both to build a small task list that keeps its data in a JSON file and survives a damaged file.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials