# How to Use the Anthropic Messages API with FreeLLMAPI: Complete Implementation Guide

> Implement the Anthropic Messages API with FreeLLMAPI. Access free model pools using Claude-compatible clients by updating your base URL and authentication. Get the complete guide.

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

---

**FreeLLMAPI exposes a fully compatible Anthropic Messages API endpoint that translates requests into its internal routing engine, allowing you to use Claude-compatible clients with free model pools by simply changing the base URL and authentication headers.**

The tashfeenahmed/freellmapi repository implements the Anthropic Messages API as a thin translation layer over its existing OpenAI-compatible infrastructure. By routing requests through `POST /v1/messages` with the appropriate `anthropic-version` header, you can leverage FreeLLMAPI's free model aggregation and automatic fallback systems using any standard Claude client or SDK.

## How the Anthropic Messages API Translation Works

FreeLLMAPI handles Anthropic requests through a four-stage pipeline that maintains full compatibility while routing through free model pools.

### Authentication and Request Validation

When a client sends a request to `POST /v1/messages`, the server first extracts the API key using `extractApiToken` and validates it against the unified dashboard key via `timingSafeStringEqual` in [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts). The system accepts authentication via either the `x-api-key` header or a standard Bearer token in the `Authorization` header.

The request body is parsed using a permissive Zod schema (`messagesSchema`) defined in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) that accepts any content block type plus optional fields including `system`, `tools`, and `thinking` parameters. This schema validation ensures compatibility with the full Anthropic Messages API specification while preparing the payload for internal processing.

### Routing Through the Free Model Pool

After validation, the system transforms the Anthropic payload into the internal `ChatMessage` format using helper functions like `contentToString` and `repairToolArguments`. This conversion allows the request to travel through the same routing machinery used by the OpenAI-compatible endpoints.

The shared routing logic (`routeRequest`, `runFallbackLoop`) selects a free model from the available pool, applies token budgets, enables compression when necessary, and respects model-group preferences. This means **all features**—including streaming, system prompts, tool calling, and image inputs—work identically to the native Anthropic service while benefiting from FreeLLMAPI's provider fallback capabilities.

### Response Conversion and Error Handling

Once the downstream model generates a response, the server maps the internal chat format back to the Anthropic wire format (`AnthropicMessageResponse`). Error responses are rewritten to Anthropic-compatible types (`anthropicErrorType`) and include appropriate `retry-after` headers when rate limits are encountered, ensuring client-side retry logic functions correctly.

The translation occurs only at the request/response boundary, meaning the `GET /v1/models` endpoint also returns Anthropic-shaped model listings when the `anthropic-version` header is present, providing a seamless discovery experience.

## Configuration Requirements

To route Anthropic clients through FreeLLMAPI, configure these three elements:

- **Base URL**: Point clients to your FreeLLMAPI server (the server automatically handles `/v1/messages`)
- **Authentication**: Use your unified FreeLLMAPI key via `x-api-key` header or `Authorization: Bearer ...`
- **Version Header**: Include `anthropic-version: 2023-06-01` to trigger Anthropic protocol handling

Model names like `claude-sonnet-4-5` or `claude-opus-2` map to free-pool families defined in the **Keys → Anthropic** dashboard tab. Each family (`default`, `opus`, `sonnet`, `haiku`) resolves to either an `auto`-selected free model or a specific pinned model you've configured.

## Implementation Examples

### Direct cURL Request

```bash
curl http://localhost:3001/v1/messages \
  -H "x-api-key: freellmapi-your-unified-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"What is the capital of France?"}]
  }'

```

### Claude Code Desktop Client

For macOS or Linux:

```bash
export ANTHROPIC_BASE_URL=http://localhost:3001
export ANTHROPIC_AUTH_TOKEN=freellmapi-your-unified-key
claude

```

For Windows PowerShell:

```powershell
$env:ANTHROPIC_BASE_URL="http://localhost:3001"
$env:ANTHROPIC_AUTH_TOKEN="freellmapi-your-unified-key"
claude

```

Note that Claude Code uses `ANTHROPIC_AUTH_TOKEN` rather than `ANTHROPIC_API_KEY` when pointing to custom endpoints.

### Node.js with Official Anthropic SDK

```javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'freellmapi-your-unified-key',
  baseUrl: 'http://localhost:3001/v1',
});

const response = await client.messages.create({
  model: 'claude-sonnet-4-5',
  maxTokens: 256,
  messages: [{ 
    role: 'user', 
    content: 'Explain quantum entanglement in plain language.' 
  }],
});

console.log(response.content);

```

All examples route through FreeLLMAPI's free-model pool, automatically falling back to working providers if a model exhausts its quota while maintaining full compatibility with Anthropic's tool-calling and streaming semantics.

## Key Source Files

The Anthropic Messages API implementation spans these critical files in the tashfeenahmed/freellmapi repository:

- **[`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts)** – Core route handler for `POST /v1/messages`, containing request validation, conversion logic, and response mapping
- **[`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts)** – Shared authentication extraction (`extractApiToken`) and request classification based on the `anthropic-version` header
- **[`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts)** – Maps Claude model names to free-pool families and provides model discovery entries
- **[`server/src/lib/anthropic-documents.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/anthropic-documents.ts)** – Helpers for processing Anthropic-specific document blocks and rejection messages
- **[`docs/api.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/api.md)** – User-facing documentation for Anthropic/Claude client configuration

## Summary

- **Full API Compatibility**: FreeLLMAPI implements the complete Anthropic Messages API surface, including streaming, tool use, and image inputs
- **Zero-Code Migration**: Change only the base URL and authentication headers to switch existing Claude clients to FreeLLMAPI
- **Unified Routing**: Anthropic requests travel through the same `runFallbackLoop` and `routeRequest` logic as OpenAI requests, ensuring consistent provider failover
- **Model Family Mapping**: Anthropic model names resolve to configurable free-pool families via [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts)
- **Error Parity**: Response errors are rewritten to Anthropic-compatible formats with appropriate retry headers

## Frequently Asked Questions

### Do I need to modify my existing Anthropic SDK code to use FreeLLMAPI?

No. The official Anthropic SDK works unchanged—simply configure the `baseUrl` to point to your FreeLLMAPI instance and provide your unified key. The server handles protocol translation transparently, so features like streaming and tool calling function identically to the native Anthropic API.

### Which authentication methods does FreeLLMAPI accept for Anthropic requests?

FreeLLMAPI accepts two authentication methods validated through `timingSafeStringEqual` in [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts): the `x-api-key` header with your unified key, or a Bearer token via the standard `Authorization: Bearer ...` header. Both methods provide identical access to the free model pool.

### How does FreeLLMAPI handle model selection for Claude-compatible requests?

When you specify a model like `claude-sonnet-4-5`, FreeLLMAPI maps this to a model family defined in [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts). Each family (`opus`, `sonnet`, `haiku`, `default`) either resolves to `auto` (letting the router choose the best available free model) or to a specific model you've pinned in the dashboard configuration.

### Are streaming responses supported through the Anthropic Messages API endpoint?

Yes. Because FreeLLMAPI performs protocol translation only at the boundary, streaming responses flow through the same `runFallbackLoop` machinery used by OpenAI-compatible endpoints. The server handles the conversion between Anthropic's streaming format and the internal message format in real-time via the response conversion logic in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts).