claude-api

Claude API (Anthropic Messages API)

Status: Production Ready Last Updated: 2025-10-25 Dependencies: None (standalone API skill) Latest Versions: @anthropic-ai/sdk@0.67.0

Quick Start (5 Minutes)

1. Get API Key

# Sign up at https://console.anthropic.com/
# Navigate to API Keys section
# Create new key and save securely
export ANTHROPIC_API_KEY="sk-ant-..."

Why this matters:

• API key required for all requests
• Keep secure (never commit to git)
• Use environment variables

2. Install SDK (Node.js)

npm install @anthropic-ai/sdk

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

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, Claude!' }],
});

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

CRITICAL:

• Always use server-side (never expose API key in client code)
• Set max_tokens (required parameter)
• Model names are versioned (use latest stable)

3. Or Use Direct API (Cloudflare Workers)

// No SDK needed - use fetch()
const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': env.ANTHROPIC_API_KEY,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});

const data = await response.json();

The Complete Claude API Reference

Table of Contents

1. [Core API](#core-api-messages-api)
2. [Streaming Responses](#streaming-responses-sse)
3. [Prompt Caching](#prompt-caching--90-cost-savings)
4. [Tool Use (Function Calling)](#tool-use-function-calling)
5. [Vision (Image Understanding)](#vision-image-understanding)
6. [Extended Thinking Mode](#extended-thinking-mode)
7. [Rate Limits](#rate-limits)
8. [Error Handling](#error-handling)
9. [Platform Integrations](#platform-integrations)
10. [Known Issues](#known-issues-prevention)

Core API (Messages API)

Available Models (October 2025)

| Model | ID | Context | Best For | Cost (per MTok) | |-------|-----|---------|----------|-----------------| | Claude Sonnet 4.5 | claude-sonnet-4-5-20250929 | 200k tokens | Balanced performance | $3/$15 (in/out) | | Claude 3.7 Sonnet | claude-3-7-sonnet-20250228 | 2M tokens | Extended thinking | $3/$15 | | Claude Opus 4 | claude-opus-4-20250514 | 200k tokens | Highest capability | $15/$75 | | Claude 3.5 Haiku | claude-3-5-haiku-20241022 | 200k tokens | Fast, cost-effective | $1/$5 |

Basic Message Creation

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

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain quantum computing in simple terms' }
  ],
});

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

Multi-Turn Conversations

const messages = [
  { role: 'user', content: 'What is the capital of France?' },
  { role: 'assistant', content: 'The capital of France is Paris.' },
  { role: 'user', content: 'What is its population?' },
];

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages,
});

System Prompts

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: 'You are a helpful Python coding assistant. Always provide type hints and docstrings.',
  messages: [
    { role: 'user', content: 'Write a function to sort a list' }
  ],
});

CRITICAL:

• System prompt MUST come before messages array
• System prompt sets behavior for entire conversation
• Can be 1-10k tokens (affects context window)

Streaming Responses (SSE)

Using SDK Stream Helper

const stream = anthropic.messages.stream({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a short story' }],
});

// Method 1: Event listeners
stream
  .on('text', (text) => {
    process.stdout.write(text);
  })
  .on('message', (message) => {
    console.log('\n\nFinal message:', message);
  })
  .on('error', (error) => {
    console.error('Stream error:', error);
  });

// Wait for completion
await stream.finalMessage();

Streaming with Manual Iteration

const stream = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain AI' }],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

Streaming Event Types

| Event | When | Use Case | |-------|------|----------| | message_start | Message begins | Initialize UI | | content_block_start | New content block | Track blocks | | content_block_delta | Text chunk received | Display text | | content_block_stop | Block complete | Format block | | message_delta | Metadata update | Update stop reason | | message_stop | Message complete | Finalize UI |

Cloudflare Workers Streaming

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'x-api-key': env.ANTHROPIC_API_KEY,
        'anthropic-version': '2023-06-01',
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        model: 'claude-sonnet-4-5-20250929',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello!' }],
        stream: true,
      }),
    });

    // Return SSE stream directly
    return new Response(response.body, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
    });
  },
};

CRITICAL:

• Errors can occur AFTER initial 200 response
• Always implement error event handlers
• Use stream.abort() to cancel
• Set proper Content-Type headers

Prompt Caching (⭐ 90% Cost Savings)

Overview

Prompt caching allows you to cache frequently used context (system prompts, documents, codebases) to:

• Reduce costs by 90% (cache reads = 10% of input token price)
• Reduce latency by 85% (time to first token)
• Cache lifetime: 5 minutes (default) or 1 hour (configurable)

Minimum Requirements

• Claude 3.5 Sonnet: 1,024 tokens minimum
• Claude 3.5 Haiku: 2,048 tokens minimum

Basic Prompt Caching

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'You are an AI assistant analyzing the following codebase...',
    },
    {
      type: 'text',
      text: LARGE_CODEBASE_CONTENT, // 50k tokens
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [
    { role: 'user', content: 'Explain the auth module' }
  ],
});

// Check cache usage
console.log('Cache read tokens:', message.usage.cache_read_input_tokens);
console.log('Cache creation tokens:', message.usage.cache_creation_input_tokens);

Caching in Messages

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Analyze this documentation:',
        },
        {
          type: 'text',
          text: LONG_DOCUMENTATION, // 20k tokens
          cache_control: { type: 'ephe