# Anthropic SDK Configuration for FreeLLMAPI: Base URL and Auth Token Setup

> Configure Anthropic SDKs with FreeLLMAPI by setting your baseURL to the FreeLLMAPI /v1 endpoint and using your unified API key for authentication. Get started easily.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-28

---

**To use an Anthropic SDK with FreeLLMAPI, set `baseURL` to your FreeLLMAPI server's `/v1` endpoint and use your unified API key for the `apiKey` parameter.**

FreeLLMAPI implements the Anthropic Messages API through its own routing layer, allowing you to use official Anthropic SDKs and Claude Code with free model backends. This guide covers the exact configuration values needed based on the source code in `tashfeenahmed/freellmapi`.

## Base URL Configuration for Anthropic SDK

Anthropic SDKs automatically append `/v1/messages` to your configured base URL. For FreeLLMAPI, set the base URL to the root of your proxy server followed by `/v1`.

As documented in [`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md) line 7, the standard local development endpoint is:

```

http://localhost:3001/v1

```

For production deployments, substitute your server's actual hostname and port.

### Why `/v1` Matters

The Anthropic SDK constructs full request paths by appending endpoint-specific segments. FreeLLMAPI's Anthropic-compatible routes in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) expect this prefix, ensuring proper routing to the underlying message handling logic.

## Authentication Token Setup

FreeLLMAPI uses a **single unified API key** across all supported provider surfaces. This key works with both authentication patterns:

- **`Authorization: Bearer <key>`** — Standard OAuth-style bearer token
- **`x-api-key: <key>`** — Anthropic-style header (recommended for SDK compatibility)

The Anthropic SDK sends authentication via the `x-api-key` header internally. According to [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) line 43, this route explicitly accepts and validates the `x-api-key` header for incoming requests.

### Obtaining Your Unified Key

Create your API key from the **Keys** page in the FreeLLMAPI dashboard. No provider-specific secrets (like actual Anthropic API keys) are required—FreeLLMAPI handles backend routing to free model providers automatically.

## Complete Code Example with @anthropic-ai/sdk

```typescript
// Example with @anthropic-ai/sdk (npm package)
// npm install @anthropic-ai/sdk
import { Anthropic } from '@anthropic-ai/sdk';

// 1️⃣ Replace with the unified key from your FreeLLMAPI dashboard
const UNIFIED_KEY = 'YOUR_UNIFIED_API_KEY';

// 2️⃣ Create the client, pointing to the FreeLLMAPI proxy
const client = new Anthropic({
  // Base URL of the FreeLLMAPI server (no trailing slash)
  baseURL: 'http://localhost:3001/v1',
  // The Anthropic SDK uses the `x-api-key` header internally.
  // Provide the unified key here.
  apiKey: UNIFIED_KEY,
});

// 3️⃣ Make a request as usual
async function run() {
  const response = await client.messages.create({
    model: 'claude-3-sonnet-20240229', // can be 'auto' for router-selected free model
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, world!' }],
  });
  console.log(response);
}

run().catch(console.error);

```

### Handling anthropic-version Header

Some SDK versions or endpoints require an explicit API version header. Add it to the client configuration:

```typescript
client.headers = {
  ...client.headers,
  'anthropic-version': '2023-06-01', // required for content-negotiated GET /v1/models
};

```

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md) | Documents base URL conventions and unified key authentication |
| [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) | Implements Anthropic-compatible endpoints, accepts `x-api-key` header |
| [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts) | Shared authentication handler for `Authorization: Bearer` and `x-api-key` |

## Troubleshooting SDK Connection Issues

**Connection refused errors** — Verify your FreeLLMAPI server is running and the port matches your `baseURL` configuration.

**Authentication failures** — Confirm you're using the unified key from the FreeLLMAPI dashboard, not an actual Anthropic API key. Check that `apiKey` is passed to the SDK constructor, not as a custom header override.

**Model not found errors** — Use `'auto'` for automatic free model selection, or specify a compatible model identifier. FreeLLMAPI maps Anthropic model names to available free backends.

## Summary

- **Base URL**: Set to `http://localhost:3001/v1` (or your server's `/v1` endpoint)
- **Auth token**: Use your FreeLLMAPI unified key; the SDK sends it as `x-api-key`
- **No Anthropic account needed** — FreeLLMAPI proxies to free model providers
- **Key files**: [`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md) for conventions, [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) for implementation details

## Frequently Asked Questions

### Do I need an Anthropic API key to use FreeLLMAPI?

No. FreeLLMAPI provides a unified API key through its dashboard. This single key authenticates all requests across supported provider surfaces, including the Anthropic-compatible API. The actual backend routing to free LLM providers is handled internally.

### Why does the base URL end with `/v1` instead of `/v1/messages`?

Anthropic SDKs append path segments automatically. Setting `baseURL` to `http://localhost:3001/v1` results in requests to `http://localhost:3001/v1/messages`, which matches FreeLLMAPI's route structure in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts).

### Can I use Claude Code with FreeLLMAPI?

Yes. Configure Claude Code using the same base URL and unified key. The Anthropic-compatible surface accepts the `x-api-key` header that Claude Code sends, as implemented in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) line 43.

### What if my SDK uses `Authorization: Bearer` instead of `x-api-key`?

FreeLLMAPI accepts both headers. The shared authentication logic in [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts) handles `Authorization: Bearer <token>` and `x-api-key: <token>` equivalently. Most Anthropic SDKs use `x-api-key` internally when you provide `apiKey` in the constructor.