Introduction

Anthropic’s Claude API opens the door to integrating one of the most capable large language models into your own applications. Whether you’re building a chatbot, a content generator, or an intelligent assistant, the API provides a straightforward HTTP interface that supports both synchronous and streaming responses.

In this guide, you’ll learn how to authenticate, send your first message, handle streaming, and apply practical patterns for production use. We’ll cover the core concepts using both Python and TypeScript, so you can follow along regardless of your stack.

Prerequisites

• An Anthropic API key (get one at console.anthropic.com)
• Basic familiarity with HTTP requests and JSON
• Python 3.8+ or Node.js 18+ installed locally

Authentication

Every request to the Claude API requires an API key sent via the x-api-key header. Keep your key secure—never hardcode it in client-side code or public repositories.

import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

Sending Your First Message

The primary endpoint is POST /v1/messages. You send a list of messages (each with a role and content) and receive a completion.

Python Example

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain quantum computing in one sentence."}
    ]
)
print(message.content[0].text)

TypeScript Example

const msg = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain quantum computing in one sentence.' }
  ],
});
console.log(msg.content[0].text);

Response structure:

• id: unique message identifier
• content: array of content blocks (usually text)
• model: the model used
• usage: token counts for input and output

Streaming Responses

For real-time applications (e.g., chat UIs), streaming reduces perceived latency. The API supports Server-Sent Events (SSE).

Python Streaming

stream = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a short story."}],
    stream=True
)
for event in stream:
    if event.type == "content_block_delta":
        print(event.delta.text, end="")

TypeScript Streaming

const stream = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Tell me a short story.' }],
  stream: true,
});
for await (const event of stream) {
  if (event.type === 'content_block_delta') {
    process.stdout.write(event.delta.text);
  }
}

System Prompts and Instructions

You can guide Claude’s behavior using a system parameter. This is ideal for setting tone, constraints, or role-playing.

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    system="You are a helpful assistant that speaks like a pirate.",
    max_tokens=256,
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

Handling Errors and Retries

Always handle API errors gracefully. Common HTTP status codes:

• 400 – Bad request (e.g., invalid model name)
• 401 – Unauthorized (bad API key)
• 429 – Rate limited
• 500 – Server error

Implement exponential backoff for retries:

import time
import random
def send_with_retry(client, payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(**payload)
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

Best Practices

1. Manage Token Usage

Track usage.input_tokens and usage.output_tokens to control costs. Set max_tokens appropriately—don’t request 4096 tokens if you only need 100.

2. Use the Right Model

• claude-3-5-sonnet-20241022: Best balance of speed and quality
• claude-3-haiku-20240307: Fastest, cheapest, ideal for simple tasks
• claude-3-opus-20240229: Highest quality for complex reasoning

3. Keep Conversations Concise

Include only relevant history in the messages array. Long contexts increase latency and cost. Consider summarizing older turns.

4. Validate Inputs

Sanitize user input before sending it to the API to prevent prompt injection. Never expose your API key in client-side code.

5. Monitor and Log

Log request IDs and response times for debugging. Anthropic’s dashboard provides usage metrics, but local logging helps correlate issues.

Advanced: Multi-turn Conversations

For chat applications, maintain a conversation history by appending assistant responses to the messages array.

conversation = [
    {"role": "user", "content": "What is the weather in Tokyo?"}
]
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=256,
    messages=conversation
)
conversation.append({"role": "assistant", "content": response.content[0].text})
conversation.append({"role": "user", "content": "And what about Osaka?"})
Send again with full history

Conclusion

The Claude API is powerful yet simple to integrate. By mastering authentication, streaming, error handling, and best practices, you can build reliable, cost-effective AI applications. Start with small experiments, monitor your usage, and gradually add complexity.

Key Takeaways

• Authenticate with the x-api-key header and keep your key server-side.
• Use the POST /v1/messages endpoint for all chat completions.
• Enable streaming for real-time user experiences.
• Set max_tokens and choose the right model to control costs.
• Implement retry logic with exponential backoff for production reliability.