# FreeLLMAPI Anthropic Messages API Support: Complete Implementation Guide

> Explore the FreeLLMAPI Anthropic Messages API implementation guide. Discover full support for completions, token counting, and tool use. Integrate seamlessly with our dedicated handler.

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

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts), it processes the identical payload structure to return token estimates before the main completion request.