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

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

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:

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

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

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 – Core route handler for POST /v1/messages, containing request validation, conversion logic, and response mapping
• server/src/routes/proxy.ts – Shared authentication extraction (extractApiToken) and request classification based on the anthropic-version header
• 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 – Helpers for processing Anthropic-specific document blocks and rejection messages
• 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
• 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: 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. 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.

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