Using the Claude API with Python: Setup to Production

Setup is three commands. Install the SDK, export your key from console.anthropic.com, and verify with a one-liner:

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

import anthropic
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
msg = client.messages.create(
    model="claude-sonnet-5", max_tokens=256,
    messages=[{"role": "user", "content": "Say hello in Hindi."}],
)
print(msg.content[0].text)

Never pass the key as a string literal in code — the zero-argument constructor reading the environment is the correct pattern for every environment from laptop to Kubernetes. For async applications, anthropic.AsyncAnthropic() exposes the identical surface with await.

Three parameters are required — model, max_tokens, messages — and two optional ones do most of the steering: system (role and rules, kept separate from user content) and temperature-style behavior controls where the model supports them. Choose the model by task: claude-haiku-4-5 for high-volume simple work, claude-sonnet-5 as the default, claude-opus-4-8 or claude-fable-5 for the hardest reasoning (see our model guide).

Responses are Pydantic objects. The two fields to internalize:

• content — a list of typed blocks; always check block.type == “text” rather than assuming index zero is text.
• usage — exact input and output token counts; log this on every call.

Also check stop_reason: “max_tokens” means your output was truncated and the ceiling needs raising.

The API is stateless, so your application owns the history: append each assistant reply to a list and resend it. A minimal conversation manager is a dozen lines:

history = []
def chat(user_text: str) -> str:
    history.append({"role": "user", "content": user_text})
    msg = client.messages.create(
        model="claude-sonnet-5", max_tokens=1024,
        system="You are a concise engineering assistant.",
        messages=history,
    )
    reply = next(b.text for b in msg.content if b.type == "text")
    history.append({"role": "assistant", "content": reply})
    return reply

Two rules: the first message must be a user turn, and history is re-billed as input every call — so trim or summarize old turns in long sessions, and put a cache_control breakpoint on your stable system prompt to make repeated context cheap.

For anything user-facing, stream. The SDK’s context-manager helper hides the server-sent-events plumbing and still gives you the complete message at the end:

with client.messages.stream(
    model="claude-sonnet-5", max_tokens=2048,
    messages=[{"role": "user", "content": "Draft a REST API design doc."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()
print(final.usage.output_tokens)

Streaming is not just UX polish: for large max_tokens values the SDK requires it, because a long non-streaming request risks HTTP timeouts. Rule of thumb — stream anything that might exceed a few thousand output tokens, and always call get_final_message() when you need usage data or the assembled text.

The SDK raises typed exceptions per HTTP status and auto-retries rate limits and server errors with exponential backoff (configurable via max_retries). Catch specific classes, most specific first — never string-match error messages:

try:
    msg = client.messages.create(**params)
except anthropic.RateLimitError:
    ...  # queue or shed load; SDK already retried
except anthropic.APIStatusError as e:
    log.error("api_error", status=e.status_code)
except anthropic.APIConnectionError:
    ...  # network problem — retry with backoff

Separate retryable failures (429, 5xx, connection errors) from non-retryable ones (400 bad request, 404 wrong model ID) in your handling — retrying a malformed request just burns quota. Log the request ID from failed responses; Anthropic support can trace it end-to-end.