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

By AICoderScope Team · 10 min read
claudeapisetup-guidepythontutorialanthropicbeginner

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...

Install python-dotenv to load it automatically:

pip install python-dotenv

Then at the top of any script:

from dotenv import load_dotenv
load_dotenv()

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

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

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)

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
// 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);

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"}]
  }'

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
  }
}

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(...)

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'))"

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. These are not interchangeable.

Using a nonexistent model string returns a 404 or a validation error. Use exactly one of these three current IDs:

ModelAPI stringPrice (input/output per M tokens)Context
Haiku 4.5claude-haiku-4-5$1 / $5200K
Sonnet 4.6claude-sonnet-4-6$3 / $151M
Opus 4.7claude-opus-4-7$15 / $751M

If you’re migrating from Claude 3.x code, do a project-wide search for any string that matches claude-3 and update it.

4. Outdated SDK version

The anthropic Python package updates frequently — the current release is 0.102.0 (May 2026). If you installed the package months ago and didn’t update, new models will either fail or not appear in autocomplete.

Check your installed version:

python -c "import anthropic; print(anthropic.__version__)"

Update:

pip install --upgrade anthropic

For Node.js, the @anthropic-ai/sdk current version is 0.96.0. npm update @anthropic-ai/sdk handles it.

5. Network and proxy issues (especially outside the US)

If you’re in mainland China, Iran, Russia, or behind a corporate proxy, API calls to api.anthropic.com may time out or return connection errors rather than a clean 401 or 400. The error looks like APIConnectionError in Python, not a rate limit or auth problem.

Solutions that work:

  • Route traffic through a VPN before running your code
  • Set the ANTHROPIC_BASE_URL environment variable to point to a reverse proxy you control
  • Use httpx proxy configuration via the SDK’s http_client parameter:
import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    http_client=DefaultHttpxClient(
        proxy="http://your-proxy:port"
    )
)

This also applies to developers on corporate networks with TLS inspection — you may need to add your company’s root CA to the trust store.

What to Learn Next

Once your first call is working, the order of topics that delivers the most value:

Streaming responses — for any user-facing app, you want tokens to appear in real-time rather than waiting for the full response. The SDK makes this straightforward with client.messages.stream(). Streaming also avoids timeout errors on longer responses.

System prompts — adding a system parameter to your messages.create() call is how you give Claude a persistent persona or behavioral constraints. This is the foundation of every Claude-based product.

Tool use (function calling) — Claude can call Python functions you define. This is the mechanism behind every “AI agent” workflow. The SDK’s @beta_tool decorator generates the schema from your function signature automatically.

Multi-turn conversations — pass the conversation history (all previous user and assistant turns) in the messages array. Claude has no memory between calls; you own the state.

If you’re evaluating AI coding assistants for your daily workflow rather than building with the API, the picture is different — see the Cursor IDE review and the VS Code + Claude Sonnet setup guide for tool comparisons that don’t require writing any API code.

Want the working code without retyping all of it?

I packaged everything in this article — plus extended examples for tool use, vision, prompt caching, batch API, extended thinking, rate-limit retry, and a 100-line CLI chatbot — into a single repo you can git clone and run in 30 minutes.

The kit also includes:

  • A China developer guide (proxies, API forwarders, payment workarounds when you can’t get a direct Anthropic key)
  • A troubleshooting reference covering 30+ common errors with exact fixes
  • A cost optimization playbook to drop a $100/month bill to $20
  • An OpenAI-to-Claude migration guide with side-by-side code diffs

26 files. Python + Node + curl. MIT licensed. $29 — pay with crypto (USDT/USDC/BTC/ETH), 30-day money-back guarantee. After payment you’ll get the download link by email within 24 hours.

Sources

Last updated May 18, 2026. Pricing and model availability change frequently; verify current state at anthropic.com/pricing before building.

Was this article helpful?