FreeLLMAPI Anthropic Messages API Support: Complete Implementation Guide

FreeLLMAPI fully implements the Anthropic Messages API specification—including message completions, token counting, and tool use—by routing requests through a dedicated handler activated by the anthropic-version header.

FreeLLMAPI is an open-source unified gateway that normalizes access to large language model providers. The codebase in tashfeenahmed/freellmapi contains a complete Anthropic compatibility layer that allows existing Claude SDKs and integrations to connect without modification.

Core Router Implementation

The Anthropic Messages API support is defined in server/src/routes/anthropic.ts. This file registers the POST /messages handler at line 439, which validates incoming requests against anthropicMessageSchema and anthropicToolSchema before forwarding them to the appropriate backend provider.

The router activates Anthropic-specific behavior only when requests include the anthropic-version header, ensuring compatibility with official Anthropic client libraries. Request validation includes checking content blocks, tool definitions, and model identifiers against the schemas defined in the shared types.

Model Resolution Architecture

Model mapping and Claude-family discovery occur in server/src/services/anthropic-map.ts. This service translates Anthropic model identifiers like anthropic/claude-3.5-sonnet into internal provider configurations, enabling seamless switching between backend implementations while maintaining the Anthropic API contract.

Document Handling Utilities

Specialized conversion logic for Anthropic document blocks resides in server/src/lib/anthropic-documents.ts. These utilities handle file uploads, content extraction, and rejection scenarios according to the Anthropic specification.

Supported Endpoints and Features

Message Completions (/v1/messages)

The primary endpoint accepts standard Anthropic payload structures including multi-turn conversations, system prompts, and content blocks. The implementation supports streaming and non-streaming responses, maintaining the same JSON structure as the official API.

Token Counting (/v1/messages/count_tokens)

As implemented at line 1044 of server/src/routes/anthropic.ts, FreeLLMAPI provides a /v1/messages/count_tokens endpoint. This allows clients to estimate token usage before sending the full request, using the same counting algorithms as Anthropic's official service.

Tool Use and Function Calling

FreeLLMAPI supports the complete Anthropic tools schema including function definitions, tool_choice parameters, and parallel tool execution. The validation layer ensures that tool input schemas conform to the Anthropic specification before forwarding requests to providers.

Integration Code Examples

Simple Message Completion

The following TypeScript example demonstrates a basic text completion request targeting Claude 3.5 Sonnet through the FreeLLMAPI gateway:

import fetch from 'node-fetch';

const response = await fetch('https://api.freellmapi.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_FREELLMAPI_KEY>',
    'anthropic-version': '2023-06-01'   // enables Anthropic routing
  },
  body: JSON.stringify({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'What is the capital of France?' }],
    max_tokens: 256
  })
});

const data = await response.json();
console.log(data);

Function Calling with Tools

To use the tool use capability, include the tools array and tool_choice parameter in your request:

await fetch('https://api.freellmapi.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_FREELLMAPI_KEY>',
    'anthropic-version': '2023-06-01'
  },
  body: JSON.stringify({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'Translate “hello” to Spanish.' }],
    tools: [
      {
        name: 'translate',
        description: 'Translate text to a target language',
        input_schema: {
          type: 'object',
          properties: {
            text: { type: 'string' },
            target_language: { type: 'string' }
          },
          required: ['text', 'target_language']
        }
      }
    ],
    tool_choice: { type: 'auto' },
    max_tokens: 256
  })
});

Pre-Request Token Counting

Estimate token consumption before making the main request:

await fetch('https://api.freellmapi.com/v1/messages/count_tokens', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_FREELLMAPI_KEY>',
    'anthropic-version': '2023-06-01'
  },
  body: JSON.stringify({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'Explain quantum entanglement.' }]
  })
});

Summary

• FreeLLMAPI implements the complete Anthropic Messages API specification in server/src/routes/anthropic.ts, activated by the anthropic-version header.
• The gateway supports message completions, token counting (at line 1044), and full tool use capabilities with schema validation.
• Model resolution occurs in server/src/services/anthropic-map.ts, handling Claude-family identifier translation.
• Existing Anthropic SDKs can connect to FreeLLMAPI by changing only the base URL and API key, requiring no code changes to request logic.

Frequently Asked Questions

Does FreeLLMAPI require the anthropic-version header?

Yes. The router in server/src/routes/anthropic.ts checks for the anthropic-version header to activate Anthropic-specific routing and validation. Requests without this header will not be processed through the Anthropic compatibility layer, ensuring proper API segregation.

Which Claude models are supported?

FreeLLMAPI supports the entire Claude model family including Claude 3.5 Sonnet, Claude 3 Opus, and Claude 3 Haiku. The server/src/services/anthropic-map.ts service handles discovery and mapping of these identifiers to available backend providers.

Is tool use fully compatible with Anthropic's specification?

Yes. FreeLLMAPI validates tool definitions against anthropicToolSchema and supports parallel tool execution, input schema validation, and the tool_choice parameter. This matches the official Anthropic Messages API behavior for function calling.

How does token counting differ from the official Anthropic API?

The token counting endpoint at /v1/messages/count_tokens follows the same request format and algorithm as Anthropic's official implementation. According to the source code at line 1044 of server/src/routes/anthropic.ts, it processes the identical payload structure to return token estimates before the main completion request.

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