Chat apps are great, but the real fun starts when your own code can use an AI model: summarising files, sorting emails, answering questions about your data, or adding a voice to a robot. This guide gets you from nothing to a working Python program. The examples use Anthropic's Claude, and the same ideas apply to OpenAI and Google's APIs.
What you need
- Python 3.9 or newer. Check with
python3 --version. - An API account and key from the provider's developer console. APIs are pay-as-you-go and separate from any chat subscription. You'll usually need to add a small amount of credit first.
- The provider's Python library:
pip install anthropic
Keep your API key secret
An API key is like a password that spends your money. Never paste it into your code, share it in screenshots or upload it to GitHub. Instead, store it in an environment variable, which the library reads automatically:
# macOS and Linux
export ANTHROPIC_API_KEY="your-key-here"
# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="your-key-here"
It's also worth setting a monthly spending limit in the console, so a bug can never run up a big bill.
Your first request
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-haiku-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Explain what a resistor does in one sentence."}
],
)
for block in response.content:
if block.type == "text":
print(block.text)
print(response.usage.input_tokens, "tokens in,", response.usage.output_tokens, "tokens out")
Here's what each part does:
- model chooses which model answers. Small, fast models like Haiku are cheap and fine for simple jobs. See how to choose an AI model.
- max_tokens caps the length of the reply, which also caps its cost.
- messages is the conversation so far. Each message has a
role(userorassistant) and somecontent. - The reply arrives as a list of content blocks, so we print the text ones.
- usage tells you how many tokens you were charged for.
Giving the model a job: system prompts
A system prompt sets the model's role and rules for the whole conversation:
response = client.messages.create(
model="claude-haiku-5-5",
max_tokens=1024,
system="You are a patient electronics tutor for beginners. Use short sentences and no jargon.",
messages=[{"role": "user", "content": "Why does an LED need a resistor?"}],
)
Our guide to writing better prompts covers what to put in one.
Having a conversation
The API doesn't remember anything between requests. To hold a conversation, your program keeps the message list and sends the whole thing every time:
messages = []
while True:
question = input("You: ")
if question.lower() in ("quit", "exit"):
break
messages.append({"role": "user", "content": question})
response = client.messages.create(
model="claude-haiku-5-5", max_tokens=1024, messages=messages
)
reply = "".join(b.text for b in response.content if b.type == "text")
print("AI:", reply)
messages.append({"role": "assistant", "content": reply})
Because the whole history is resent each time, long conversations cost more per message. That's a key idea in context windows and cutting AI costs.
Handling errors
Network hiccups and busy servers happen. The library automatically retries some failures, but your program should still catch errors rather than crash:
try:
response = client.messages.create(
model="claude-haiku-5-5", max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
except anthropic.AuthenticationError:
print("Check your API key.")
except anthropic.RateLimitError:
print("Too many requests. Wait a moment and try again.")
except anthropic.APIError as e:
print("Something went wrong:", e)
What will it cost?
You pay per token, with separate prices for input and output. Short test requests like these cost a tiny fraction of a cent each on small models. To estimate a real app, try the AI API cost calculator.
Model names and library details change over time, so check the provider's documentation for the current models before you build.
Going deeper
Streaming replies
Long replies can take a while. Streaming shows text as it's generated, which makes apps feel much faster, and avoids timeouts on very long outputs:
with client.messages.stream(
model="claude-haiku-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Write a short poem about solder."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print()
Many requests at once
For processing lots of items, the async client sends requests concurrently. A semaphore limits how many run together, so you stay within your rate limits:
import asyncio
import anthropic
client = anthropic.AsyncAnthropic()
limit = asyncio.Semaphore(5)
async def summarise(text):
async with limit:
r = await client.messages.create(
model="claude-haiku-5-5", max_tokens=200,
messages=[{"role": "user", "content": "Summarise in one sentence:\n" + text}],
)
return "".join(b.text for b in r.content if b.type == "text")
async def main(texts):
return await asyncio.gather(*(summarise(t) for t in texts))
results = asyncio.run(main(["First document...", "Second document..."]))
If results aren't needed straight away, the Batches API is simpler and half the price. See cutting AI costs.
Rate limits and retries
APIs limit requests and tokens per minute. When you exceed them, you get a 429 error. Anthropic's library automatically retries rate-limit and temporary server errors a couple of times with increasing delays, and you can raise this with anthropic.Anthropic(max_retries=5). For heavy workloads, spread requests out instead of relying on retries.
Structuring a real app
- Keep model names, prompts and limits in one configuration place, so they're easy to change.
- Log the request ID, model and token usage of every call. It makes debugging and cost tracking far easier.
- Never let user input change your system prompt, and treat model output as untrusted text before using it in a database query or web page.
- Build a small set of test inputs and expected results, and re-run them whenever you change prompts or models.
Sources
The main references behind this guide. Numbers we worked out ourselves, such as the code outputs, come from running the code.