Using Claude Code and Anthropic SDKs with FreeLLMAPI: A Complete Integration Guide

Yes, FreeLLMAPI fully supports Claude Code and the Anthropic SDK through native Anthropic-compatible endpoints that translate requests to internal OpenAI formats while preserving Claude model identifiers.

FreeLLMAPI (tashfeenahmed/freellmapi) implements a complete Anthropic-compatible API layer that bridges the gap between Anthropic's official tooling and free large language model pools. The server exposes standard /v1/messages and /v1/models endpoints that handle authentication, model resolution, and bidirectional format conversion automatically.

Anthropic-Compatible Endpoints in FreeLLMAPI

Core Route Implementation (server/src/routes/anthropic.ts)

The primary integration point resides in server/src/routes/anthropic.ts, which implements the POST /v1/messages and GET /v1/models endpoints. This file parses incoming Anthropic JSON payloads, converts them to internal ChatMessage objects defined in shared/types.ts, executes the standard routing loop, and transforms responses back to Anthropic's wire format. The route maintains compatibility with Claude Code's expected response structures while routing traffic to free-tier models.

Model Mapping and Resolution (server/src/services/anthropic-map.ts)

Claude family identifiers (such as claude-opus, claude-sonnet, claude-haiku, and default) resolve to concrete catalog models through server/src/services/anthropic-map.ts. The resolveAnthropicModel() function consults the settings table to determine whether to use automatic routing or pinned models. Operators can configure these mappings via the dashboard at /api/settings/anthropic-map or directly through the REST API, allowing specific Claude families to target specific free models like gpt-4o-mini.

Authentication and Session Management (server/src/routes/proxy.ts)

The server/src/routes/proxy.ts file provides unified authentication through extractApiToken(), which accepts both OpenAI-style Authorization: Bearer tokens and Anthropic-style x-api-key headers. For conversation continuity, getStickyModel() and setStickyModel() implement sticky sessions that hash the first user message (or use an explicit session header) to ensure Claude Code sessions maintain consistent model assignments across multiple turns.

Configuring Your Anthropic Client

Base URL and API Key Setup

Point Claude Code or the Anthropic SDK to your FreeLLMAPI instance by setting the base URL to https://your-freellmapi-instance.com/v1. Provide the unified API key either as a bearer token in the Authorization header or as an x-api-key header. The environment variable ANTHROPIC_API_KEY will work automatically with the SDK when the base URL is configured.

Optional Model Pinning

By default, all Claude family requests route to the free-model pool (auto). To pin specific behavior, send a PUT request to /api/settings/anthropic-map with mappings like {"sonnet": "gpt-4o-mini"} to direct Claude Sonnet requests to a specific underlying model.

Implementation Examples

Node.js SDK Configuration

// Example with the official @anthropic/sdk (Node.js)
import { Anthropic } from "@anthropic/sdk";

const client = new Anthropic({
  // Point to your Free LLMAPI instance
  baseURL: "https://my-freellmapi.example.com/v1",
  // Provide the unified API key (can also be set via env var ANTHROPIC_API_KEY)
  apiKey: "sk-freellmapi-xxxxxxxxxxxxxxxx",
});

const response = await client.messages.create({
  model: "claude-3-sonnet-20240229", // any Claude family name works
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explain why the sky is blue." }],
});

console.log(response.content);

Claude Code Configuration

When using Claude Code (the VS Code extension), configure the endpoint through the settings interface:

• Anthropic Base URL: https://my-freellmapi.example.com/v1
• Anthropic API Key: sk-freellmapi-xxxxxxxxxxxxxxxx

Once configured, Claude Code will send requests using identifiers like claude-sonnet-4-5 or claude-opus-20240304 and receive responses from FreeLLMAPI's free model pool.

Direct Model Mapping API

// Directly pin a Claude family to a specific free model (optional)
import fetch from "node-fetch";

await fetch("https://my-freellmapi.example.com/api/settings/anthropic-map", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer sk-freellmapi-xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ sonnet: "gpt-4o-mini" }), // map sonnet family to a catalog model
});

Advanced Features: Tools, Images, and Sticky Sessions

FreeLLMAPI handles Anthropic's native tool definitions and image blocks through bidirectional conversion functions in server/src/routes/proxy.ts. The convertRequest() function transforms Anthropic tool schemas to internal OpenAI-compatible formats, while imageBlockToUrl() and toAnthropicContent() manage image block conversion. Sticky sessions ensure that Claude Code conversations maintain model consistency by hashing the initial message and storing the selected model for subsequent requests in the same session.

Summary

• Full API compatibility: FreeLLMAPI implements POST /v1/messages and GET /v1/models endpoints that are drop-in replacements for Anthropic's official API.
• Flexible authentication: Accepts both Authorization: Bearer and x-api-key headers via extractApiToken() in server/src/routes/proxy.ts.
• Intelligent model mapping: Claude families (opus, sonnet, haiku) resolve to free models through resolveAnthropicModel() in server/src/services/anthropic-map.ts.
• Session persistence: Sticky sessions via getStickyModel() and setStickyModel() ensure conversation continuity for Claude Code users.
• Format translation: Automatic conversion of tools and images through convertRequest(), imageBlockToUrl(), and toAnthropicContent().

Frequently Asked Questions

Does FreeLLMAPI support all Claude model identifiers?

Yes. FreeLLMAPI accepts any Claude family identifier (such as claude-3-opus-20240229, claude-3-sonnet-20240229, or claude-3-haiku-20240307) and resolves it to an available free model through the mapping system in server/src/services/anthropic-map.ts. The response preserves the original Claude identifier while the underlying inference comes from the configured free model pool.

How do I troubleshoot authentication errors with Claude Code?

Ensure you are using the unified API key provided by your FreeLLMAPI instance. The server accepts this key via either the standard Authorization: Bearer <key> header or the Anthropic-specific x-api-key header, as implemented in extractApiToken() within server/src/routes/proxy.ts. Verify that your base URL points to the /v1 path of your FreeLLMAPI instance and not the root domain.

Can I use Anthropic's computer use beta tools with FreeLLMAPI?

Yes. The bidirectional conversion logic in server/src/routes/proxy.ts handles tool definitions through convertRequest() and tool results through toAnthropicContent(). Anthropic tool schemas are automatically translated to OpenAI-compatible function formats for the underlying model, then converted back to Anthropic's expected response structure for the client.

What happens if the free model pool is exhausted during a Claude Code session?

FreeLLMAPI's sticky session mechanism (getStickyModel() in server/src/routes/proxy.ts) binds your conversation to a specific model based on the hash of the first user message. If that specific model becomes unavailable, the router may return an error or fail over depending on your instance configuration. For production use, configure the anthropic-map settings to pin Claude families to specific high-availability models rather than relying on the auto routing pool.

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