Claude API Basics
A quick reference for making your first Claude API call, picking a model, and reading the response.
TL;DR
- 01Install the Anthropic SDK and set your
ANTHROPIC_API_KEYvariable. - 02Call
client.messages.create()with a model, prompt, andmax_tokens. - 03Check
stop_reasonbefore readingcontentto handle responses safely.
Tips
- 01Pin an exact model ID like
claude-opus-4-8in production so a later model update never silently changes your app's behavior. - 02Set
max_tokensgenerously for long or open-ended replies, since Claude stops the moment it reaches that limit, even mid-sentence.
Warnings
- 01
max_tokensis required on every request — omitting it raises a validation error before Claude even sees your prompt. - 02Never hard-code an API key in source control; load it from an environment variable or a secrets manager instead.
Installation and Auth
pip install anthropicInstalls the Python SDK from PyPI so you can start calling Claude.
pip install anthropicnpm install @anthropic-ai/sdkInstalls the TypeScript and Node SDK for JavaScript projects.
npm install @anthropic-ai/sdkANTHROPIC_API_KEYStores your API key as an environment variable instead of hard-coding it.
export ANTHROPIC_API_KEY="sk-ant-..."Your First Request
Anthropic()Creates a client that reads the API key from the environment automatically.
import anthropic
client = anthropic.Anthropic()messages.create()Sends a prompt to Claude with a model, max_tokens, and a messages array.
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Explain closures in one paragraph."}]
)system parameterGives Claude a persistent role or persona for the whole conversation.
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system="You are a concise technical writer.",
messages=[{"role": "user", "content": "Explain closures."}]
)max_tokensCaps the response length; short answers need less, long docs need more.
# Short answers: 256-512 | Long docs: 4096-8192 | Max: 128000Reading the Response
content[0].textReads the text of Claude's reply from the response object.
print(message.content[0].text)stop_reasonExplains why generation stopped: end_turn, max_tokens, tool_use, or refusal.
if message.stop_reason == "end_turn":
print(message.content[0].text)usageReports input and output token counts so you can track cost.
print(message.usage.input_tokens)
print(message.usage.output_tokens)message.modelConfirms which model actually served the request.
print(message.model) # e.g. "claude-opus-4-8"Choosing a Model
Claude Opus 4.8Best for hard reasoning and agentic tasks; the default for most new integrations.
claude-opus-4-8Claude Sonnet 5Near-Opus quality on coding and agentic work at a lower cost.
claude-sonnet-5Claude Haiku 4.5Fastest and cheapest option for high-volume tasks like tagging or routing.
claude-haiku-4-5Claude Fable 5Anthropic's most capable model for the hardest, longest-horizon tasks.
claude-fable-5In Practice
Sends a single prompt to Claude, checks the stop reason, and prints the response text and token usage.
- 01Creating the client once and reusing it avoids re-reading credentials on every call.
- 02Passing max_tokens and model explicitly keeps the request valid and predictable in production.
- 03Checking stop_reason before touching content prevents crashes when a response is truncated or refused.
- 04Printing usage after every call makes token cost visible instead of a surprise on the bill.
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system="You are a concise technical writer.",
messages=[{"role": "user", "content": "Explain what a closure is, in two sentences."}]
)
if message.stop_reason == "end_turn":
print(message.content[0].text)
elif message.stop_reason == "max_tokens":
print("Response was cut off - increase max_tokens")
elif message.stop_reason == "refusal":
print("Request declined by safety classifier")
print(f"Tokens used: {message.usage.input_tokens} in / {message.usage.output_tokens} out")FAQ
Set the ANTHROPIC_API_KEY environment variable and the SDK reads it automatically when you create a client. Pass api_key directly to the constructor only if you manage multiple keys or a secrets manager.
Start with claude-opus-4-8 for most new integrations — it balances reasoning quality with cost. Switch to claude-haiku-4-5 for high-volume, latency-sensitive tasks like tagging or routing, and reach for claude-sonnet-5 as a faster, cheaper middle ground.
stop_reason explains why Claude stopped generating: end_turn means a normal finish, max_tokens means the response got cut off, tool_use means Claude called a tool, and refusal means the safety classifier declined the request. Always check it before reading content.
The Messages API requires model, max_tokens, and messages on every request. Missing any of these — most often max_tokens — fails validation before the request is sent, so double-check your payload against the required fields first.
Append each turn to the messages array in order, alternating user and assistant roles. Claude has no memory between calls, so you must resend the full history on every request.
messages = [
{"role": "user", "content": "What is a closure?"},
{"role": "assistant", "content": "A closure captures variables from its enclosing scope."},
{"role": "user", "content": "Give me a JavaScript example."},
]