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

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

// 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:

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	Documents base URL conventions and unified key authentication
server/src/routes/anthropic.ts	Implements Anthropic-compatible endpoints, accepts x-api-key header
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 for conventions, 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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}