DEV Community

Jovan Chan
Jovan Chan

Posted on • Originally published at aicoderscope.com

Claude API from Scratch: Your First Working Call in 30 Minutes (2026)

#claude #api #setupguide #python

This article was originally published on aicoderscope.com

Most Claude API tutorials start in the middle. They assume you already have a key configured, a virtual environment ready, and a working .env file. If you hit a wall at step two, you're searching Stack Overflow for answers that aren't there.

This guide starts at zero. By the end you'll have made a real API call, know exactly what every line of code does, and understand the five mistakes that waste 90% of beginners' first hour.

Prerequisites

You need three things before touching any code:

Python 3.9+ or Node.js 18+. The Anthropic Python SDK requires Python 3.9 or later (not 3.8). Run python --version or node --version to check. If you're on Python 3.8, upgrade first — the SDK will silently fail or refuse to install.

An Anthropic account. Sign up at console.anthropic.com. The console is separate from the chat interface at claude.ai — you need the console for API keys.

An international credit card. Visa, Mastercard, and Amex work. If you're outside the US and your local card is declined, Wise (virtual Visa) and Payoneer both work reliably. Prepaid cards from most issuers are also accepted. You won't be charged immediately — Anthropic gives new accounts roughly $5 in free trial credits that expire 14 days after you claim them. The minimum credit top-up after that is $5.

Get Your API Key

Navigate to console.anthropic.com and sign in. In the left sidebar, click API Keys, then Create Key. Give it a descriptive name — "dev-local" or "test-2026" — not "key1." You'll thank yourself when you have four keys three months from now.

Copy the key immediately. Anthropic shows it exactly once. If you close that screen without copying, you'll need to delete the key and create a new one.

Store it in a .env file, never in code:

# .env
ANTHROPIC_API_KEY=sk-ant-api03-...your-key-here...
Enter fullscreen mode Exit fullscreen mode

Install python-dotenv to load it automatically:

pip install python-dotenv
Enter fullscreen mode Exit fullscreen mode

Then at the top of any script:

from dotenv import load_dotenv
load_dotenv()
Enter fullscreen mode Exit fullscreen mode

The Anthropic SDK reads ANTHROPIC_API_KEY from the environment automatically once it's loaded. You do not need to pass it explicitly to the client constructor.

Add .env to your .gitignore right now, before you commit anything:

echo ".env" >> .gitignore
Enter fullscreen mode Exit fullscreen mode

This is not optional. API key leaks on GitHub are the single most common beginner mistake in this space. An exposed key will be abused within minutes by automated scanners.

Your First API Call

Python

Install the SDK:

pip install anthropic
Enter fullscreen mode Exit fullscreen mode

Then make your first call:

import os
from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

client = Anthropic()  # reads ANTHROPIC_API_KEY from env automatically

message = client.messages.create(
    model="claude-haiku-4-5",   # cheapest model — good for testing
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain async/await in Python in two sentences."}
    ]
)

print(message.content[0].text)
Enter fullscreen mode Exit fullscreen mode

What every parameter does:

  • model: which Claude model to use. claude-haiku-4-5 costs $1 per million input tokens and $5 per million output tokens — far cheaper than Sonnet or Opus for testing. Switch to claude-sonnet-4-6 ($3/$15) for more nuanced tasks, or claude-opus-4-7 ($15/$75) for your most complex work.
  • max_tokens: the hard cap on how many tokens Claude can output. It will stop mid-sentence if it hits this limit. 1024 is fine for short responses; set it higher for longer ones. You're billed only for actual tokens generated, not the max.
  • messages: a list of conversation turns. Every turn needs a role ("user" or "assistant") and content. For a fresh single query, a one-item list is all you need.

The response object has a content list. The first item (content[0]) is the text block, and .text gives you the string. This feels verbose but lets the SDK return multiple content blocks (e.g., text + tool results) in a single response.

Node.js 

npm install @anthropic-ai/sdk dotenv
Enter fullscreen mode Exit fullscreen mode 
// first-call.mjs
import Anthropic from '@anthropic-ai/sdk';
import 'dotenv/config';

const client = new Anthropic();
// reads process.env.ANTHROPIC_API_KEY automatically

const message = await client.messages.create({
  model: 'claude-haiku-4-5',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain async/await in JavaScript in two sentences.' }
  ]
});

console.log(message.content[0].text);
Enter fullscreen mode Exit fullscreen mode

Run it with node first-call.mjs. The await at the top level requires either a .mjs file or "type": "module" in your package.json. If you're in a CommonJS project, wrap the call in an async function.

cURL

Useful for testing without any SDK setup, or for debugging from a server:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'
Enter fullscreen mode Exit fullscreen mode

Three headers are required:

  • x-api-key: your API key
  • anthropic-version: 2023-06-01: the API version. The SDK sets this header automatically; with raw cURL you must include it or you'll get a 400.
  • content-type: application/json: standard for any JSON POST

The response is JSON. The model's reply is at content[0].text inside the returned object.

What a successful response looks like

Whether Python, Node, or cURL, you'll get back a structure like this:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-4-5",
  "content": [
    {
      "type": "text",
      "text": "Async/await is syntactic sugar over Promises that makes asynchronous code read like synchronous code..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 42
  }
}
Enter fullscreen mode Exit fullscreen mode

stop_reason: "end_turn" means the model finished naturally. If you see "max_tokens" there, Claude hit your limit — raise max_tokens or split the request.

The usage field shows exactly what you were billed. For a test call with Haiku, 18 input + 42 output tokens costs fractions of a cent.

5 Most Common Beginner Mistakes

1. Hitting the 429 rate limit and not knowing why

New Anthropic accounts start on Tier 1, which has conservative rate limits. If you're running a loop that makes dozens of calls per minute, you'll hit a RateLimitError (HTTP 429). The SDK retries automatically twice with exponential backoff, but beyond that it throws.

Handle it explicitly:

import time
from anthropic import RateLimitError

for item in my_list:
    try:
        result = client.messages.create(...)
    except RateLimitError:
        time.sleep(60)  # wait a minute, then continue
        result = client.messages.create(...)
Enter fullscreen mode Exit fullscreen mode

To advance to Tier 2 (higher limits), you need $40 in cumulative API credit purchases. There's no review process — it's automatic once you hit the threshold.

2. API key not in environment

The most common symptom: AuthenticationError or 401. Nine times out of ten the key is set in your terminal but not in the environment your code actually runs in.

Test this first:

python -c "import os; print(os.environ.get('ANTHROPIC_API_KEY', 'NOT SET'))"
Enter fullscreen mode Exit fullscreen mode

If it prints NOT SET, your .env file isn't being loaded. Check that load_dotenv() is called before you instantiate the Anthropic() client, and that your .env file is in the working directory when you run the script.

3. Wrong model name

This trips up everyone who's used the older Claude 3.x models. The naming changed. The old pattern was claude-3-5-sonnet-20241022 — dated, hyphenated, verbose. The current pattern is claude-sonnet-4-6. Thes

Top comments (0)