Claude API cheatsheet

Claude API: Shaping requests

6 common Claude API tasks.

Add a system prompt

Set Claude's role and rules with the top-level system parameter.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    system="You are a helpful coding assistant. Always provide examples in Python.",
    messages=[{"role": "user", "content": "How do I read a JSON file?"}],
)

Continue a conversation

The API is stateless: send the whole history on every request, alternating user and assistant turns.

messages = [
    {"role": "user", "content": "My name is Alice."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
    {"role": "user", "content": "What's my name?"},
]
response = client.messages.create(model="claude-opus-5-5", max_tokens=16000, messages=messages)

Ask about an image

Pass an image by URL, or as base64 with media_type, in the user message before the question.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}},
            {"type": "text", "text": "Describe this image"},
        ],
    }],
)

Control how hard Claude thinks

Use adaptive thinking and set output_config.effort (low, medium, high, xhigh or max) to trade depth against cost and speed.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Solve this step by step..."}],
)

Read thinking and text blocks

Responses can mix thinking and text blocks. Branch on each block's type.

for block in response.content:
    if block.type == "thinking":
        print("Thinking:", block.thinking)
    elif block.type == "text":
        print("Answer:", block.text)

Check why generation stopped

Check stop_reason before using the content: end_turn, max_tokens, tool_use, pause_turn or refusal.

if response.stop_reason == "max_tokens":
    print("Truncated: raise max_tokens or stream the response")
elif response.stop_reason == "refusal":
    print(response.stop_details.category)