1# Claude API — Python
2 
3## Installation
4 
5```bash
6pip install anthropic
7```
8 
9## Client Initialization
10 
11```python
12import anthropic
13 
14# Default — resolves credentials from the environment:
15# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
16# Prefer this for local dev; don't hardcode a key.
17client = anthropic.Anthropic()
18 
19# Explicit API key (only when you must inject a specific key)
20client = anthropic.Anthropic(api_key="your-api-key")
21 
22# Async client
23async_client = anthropic.AsyncAnthropic()
24```
25 
26---
27 
28## Client Configuration
29 
30### Per-request overrides
31 
32Use `with_options()` to override client settings for a single call without mutating the client:
33 
34```python
35client.with_options(timeout=5.0, max_retries=5).messages.create(
36    model="claude-opus-4-8",
37    max_tokens=1024,
38    messages=[{"role": "user", "content": "Hello"}],
39)
40```
41 
42### Timeouts
43 
44Default request timeout is 10 minutes. Pass a float (seconds) or an `httpx.Timeout` for granular control. On timeout the SDK raises `anthropic.APITimeoutError` (and retries per `max_retries`).
45 
46```python
47import httpx
48 
49client = anthropic.Anthropic(timeout=20.0)
50client = anthropic.Anthropic(
51    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
52)
53```
54 
55### Retries
56 
57The SDK auto-retries connection errors, 408, 409, 429, and ≥500 with exponential backoff (default 2 retries). Set `max_retries` on the client or via `with_options()`; `max_retries=0` disables.
58 
59### Async performance (aiohttp backend)
60 
61For high-concurrency async workloads, install `anthropic[aiohttp]` and pass `DefaultAioHttpClient` instead of the default httpx backend:
62 
63```python
64from anthropic import AsyncAnthropic, DefaultAioHttpClient
65 
66async with AsyncAnthropic(http_client=DefaultAioHttpClient()) as client:
67    ...
68```
69 
70### Custom HTTP client (proxy, base URL)
71 
72Use `DefaultHttpxClient` / `DefaultAsyncHttpxClient` — not raw `httpx.Client` — so the SDK's default timeouts and connection limits are preserved:
73 
74```python
75from anthropic import Anthropic, DefaultHttpxClient
76 
77client = Anthropic(
78    base_url="http://my.test.server.example.com:8083",  # or ANTHROPIC_BASE_URL env var
79    http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com"),
80)
81```
82 
83### Logging
84 
85Set `ANTHROPIC_LOG=debug` (or `info`) to enable SDK logging via the standard `logging` module.
86 
87---
88 
89## Basic Message Request
90 
91```python
92response = client.messages.create(
93    model="claude-opus-4-8",
94    max_tokens=16000,
95    messages=[
96        {"role": "user", "content": "What is the capital of France?"}
97    ]
98)
99# response.content is a list of content block objects (TextBlock, ThinkingBlock,
100# ToolUseBlock, ...). Check .type before accessing .text.
101for block in response.content:
102    if block.type == "text":
103        print(block.text)
104```
105 
106---
107 
108## System Prompts
109 
110```python
111response = client.messages.create(
112    model="claude-opus-4-8",
113    max_tokens=16000,
114    system="You are a helpful coding assistant. Always provide examples in Python.",
115    messages=[{"role": "user", "content": "How do I read a JSON file?"}]
116)
117```
118 
119### Mid-conversation system messages (beta, model-gated)
120 
121For operator instructions that arrive mid-conversation (mode switches, injected state), append `{"role": "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
122 
123```python
124response = client.messages.create(
125    model=MODEL_ID,  # must support mid-conversation system messages
126    max_tokens=16000,
127    system=[{"type": "text", "text": STABLE_SYSTEM, "cache_control": {"type": "ephemeral"}}],
128    messages=history + [
129        {"role": "user", "content": user_message},
130        {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."},
131    ],
132    extra_headers={"anthropic-beta": "mid-conversation-system-2026-04-07"},
133)
134```
135 
136---
137 
138## Vision (Images)
139 
140### Base64
141 
142```python
143import base64
144 
145with open("image.png", "rb") as f:
146    image_data = base64.standard_b64encode(f.read()).decode("utf-8")
147 
148response = client.messages.create(
149    model="claude-opus-4-8",
150    max_tokens=16000,
151    messages=[{
152        "role": "user",
153        "content": [
154            {
155                "type": "image",
156                "source": {
157                    "type": "base64",
158                    "media_type": "image/png",
159                    "data": image_data
160                }
161            },
162            {"type": "text", "text": "What's in this image?"}
163        ]
164    }]
165)
166```
167 
168### URL
169 
170```python
171response = client.messages.create(
172    model="claude-opus-4-8",
173    max_tokens=16000,
174    messages=[{
175        "role": "user",
176        "content": [
177            {
178                "type": "image",
179                "source": {
180                    "type": "url",
181                    "url": "https://example.com/image.png"
182                }
183            },
184            {"type": "text", "text": "Describe this image"}
185        ]
186    }]
187)
188```
189 
190---
191 
192## Prompt Caching
193 
194Cache large context to reduce costs (up to 90% savings). **Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`.
195 
196### Automatic Caching (Recommended)
197 
198Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks:
199 
200```python
201response = client.messages.create(
202    model="claude-opus-4-8",
203    max_tokens=16000,
204    cache_control={"type": "ephemeral"},  # auto-caches the last cacheable block
205    system="You are an expert on this large document...",
206    messages=[{"role": "user", "content": "Summarize the key points"}]
207)
208```
209 
210### Manual Cache Control
211 
212For fine-grained control, add `cache_control` to specific content blocks:
213 
214```python
215response = client.messages.create(
216    model="claude-opus-4-8",
217    max_tokens=16000,
218    system=[{
219        "type": "text",
220        "text": "You are an expert on this large document...",
221        "cache_control": {"type": "ephemeral"}  # default TTL is 5 minutes
222    }],
223    messages=[{"role": "user", "content": "Summarize the key points"}]
224)
225 
226# With explicit TTL (time-to-live)
227response = client.messages.create(
228    model="claude-opus-4-8",
229    max_tokens=16000,
230    system=[{
231        "type": "text",
232        "text": "You are an expert on this large document...",
233        "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1 hour TTL
234    }],
235    messages=[{"role": "user", "content": "Summarize the key points"}]
236)
237```
238 
239### Verifying Cache Hits
240 
241```python
242print(response.usage.cache_creation_input_tokens)  # tokens written to cache (~1.25x cost)
243print(response.usage.cache_read_input_tokens)      # tokens served from cache (~0.1x cost)
244print(response.usage.input_tokens)                 # uncached tokens (full cost)
245```
246 
247If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `datetime.now()` or a UUID in the system prompt, unsorted `json.dumps()`, or a varying tool set. See `shared/prompt-caching.md` for the full audit table.
248 
249---
250 
251## Extended Thinking
252 
253> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
254> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
255 
256```python
257# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
258response = client.messages.create(
259    model="claude-opus-4-8",
260    max_tokens=16000,
261    thinking={"type": "adaptive"},
262    output_config={"effort": "high"},  # low | medium | high | max
263    messages=[{"role": "user", "content": "Solve this step by step..."}]
264)
265 
266# Access thinking and response
267for block in response.content:
268    if block.type == "thinking":
269        print(f"Thinking: {block.thinking}")
270    elif block.type == "text":
271        print(f"Response: {block.text}")
272```
273 
274---
275 
276## Error Handling
277 
278```python
279import anthropic
280 
281try:
282    response = client.messages.create(...)
283except anthropic.BadRequestError as e:
284    print(f"Bad request: {e.message}")
285except anthropic.AuthenticationError:
286    print("Invalid API key")
287except anthropic.PermissionDeniedError:
288    print("API key lacks required permissions")
289except anthropic.NotFoundError:
290    print("Invalid model or endpoint")
291except anthropic.RateLimitError as e:
292    retry_after = int(e.response.headers.get("retry-after", "60"))
293    print(f"Rate limited. Retry after {retry_after}s.")
294except anthropic.APIStatusError as e:
295    if e.status_code >= 500:
296        print(f"Server error ({e.status_code}). Retry later.")
297    else:
298        print(f"API error: {e.message}")
299except anthropic.APIConnectionError:
300    print("Network error. Check internet connection.")
301```
302 
303---
304 
305## Response Helpers
306 
307Every response object exposes `_request_id` (populated from the `request-id` header) — log it when reporting failures to Anthropic. Despite the underscore prefix, this property is public.
308 
309```python
310message = client.messages.create(...)
311print(message._request_id)       # req_018EeWyXxfu5pfWkrYcMdjWG
312print(message.to_json())          # serialize the Pydantic model
313print(message.to_dict())          # plain dict
314```
315 
316To access raw headers or other response metadata, use `.with_raw_response`:
317 
318```python
319raw = client.messages.with_raw_response.create(
320    model="claude-opus-4-8",
321    max_tokens=1024,
322    messages=[{"role": "user", "content": "Hello"}],
323)
324print(raw.headers.get("request-id"))
325message = raw.parse()  # the Message object messages.create() would have returned
326```
327 
328---
329 
330## Multi-Turn Conversations
331 
332The API is stateless — send the full conversation history each time.
333 
334```python
335class ConversationManager:
336    """Manage multi-turn conversations with the Claude API."""
337 
338    def __init__(self, client: anthropic.Anthropic, model: str, system: str = None):
339        self.client = client
340        self.model = model
341        self.system = system
342        self.messages = []
343 
344    def send(self, user_message: str, **kwargs) -> str:
345        """Send a message and get a response."""
346        self.messages.append({"role": "user", "content": user_message})
347 
348        response = self.client.messages.create(
349            model=self.model,
350            max_tokens=kwargs.get("max_tokens", 16000),
351            system=self.system,
352            messages=self.messages,
353            **kwargs
354        )
355 
356        assistant_message = next(
357            (b.text for b in response.content if b.type == "text"), ""
358        )
359        self.messages.append({"role": "assistant", "content": assistant_message})
360 
361        return assistant_message
362 
363# Usage
364conversation = ConversationManager(
365    client=anthropic.Anthropic(),
366    model="claude-opus-4-8",
367    system="You are a helpful assistant."
368)
369 
370response1 = conversation.send("My name is Alice.")
371response2 = conversation.send("What's my name?")  # Claude remembers "Alice"
372```
373 
374**Rules:**
375 
376- Consecutive same-role messages are allowed — the API combines them into a single turn
377- First message must be `user`
378- `role: "system"` messages are allowed mid-conversation under the `mid-conversation-system-2026-04-07` beta on supporting models — see § Mid-conversation system messages above
379 
380---
381 
382### Compaction (long conversations)
383 
384> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
385 
386```python
387import anthropic
388 
389client = anthropic.Anthropic()
390messages = []
391 
392def chat(user_message: str) -> str:
393    messages.append({"role": "user", "content": user_message})
394 
395    response = client.beta.messages.create(
396        betas=["compact-2026-01-12"],
397        model="claude-opus-4-8",
398        max_tokens=16000,
399        messages=messages,
400        context_management={
401            "edits": [{"type": "compact_20260112"}]
402        }
403    )
404 
405    # Append full content — compaction blocks must be preserved
406    messages.append({"role": "assistant", "content": response.content})
407 
408    return next(block.text for block in response.content if block.type == "text")
409 
410# Compaction triggers automatically when context grows large
411print(chat("Help me build a Python web scraper"))
412print(chat("Add support for JavaScript-rendered pages"))
413print(chat("Now add rate limiting and error handling"))
414```
415 
416---
417 
418## Stop Reasons
419 
420The `stop_reason` field in the response indicates why the model stopped generating:
421 
422| Value | Meaning |
423|-------|---------|
424| `end_turn` | Claude finished its response naturally |
425| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming |
426| `stop_sequence` | Hit a custom stop sequence |
427| `tool_use` | Claude wants to call a tool — execute it and continue |
428| `pause_turn` | Model paused and can be resumed (agentic flows) |
429| `refusal` | Claude refused for safety reasons — check `stop_details` |
430 
431### Structured Stop Details
432 
433When `stop_reason` is `"refusal"`, the response includes a `stop_details` object with structured information about the refusal:
434 
435```python
436if response.stop_reason == "refusal" and response.stop_details:
437    print(f"Category: {response.stop_details.category}")   # "cyber" | "bio" | None
438    print(f"Explanation: {response.stop_details.explanation}")
439```
440 
441---
442 
443## Cost Optimization Strategies
444 
445### 1. Use Prompt Caching for Repeated Context
446 
447```python
448# Automatic caching (simplest — caches the last cacheable block)
449response = client.messages.create(
450    model="claude-opus-4-8",
451    max_tokens=16000,
452    cache_control={"type": "ephemeral"},
453    system=large_document_text,  # e.g., 50KB of context
454    messages=[{"role": "user", "content": "Summarize the key points"}]
455)
456 
457# First request: full cost
458# Subsequent requests: ~90% cheaper for cached portion
459```
460 
461### 2. Choose the Right Model
462 
463```python
464# Default to Opus for most tasks
465response = client.messages.create(
466    model="claude-opus-4-8",  # $5.00/$25.00 per 1M tokens
467    max_tokens=16000,
468    messages=[{"role": "user", "content": "Explain quantum computing"}]
469)
470 
471# Use Sonnet for high-volume production workloads
472standard_response = client.messages.create(
473    model="claude-sonnet-4-6",  # $3.00/$15.00 per 1M tokens
474    max_tokens=16000,
475    messages=[{"role": "user", "content": "Summarize this document"}]
476)
477 
478# Use Haiku only for simple, speed-critical tasks
479simple_response = client.messages.create(
480    model="claude-haiku-4-5",  # $1.00/$5.00 per 1M tokens
481    max_tokens=256,
482    messages=[{"role": "user", "content": "Classify this as positive or negative"}]
483)
484```
485 
486### 3. Use Token Counting Before Requests
487 
488```python
489count_response = client.messages.count_tokens(
490    model="claude-opus-4-8",
491    messages=messages,
492    system=system
493)
494 
495estimated_input_cost = count_response.input_tokens * 0.000005  # $5/1M tokens
496print(f"Estimated input cost: ${estimated_input_cost:.4f}")
497```
498 
499---
500 
501## Retry with Exponential Backoff
502 
503> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides.
504 
505```python
506import time
507import random
508import anthropic
509 
510def call_with_retry(
511    client: anthropic.Anthropic,
512    max_retries: int = 5,
513    base_delay: float = 1.0,
514    max_delay: float = 60.0,
515    **kwargs
516):
517    """Call the API with exponential backoff retry."""
518    last_exception = None
519 
520    for attempt in range(max_retries):
521        try:
522            return client.messages.create(**kwargs)
523        except anthropic.RateLimitError as e:
524            last_exception = e
525        except anthropic.APIStatusError as e:
526            if e.status_code >= 500:
527                last_exception = e
528            else:
529                raise  # Client errors (4xx except 429) should not be retried
530 
531        delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
532        print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s")
533        time.sleep(delay)
534 
535    raise last_exception
536```
537