# How to Use FreeLLMAPI for Anthropic Claude Messages API: Complete Integration Guide

> Integrate Anthropic Claude Messages API using FreeLLMAPI. This guide shows how to use the compatible endpoint and translate payloads for free model providers.

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

---

**FreeLLMAPI implements a fully Anthropic-compatible Messages endpoint at `POST /v1/messages` that accepts standard Claude API payloads, translates them internally, and routes through free-model providers.**

FreeLLMAPI's Anthropic Claude Messages API integration lets you point any Claude client—whether the official Anthropic SDK, Claude Code, or custom scripts—at your self-hosted instance. The service transparently converts Anthropic-shaped requests into its internal OpenAI-compatible format, executes its free-model fallback engine, and returns Anthropic-compatible responses including Server-Sent Events (SSE) for streaming.

## Architecture Overview

The Anthropic compatibility layer lives in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts). Here's how a request flows through the system:

| Step | Action | Source Location |
|------|--------|-----------------|
| 1 | HTTP `POST /v1/messages` enters via `anthropicRouter` | [`anthropic.ts:45`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L45) |
| 2 | `authenticate` helper validates `x-api-key` against unified API key | [`anthropic.ts:95-103`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L95-L103) |
| 3 | Zod `messagesSchema` validates payload structure | [`anthropic.ts:81-98`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L81-L98) |
| 4 | `convertRequest` translates Anthropic blocks to internal `ChatMessage[]` | [`anthropic.ts:65-66`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L65-L66) |
| 5 | `applyTokenBudget` enforces token limits with optional `compressRequest` | [`anthropic.ts:106-108`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L106-L108) |
| 6 | `resolveAnthropicModel` maps Claude family names to concrete models | [`anthropic.ts:30`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L30) |
| 7 | Sticky session handling via `x-claude-code-session-id` header | [`anthropic.ts:36-38`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L36-L38) |
| 8 | `runFallbackLoop` executes the shared fallback engine | [`anthropic.ts:110-118`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L110-L118) |
| 9 | `toAnthropicContent` converts provider response back to Anthropic shape | [`anthropic.ts:94-114`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L94-L114) |
| 10 | `streamCompletion` handles SSE streaming with Anthropic event types | [`anthropic.ts:70-73`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L70-L73) |

## Authentication and API Keys

FreeLLMAPI uses a **unified API key** system. The same key works for both OpenAI-compatible and Anthropic-compatible routes.

Set the `x-api-key` header to your key from the dashboard:

```bash
curl -X POST https://your-freellmapi-host/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -d '{ "model": "auto", "messages": [...] }'

```

The `authenticate` function in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) validates this against `getUnifiedApiKey` from the database.

## Core API Requests

### Basic Chat Completion

Send a simple non-streaming request:

```bash
curl -X POST https://api.myfreellmapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -d '{
        "model": "auto",
        "max_tokens": 512,
        "messages": [
          { "role": "user", "content": "Explain quantum entanglement in plain English." }
        ]
      }'

```

Key parameters:
- **`model`**: Any Claude family name (`claude-3-opus`, `claude-3.5-sonnet`, `claude-3-haiku`) or `"auto"` for automatic free-model selection
- **`max_tokens`**: Required output token limit (defaults to 1024 if omitted)
- **`messages`**: Array of `{role, content}` objects following Anthropic's format

### Streaming Responses

Enable SSE streaming with `stream: true`:

```bash
curl -N -X POST https://api.myfreellmapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -d '{
        "model": "claude-3.5-sonnet",
        "stream": true,
        "messages": [
          { "role": "user", "content": "Tell me a joke." }
        ]
      }'

```

Use `curl -N` (no buffering) to receive events in real-time. The server emits standard Anthropic SSE events:

```

event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop

```

The `streamCompletion` function handles translation of OpenAI provider streams into this Anthropic event format.

### Tool Use and Function Calling

FreeLLMAPI forwards tool definitions to capable providers and repairs returned tool calls:

```bash
curl -X POST https://api.myfreellmapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -d '{
        "model": "auto",
        "tools": [
          {
            "name": "search",
            "description": "Web search",
            "input_schema": {
              "type": "object",
              "properties": { "query": { "type": "string" } },
              "required": ["query"]
            }
          }
        ],
        "tool_choice": { "type": "auto" },
        "messages": [
          { "role": "user", "content": "Find the tallest mountain in the world." }
        ]
      }'

```

Tool arguments are validated via [`server/src/lib/tool-validate.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/tool-validate.ts) and repaired via [`server/src/lib/tool-args.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/tool-args.ts).

### Multimodal Inputs (Images)

Send images using Anthropic's block format:

```bash
curl -X POST https://api.myfreellmapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -d '{
        "model": "auto",
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "image",
                "source": {
                  "type": "base64",
                  "media_type": "image/png",
                  "data": "<BASE64_DATA>"
                }
              },
              { "type": "text", "text": "Describe this picture." }
            ]
          }
        ]
      }'

```

Images are normalized via [`server/src/lib/image-normalize.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/image-normalize.ts), converted to `image_url` blocks, and token-cost estimated before budget checks.

## Model Resolution and Mapping

The `resolveAnthropicModel` function in [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts) handles model selection:

| Input | Behavior |
|-------|----------|
| `claude-3-opus` | Maps to highest-capability free provider |
| `claude-3.5-sonnet` | Maps to Sonnet-class free model |
| `claude-3-haiku` | Maps to fastest/lightest free model |
| `auto` (default) | FreeLLMAPI selects cheapest available provider |

You can customize mappings in the dashboard or directly edit [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts).

## Session Persistence and Sticky Routing

For clients like **Claude Code** that require consistent model behavior across turns, supply a session ID:

```bash
curl -X POST https://api.myfreellmapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FREE_LLMAPI_KEY" \
  -H "x-claude-code-session-id: my-session-123" \
  -d '{ "model": "auto", "messages": [...] }'

```

The router extracts this header (also accepts `x-session-id`) and pins the session to the same provider/model, preventing model flapping. See [`anthropic.ts:36-38`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L36-L38).

## Token Budgeting and Compression

FreeLLMAPI enforces per-request token limits through [`server/src/lib/guardrails.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/guardrails.ts):

1. `estimateTokens` calculates prompt token count
2. `applyTokenBudget` checks against limits
3. If over budget, `compressRequest` may truncate or summarize
4. Compression status returned in `X-FreeLLM-Compress` header

Set explicit budgets via `max_tokens` or rely on `DEFAULT_MAX_TOKENS` (1024).

## Error Handling

Provider errors map to Anthropic-compatible error types:

| Error Type | Trigger |
|------------|---------|
| `api_error` | Generic provider failure |
| `overloaded_error` | Rate limit or quota exceeded |
| `request_too_large` | Token budget exceeded |
| `not_found_error` | Invalid model reference |

The `anthropicErrorType` helper at [`anthropic.ts:165-170`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts#L165-L170) performs this mapping.

## Key Source Files

| File | Purpose |
|------|---------|
| [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) | Main Anthropic Messages endpoint implementation |
| [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts) | Claude family → catalog model resolution |
| [`server/src/lib/fallback-loop.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/fallback-loop.ts) | Shared provider fallback and retry engine |
| [`server/src/lib/content.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/content.ts) | Content block utilities |
| [`server/src/lib/image-normalize.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/image-normalize.ts) | Image preprocessing and token estimation |
| [`server/src/lib/guardrails.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/guardrails.ts) | Token budget enforcement |
| [`server/src/lib/tool-args.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/tool-args.ts) | Tool argument repair |
| [`server/src/lib/tool-validate.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/tool-validate.ts) | Tool schema validation |
| [`server/src/lib/error-redaction.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/error-redaction.ts) | Error message sanitization |

## Summary

- **FreeLLMAPI's Anthropic Claude Messages API** provides drop-in compatibility at `POST /v1/messages`
- **Unified API key authentication** works across OpenAI and Anthropic routes
- **Automatic model routing** via `"auto"` or explicit Claude family names
- **Full feature parity** including streaming, tools, images, and session persistence
- **Token budgeting and compression** protect against oversized requests
- **Sticky sessions** ensure consistent behavior for multi-turn conversations

## Frequently Asked Questions

### What model names can I use with the FreeLLMAPI Anthropic Claude Messages API?

Use any Claude family identifier (`claude-3-opus`, `claude-3-sonnet`, `claude-3.5-sonnet`, `claude-3-haiku`) or `"auto"` to let FreeLLMAPI select the best available free provider. The mapping logic in [`server/src/services/anthropic-map.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/anthropic-map.ts) resolves these to concrete catalog models at runtime.

### Do I need a separate Anthropic API key to use this integration?

No. FreeLLMAPI uses a **unified API key** system. The same key from your dashboard works for both OpenAI-compatible (`/v1/chat/completions`) and Anthropic-compatible (`/v1/messages`) endpoints. The service handles all provider authentication internally through its free-model pool.

### How does streaming work with Claude Code or other Anthropic clients?

Set `stream: true` in your request. FreeLLMAPI's `streamCompletion` function translates OpenAI provider SSE streams into Anthropic-native events (`message_start`, `content_block_delta`, `message_stop`). Use the `x-claude-code-session-id` header to pin sessions and prevent model switching mid-conversation.

### Can I use tools and image inputs together?

Yes. The `convertRequest` function in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts) handles mixed content blocks including text, images, and tool definitions. Images are normalized via [`server/src/lib/image-normalize.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/image-normalize.ts), tools are validated via [`server/src/lib/tool-validate.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/tool-validate.ts), and the fallback engine routes to providers capable of handling both modalities.