Claude API & SDK — Graduate to Code

🤔 When to Use the CLI vs the API

Claude Code CLI is your default tool. The API is a step up — more power, more control, more code. Know when the upgrade is worth it.

The mental model: CLI = you talking to Claude. API = your app talking to Claude. If you're shipping something users will interact with, the API is almost always the right choice.

API Capabilities at a Glance

🔧 SDK Setup

The Anthropic SDK is available in Python and TypeScript/JavaScript. Pick the language that matches your project — the API surface is nearly identical in both.

# Install the SDK
pip install anthropic

# Set your API key (get it at console.anthropic.com)
export ANTHROPIC_API_KEY="sk-ant-..."

# Or add to .env file (use python-dotenv)
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello in one sentence."}]
)

print(message.content[0].text)

# Install the SDK
npm install @anthropic-ai/sdk

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Or use a .env file with dotenv
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();  // reads ANTHROPIC_API_KEY from env

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 256,
  messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
});

console.log(message.content[0].text);

Which model to use?

• claude-opus-4-7 — Most intelligent. Best for complex reasoning, nuanced writing, difficult code. Highest cost.
• claude-sonnet-4-6 — Best balance. Excellent quality at moderate speed and cost. Default for most apps.
• claude-haiku-4-5-20251001 — Fastest and cheapest. Great for classification, extraction, high-volume tasks.

📡 Anatomy of an API Call

Every call to messages.create follows the same structure. Understanding each parameter lets you control exactly what Claude does.

Multi-turn conversation pattern

import anthropic

client = anthropic.Anthropic()
history = []

def chat(user_message):
    history.append({"role": "user", "content": user_message})
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system="You are a concise writing assistant. Keep replies under 3 sentences.",
        messages=history
    )
    assistant_msg = response.content[0].text
    history.append({"role": "assistant", "content": assistant_msg})
    return assistant_msg

# Start chatting
print(chat("Write a tagline for a SaaS invoicing app."))
print(chat("Make it shorter and punchier."))
print(chat("Now write 3 variations."))

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();
const history: Anthropic.MessageParam[] = [];

async function chat(userMessage: string) {
  history.push({ role: 'user', content: userMessage });
  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    system: 'You are a concise writing assistant. Keep replies under 3 sentences.',
    messages: history,
  });
  const assistantMsg = response.content[0].text;
  history.push({ role: 'assistant', content: assistantMsg });
  return assistantMsg;
}

// Start chatting
console.log(await chat('Write a tagline for a SaaS invoicing app.'));
console.log(await chat('Make it shorter and punchier.'));
console.log(await chat('Now write 3 variations.'));

🔨 Tool Use — Claude Calls Your Functions

Tool use (also called function calling) lets Claude trigger structured actions in your code. Instead of asking Claude to return JSON you parse manually, you define a function schema and Claude returns a precise, typed call you execute.

import anthropic, json

client = anthropic.Anthropic()

# 1. Define the tool Claude can call
tools = [{
    "name": "get_word_count",
    "description": "Count words in a piece of text",
    "input_schema": {
        "type": "object",
        "properties": {
            "text": {"type": "string", "description": "Text to count"}
        },
        "required": ["text"]
    }
}]

# 2. Your actual function
def get_word_count(text):
    return {"count": len(text.split()), "characters": len(text)}

# 3. Send request — Claude may call the tool
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    tools=tools,
    messages=[{"role": "user",
               "content": "How many words are in: 'The quick brown fox jumps over the lazy dog'?"}]
)

# 4. Handle tool call if Claude decided to use it
if response.stop_reason == "tool_use":
    tool_call = next(b for b in response.content if b.type == "tool_use")
    result = get_word_count(**tool_call.input)

    # 5. Send result back so Claude can answer
    final = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=256,
        tools=tools,
        messages=[
            {"role": "user", "content": "How many words are in: 'The quick brown fox...'?"},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": [{
                "type": "tool_result",
                "tool_use_id": tool_call.id,
                "content": json.dumps(result)
            }]}
        ]
    )
    print(final.content[0].text)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

// 1. Define the tool Claude can call
const tools: Anthropic.Tool[] = [{
  name: 'get_word_count',
  description: 'Count words in a piece of text',
  input_schema: {
    type: 'object',
    properties: {
      text: { type: 'string', description: 'Text to count' }
    },
    required: ['text']
  }
}];

// 2. Your actual function
function getWordCount(text: string) {
  return { count: text.split(' ').length, characters: text.length };
}

// 3. Send request
const response = await client.messages.create({
  model: 'claude-sonnet-4-6', max_tokens: 512, tools,
  messages: [{ role: 'user', content: 'How many words in: "The quick brown fox..."?' }],
});

// 4. Handle tool call
if (response.stop_reason === 'tool_use') {
  const toolCall = response.content.find(b => b.type === 'tool_use') as Anthropic.ToolUseBlock;
  const result = getWordCount((toolCall.input as any).text);
  // 5. Send result back
  const final = await client.messages.create({
    model: 'claude-sonnet-4-6', max_tokens: 256, tools,
    messages: [
      { role: 'user', content: 'How many words in: "The quick brown fox..."?' },
      { role: 'assistant', content: response.content },
      { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolCall.id, content: JSON.stringify(result) }] }
    ],
  });
  console.log(final.content[0].text);
}

⚡ Streaming — Live Token-by-Token Output

Without streaming, your app waits silently until Claude finishes, then shows the full response at once. With streaming, tokens arrive as they're generated — your UI feels instant, even for long outputs.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a short poem about shipping software."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)  # prints each chunk as it arrives

# After loop: access the final complete message
final_message = stream.get_final_message()
print(f"\n\nTotal tokens: {final_message.usage.input_tokens + final_message.usage.output_tokens}")

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

// stream.text_stream is an async iterable
const stream = client.messages.stream({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a short poem about shipping software.' }],
});

for await (const chunk of stream.text_stream) {
  process.stdout.write(chunk);  // prints each token as it arrives
}

const finalMessage = await stream.finalMessage();
console.log(`\nTotal tokens: ${finalMessage.usage.input_tokens + finalMessage.usage.output_tokens}`);

💾 Prompt Caching — Cut Costs by Up to 90%

If your app sends the same long system prompt (documentation, codebase context, instructions) with every request, you're paying to re-process that content every time. Prompt caching stores it at Anthropic — you pay 10% of normal input cost on cache hits.

import anthropic

client = anthropic.Anthropic()

# Large system prompt (e.g. documentation, codebase, instructions)
SYSTEM_PROMPT = """You are an expert technical writer...
[imagine 2000+ tokens of detailed instructions here]
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"}  # ← this is the only change
    }],
    messages=[{"role": "user", "content": "Summarize the authentication section."}]
)

# Check if cache was used
usage = response.usage
print(f"Cache write: {usage.cache_creation_input_tokens}")
print(f"Cache read:  {usage.cache_read_input_tokens}")

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();
const SYSTEM_PROMPT = `You are an expert technical writer...
[imagine 2000+ tokens of detailed instructions here]
`;

const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  system: [{
    type: 'text',
    text: SYSTEM_PROMPT,
    cache_control: { type: 'ephemeral' },  // ← only change needed
  }],
  messages: [{ role: 'user', content: 'Summarize the authentication section.' }],
});

const { usage } = response;
console.log(`Cache write: ${usage.cache_creation_input_tokens}`);
console.log(`Cache read:  ${usage.cache_read_input_tokens}`);

📦 Batch API — Process Thousands Async

Need to run Claude on 500 support tickets, 10,000 product descriptions, or a month of commit messages? Don't loop through them in real time. Use the Batch API: submit all requests at once, get results when they're ready, pay 50% less.

• Cost: 50% discount vs standard API pricing — no other change required
• Throughput: Up to 100,000 requests per batch
• Latency: Results typically within 1 hour, up to 24 hours max
• Use case: Offline processing, data pipelines, bulk generation — not real-time user interactions

import anthropic

client = anthropic.Anthropic()

# Build a list of requests — each has a custom_id for tracking
tickets = ["Login fails on Safari", "Export button does nothing", "Billing page 500 error"]

requests = [
    anthropic.types.beta.messages.MessageCreateParamsNonStreaming(
        custom_id=f"ticket-{i}",
        params={
            "model": "claude-haiku-4-5-20251001",
            "max_tokens": 128,
            "messages": [{
                "role": "user",
                "content": f"Classify this bug report as Critical/High/Medium/Low. Reply with one word.\n\n{ticket}"
            }]
        }
    )
    for i, ticket in enumerate(tickets)
]

# Submit — returns immediately with a batch ID
batch = client.beta.messages.batches.create(requests=requests)
print(f"Batch submitted: {batch.id} — status: {batch.processing_status}")

# Poll until done (in production, use a webhook or cron job)
import time
while batch.processing_status == "in_progress":
    time.sleep(10)
    batch = client.beta.messages.batches.retrieve(batch.id)

# Retrieve results
for result in client.beta.messages.batches.results(batch.id):
    severity = result.result.message.content[0].text
    print(f"{result.custom_id}: {severity}")

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const tickets = ['Login fails on Safari', 'Export button does nothing', 'Billing page 500 error'];

const requests = tickets.map((ticket, i) => ({
  custom_id: `ticket-${i}`,
  params: {
    model: 'claude-haiku-4-5-20251001',
    max_tokens: 128,
    messages: [{ role: 'user' as const, content: `Classify as Critical/High/Medium/Low. One word.\n\n${ticket}` }],
  },
}));

// Submit
let batch = await client.beta.messages.batches.create({ requests });
console.log(`Batch: ${batch.id} — ${batch.processing_status}`);

// Poll
while (batch.processing_status === 'in_progress') {
  await new Promise(r => setTimeout(r, 10000));
  batch = await client.beta.messages.batches.retrieve(batch.id);
}

// Results
for await (const result of await client.beta.messages.batches.results(batch.id)) {
  const msg = result.result as any;
  console.log(`${result.custom_id}: ${msg.message.content[0].text}`);
}