Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

Added Anthropic compatible APIs (#361)

Tashfeenc5e4a34de09a
diff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.json
index 9372d616..a13799ab 100644
--- a/client/src/i18n/locales/en.json
+++ b/client/src/i18n/locales/en.json
@@ -170,6 +170,20 @@
"endpointResponses": "Responses",
"endpointEmbeddings": "Embeddings",
"endpointEmbeddingsHint": "model: \"auto\" or a family from the Embeddings tab",
+ "endpointMessages": "Messages",
+ "endpointMessagesHint": "Anthropic-compatible (Claude)",
+ "anthropicTitle": "Claude (Anthropic) models",
+ "anthropicDesc": "Point a Claude or Anthropic SDK client at this server. Anthropic clients send Claude model names — map each to Auto (the router picks a free model) or pin a specific one.",
+ "anthropicBaseUrl": "Base URL",
+ "anthropicAuth": "Auth header",
+ "anthropicAuto": "Auto — router picks the best model",
+ "anthropicSave": "Save mapping",
+ "anthropicSaved": "Saved",
+ "anthropicNote": "Anthropic clients keep their built-in Claude model names; the mapping above decides how each one routes into your pool.",
+ "familyDefault": "Default",
+ "familyOpus": "Opus",
+ "familySonnet": "Sonnet",
+ "familyHaiku": "Haiku",
"selectPlatform": "Select a provider",
"addKey": "Add key",
"adding": "Adding…",
diff --git a/client/src/i18n/locales/es.json b/client/src/i18n/locales/es.json
index 5cc8bd85..47c0e7d0 100644
--- a/client/src/i18n/locales/es.json
+++ b/client/src/i18n/locales/es.json
@@ -153,6 +153,20 @@
"endpointResponses": "Responses",
"endpointEmbeddings": "Embeddings",
"endpointEmbeddingsHint": "model: «auto» o una familia de la pestaña Embeddings",
+ "endpointMessages": "Messages",
+ "endpointMessagesHint": "Compatible con Anthropic (Claude)",
+ "anthropicTitle": "Modelos Claude (Anthropic)",
+ "anthropicDesc": "Apunta un cliente SDK de Claude o Anthropic a este servidor. Los clientes de Anthropic envían nombres de modelos Claude: asigna cada uno a Auto (el router elige un modelo gratuito) o fija uno específico.",
+ "anthropicBaseUrl": "URL base",
+ "anthropicAuth": "Encabezado de autenticación",
+ "anthropicAuto": "Auto — el router elige el mejor modelo",
+ "anthropicSave": "Guardar asignación",
+ "anthropicSaved": "Guardado",
+ "anthropicNote": "Los clientes de Anthropic conservan sus nombres de modelos Claude integrados; la asignación de arriba decide cómo se enruta cada uno hacia tu grupo.",
+ "familyDefault": "Predeterminado",
+ "familyOpus": "Opus",
+ "familySonnet": "Sonnet",
+ "familyHaiku": "Haiku",
"selectPlatform": "Selecciona un proveedor",
"addKey": "Añadir clave",
"adding": "Añadiendo…",
diff --git a/client/src/i18n/locales/fr.json b/client/src/i18n/locales/fr.json
index 8a861b90..8b6b0407 100644
--- a/client/src/i18n/locales/fr.json
+++ b/client/src/i18n/locales/fr.json
@@ -153,6 +153,20 @@
"endpointResponses": "Responses",
"endpointEmbeddings": "Embeddings",
"endpointEmbeddingsHint": "model : « auto » ou une famille de l'onglet Embeddings",
+ "endpointMessages": "Messages",
+ "endpointMessagesHint": "Compatible Anthropic (Claude)",
+ "anthropicTitle": "Modèles Claude (Anthropic)",
+ "anthropicDesc": "Pointez un client SDK Claude ou Anthropic vers ce serveur. Les clients Anthropic envoient des noms de modèles Claude — associez chacun à Auto (le routeur choisit un modèle gratuit) ou fixez-en un précis.",
+ "anthropicBaseUrl": "URL de base",
+ "anthropicAuth": "En-tête d'authentification",
+ "anthropicAuto": "Auto — le routeur choisit le meilleur modèle",
+ "anthropicSave": "Enregistrer le mappage",
+ "anthropicSaved": "Enregistré",
+ "anthropicNote": "Les clients Anthropic conservent leurs noms de modèles Claude intégrés ; le mappage ci-dessus décide de l'acheminement de chacun vers votre pool.",
+ "familyDefault": "Par défaut",
+ "familyOpus": "Opus",
+ "familySonnet": "Sonnet",
+ "familyHaiku": "Haiku",
"selectPlatform": "Sélectionner un fournisseur",
"addKey": "Ajouter une clé",
"adding": "Ajout…",
diff --git a/client/src/i18n/locales/pt-BR.json b/client/src/i18n/locales/pt-BR.json
index 6ff30402..82b1de11 100644
--- a/client/src/i18n/locales/pt-BR.json
+++ b/client/src/i18n/locales/pt-BR.json
@@ -153,6 +153,20 @@
"endpointResponses": "Responses",
"endpointEmbeddings": "Embeddings",
"endpointEmbeddingsHint": "model: \"auto\" ou uma família da aba Embeddings",
+ "endpointMessages": "Messages",
+ "endpointMessagesHint": "Compatível com Anthropic (Claude)",
+ "anthropicTitle": "Modelos Claude (Anthropic)",
+ "anthropicDesc": "Aponte um cliente SDK do Claude ou da Anthropic para este servidor. Os clientes da Anthropic enviam nomes de modelos Claude — mapeie cada um para Auto (o roteador escolhe um modelo gratuito) ou fixe um específico.",
+ "anthropicBaseUrl": "URL base",
+ "anthropicAuth": "Cabeçalho de autenticação",
+ "anthropicAuto": "Auto — o roteador escolhe o melhor modelo",
+ "anthropicSave": "Salvar mapeamento",
+ "anthropicSaved": "Salvo",
+ "anthropicNote": "Os clientes da Anthropic mantêm seus nomes de modelos Claude integrados; o mapeamento acima decide como cada um é roteado para o seu pool.",
+ "familyDefault": "Padrão",
+ "familyOpus": "Opus",
+ "familySonnet": "Sonnet",
+ "familyHaiku": "Haiku",
"selectPlatform": "Selecione um provedor",
"addKey": "Adicionar chave",
"adding": "Adicionando…",
diff --git a/client/src/i18n/locales/zh-CN.json b/client/src/i18n/locales/zh-CN.json
index 79a4e5aa..b1921aa1 100644
--- a/client/src/i18n/locales/zh-CN.json
+++ b/client/src/i18n/locales/zh-CN.json
@@ -153,6 +153,20 @@
"endpointResponses": "响应",
"endpointEmbeddings": "嵌入",
"endpointEmbeddingsHint": "model: \"auto\" 或「嵌入模型」标签中的系列",
+ "endpointMessages": "Messages",
+ "endpointMessagesHint": "兼容 Anthropic(Claude)",
+ "anthropicTitle": "Claude(Anthropic)模型",
+ "anthropicDesc": "将 Claude 或 Anthropic SDK 客户端指向此服务器。Anthropic 客户端会发送 Claude 模型名称——将每个名称映射为 Auto(由路由器挑选一个免费模型)或固定为某个指定模型。",
+ "anthropicBaseUrl": "Base URL",
+ "anthropicAuth": "鉴权请求头",
+ "anthropicAuto": "Auto — 由路由器挑选最佳模型",
+ "anthropicSave": "保存映射",
+ "anthropicSaved": "已保存",
+ "anthropicNote": "Anthropic 客户端会保留其内置的 Claude 模型名称;上方的映射决定每个名称如何路由到你的资源池。",
+ "familyDefault": "默认",
+ "familyOpus": "Opus",
+ "familySonnet": "Sonnet",
+ "familyHaiku": "Haiku",
"selectPlatform": "选择提供商",
"addKey": "添加密钥",
"adding": "添加中…",
diff --git a/client/src/pages/KeysPage.tsx b/client/src/pages/KeysPage.tsx
index 093a0df7..fc3484fb 100644
--- a/client/src/pages/KeysPage.tsx
+++ b/client/src/pages/KeysPage.tsx
@@ -13,6 +13,19 @@ import { Pencil, ExternalLink, Globe } from 'lucide-react'
import { formatSqliteUtcToLocalTime } from '@/lib/utils'
import { useI18n } from '@/i18n'
+// Claude (Anthropic) model families the mapping editor exposes. Anthropic
+// clients send these names; each maps to "auto" (router picks a free model) or
+// a pinned catalog model. Mirrors services/anthropic-map.ts on the server.
+type ClaudeFamily = 'default' | 'opus' | 'sonnet' | 'haiku'
+type AnthropicMap = Record<ClaudeFamily, string>
+interface MappableModel { modelId: string; displayName: string; enabled: boolean }
+const FAMILY_ORDER: { key: ClaudeFamily; labelKey: string }[] = [
+ { key: 'default', labelKey: 'keys.familyDefault' },
+ { key: 'opus', labelKey: 'keys.familyOpus' },
+ { key: 'sonnet', labelKey: 'keys.familySonnet' },
+ { key: 'haiku', labelKey: 'keys.familyHaiku' },
+]
+
// Small "Get API key" external link shown next to a provider (#137).
function GetKeyLink({ url }: { url: string }) {
const { t } = useI18n()
@@ -170,6 +183,8 @@ function UnifiedKeySection() {
<code className="font-mono">/v1/chat/completions</code>
<span className="text-muted-foreground">{t('keys.endpointResponses')}</span>
<code className="font-mono">/v1/responses</code>
+ <span className="text-muted-foreground">{t('keys.endpointMessages')}</span>
+ <code className="font-mono">/v1/messages <span className="text-muted-foreground">({t('keys.endpointMessagesHint')})</span></code>
<span className="text-muted-foreground">{t('keys.endpointEmbeddings')}</span>
<code className="font-mono">/v1/embeddings <span className="text-muted-foreground">({t('keys.endpointEmbeddingsHint')})</span></code>
</div>
@@ -377,6 +392,88 @@ function CustomProviderSection() {
)
}
+// Claude (Anthropic) model mapping: point a Claude / Anthropic SDK client at
+// this server and decide how its built-in model names route into the free pool.
+function AnthropicSection() {
+ const { t } = useI18n()
+ const queryClient = useQueryClient()
+
+ // Anthropic clients append `/v1/messages` to the base URL, so they want the
+ // bare origin (OpenAI clients use origin + /v1, shown in the key section).
+ const origin = import.meta.env.DEV
+ ? `http://${window.location.hostname}:${__SERVER_PORT__}`
+ : window.location.origin
+
+ const { data: mapData } = useQuery<{ map: AnthropicMap }>({
+ queryKey: ['anthropic-map'],
+ queryFn: () => apiFetch('/api/settings/anthropic-map'),
+ })
+ const { data: models = [] } = useQuery<MappableModel[]>({
+ queryKey: ['fallback'],
+ queryFn: () => apiFetch('/api/fallback'),
+ })
+
+ const [draft, setDraft] = useState<AnthropicMap | null>(null)
+ useEffect(() => { if (mapData?.map) setDraft(mapData.map) }, [mapData])
+
+ const save = useMutation({
+ mutationFn: (map: AnthropicMap) => apiFetch('/api/settings/anthropic-map', { method: 'PUT', body: JSON.stringify(map) }),
+ onSuccess: () => queryClient.invalidateQueries({ queryKey: ['anthropic-map'] }),
+ })
+
+ // Dedup catalog models by id; only enabled models can be pinned.
+ const modelOptions = Array.from(new Map(models.filter(m => m.enabled).map(m => [m.modelId, m])).values())
+ .sort((a, b) => a.displayName.localeCompare(b.displayName))
+ const dirty = !!(draft && mapData?.map && JSON.stringify(draft) !== JSON.stringify(mapData.map))
+
+ return (
+ <section className="rounded-3xl border bg-card p-5">
+ <div className="flex items-start justify-between gap-4 mb-3">
+ <div>
+ <h2 className="text-sm font-medium">{t('keys.anthropicTitle')}</h2>
+ <p className="text-xs text-muted-foreground mt-0.5 max-w-prose">{t('keys.anthropicDesc')}</p>
+ </div>
+ <Button size="sm" disabled={!dirty || save.isPending} onClick={() => draft && save.mutate(draft)}>
+ {save.isSuccess && !dirty ? t('keys.anthropicSaved') : t('keys.anthropicSave')}
+ </Button>
+ </div>
+
+ <div className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 text-xs mb-4">
+ <span className="text-muted-foreground">{t('keys.anthropicBaseUrl')}</span>
+ <code className="font-mono break-all">{origin}</code>
+ <span className="text-muted-foreground">{t('keys.anthropicAuth')}</span>
+ <code className="font-mono">x-api-key</code>
+ </div>
+
+ <div className="space-y-2">
+ {FAMILY_ORDER.map(({ key, labelKey }) => (
+ <div key={key} className="flex items-center gap-3">
+ <span className="w-40 text-xs font-medium shrink-0">{t(labelKey)}</span>
+ <Select
+ value={draft?.[key] ?? 'auto'}
+ onValueChange={(v) => setDraft(d => (d ? { ...d, [key]: v } : d))}
+ >
+ <SelectTrigger className="w-[320px] max-w-full"><SelectValue /></SelectTrigger>
+ <SelectContent>
+ <SelectItem value="auto">{t('keys.anthropicAuto')}</SelectItem>
+ {/* Keep a currently-pinned-but-now-disabled model selectable. */}
+ {draft?.[key] && draft[key] !== 'auto' && !modelOptions.some(m => m.modelId === draft[key]) && (
+ <SelectItem value={draft[key]}>{draft[key]}</SelectItem>
+ )}
+ {modelOptions.map(m => (
+ <SelectItem key={m.modelId} value={m.modelId}>{m.displayName}</SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ ))}
+ </div>
+
+ <p className="text-xs text-muted-foreground mt-4 max-w-prose">{t('keys.anthropicNote')}</p>
+ </section>
+ )
+}
+
export default function KeysPage() {
const { t } = useI18n()
const queryClient = useQueryClient()
@@ -542,6 +639,8 @@ export default function KeysPage() {
<div className="space-y-8">
<UnifiedKeySection />
+ <AnthropicSection />
+
<ProxySettingsSection />
<section>
diff --git a/server/src/__tests__/routes/anthropic.test.ts b/server/src/__tests__/routes/anthropic.test.ts
new file mode 100644
index 00000000..374af0f8
--- /dev/null
+++ b/server/src/__tests__/routes/anthropic.test.ts
@@ -0,0 +1,357 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
+import { mintDashboardToken } from '../helpers/auth.js';
+
+// Anthropic-compatible Messages API (`POST /v1/messages`). These tests drive
+// the route end-to-end through a mocked Groq upstream and assert the Anthropic
+// wire format both inbound (system / content blocks / tool_use / tool_result /
+// images) and outbound (message envelope, tool_use blocks, SSE event sequence)
+// — i.e. what Claude Code actually sends and parses.
+
+let dashToken = '';
+
+async function request(app: Express, path: string, body: any, extraHeaders: Record<string, string> = {}) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const res = await fetch(`http://127.0.0.1:${addr.port}${path}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...extraHeaders },
+ body: JSON.stringify(body),
+ });
+ const text = await res.text();
+ server.close();
+ let json: any = null;
+ try { json = JSON.parse(text); } catch { /* SSE body */ }
+ return { status: res.status, headers: res.headers, text, body: json };
+}
+
+async function send(app: Express, method: string, path: string, body?: any, extraHeaders: Record<string, string> = {}) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const res = await fetch(`http://127.0.0.1:${addr.port}${path}`, {
+ method,
+ headers: { ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...extraHeaders },
+ body: body !== undefined ? JSON.stringify(body) : undefined,
+ });
+ const text = await res.text();
+ server.close();
+ let json: any = null;
+ try { json = JSON.parse(text); } catch { /* non-JSON */ }
+ return { status: res.status, headers: res.headers, text, body: json };
+}
+
+function anthropicHeaders() {
+ return { 'x-api-key': getUnifiedApiKey(), 'anthropic-version': '2023-06-01' };
+}
+
+/** Parse an SSE body into ordered {event, data} pairs. */
+function sseEvents(text: string): Array<{ event: string; data: any }> {
+ const events: Array<{ event: string; data: any }> = [];
+ for (const block of text.split('\n\n')) {
+ let event: string | null = null;
+ let data: string | null = null;
+ for (const line of block.split('\n')) {
+ if (line.startsWith('event: ')) event = line.slice(7).trim();
+ else if (line.startsWith('data: ')) data = line.slice(6);
+ }
+ if (event && data) { try { events.push({ event, data: JSON.parse(data) }); } catch { /* ignore */ } }
+ }
+ return events;
+}
+
+const sse = (...payloads: (object | string)[]) =>
+ payloads.map(p => `data: ${typeof p === 'string' ? p : JSON.stringify(p)}\n\n`).join('');
+
+// Mock Groq's chat-completions upstream with a single canned JSON response, and
+// capture the request body the provider forwarded (post-translation).
+function mockJson(response: any) {
+ const origFetch = global.fetch;
+ const captured: { body: any } = { body: null };
+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+ const urlStr = typeof url === 'string' ? url : url.toString();
+ if (urlStr.includes('api.groq.com/openai/v1/chat/completions')) {
+ captured.body = JSON.parse(String((init as RequestInit).body));
+ return { ok: true, json: () => Promise.resolve(response) } as any;
+ }
+ return origFetch(url as any, init);
+ });
+ return captured;
+}
+
+// Mock Groq's streaming upstream with a raw SSE body.
+function mockStream(body: string) {
+ const origFetch = global.fetch;
+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+ const urlStr = typeof url === 'string' ? url : url.toString();
+ if (urlStr.includes('api.groq.com/openai/v1/chat/completions')) {
+ return new Response(body, { status: 200, headers: { 'Content-Type': 'text/event-stream' } });
+ }
+ return origFetch(url as any, init);
+ });
+}
+
+const textCompletion = (text: string) => ({
+ id: 'chatcmpl-x', object: 'chat.completion', created: 1, model: 'openai/gpt-oss-120b',
+ choices: [{ index: 0, message: { role: 'assistant', content: text }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 11, completion_tokens: 7, total_tokens: 18 },
+});
+
+const toolCompletion = (name: string, args: string) => ({
+ id: 'chatcmpl-t', object: 'chat.completion', created: 1, model: 'openai/gpt-oss-120b',
+ choices: [{ index: 0, message: { role: 'assistant', content: null, tool_calls: [{ id: 'call_1', type: 'function', function: { name, arguments: args } }] }, finish_reason: 'tool_calls' }],
+ usage: { prompt_tokens: 12, completion_tokens: 4, total_tokens: 16 },
+});
+
+const WEATHER_TOOL = {
+ name: 'get_weather',
+ description: 'Get current weather',
+ input_schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+};
+
+describe('Anthropic-compatible /v1/messages', () => {
+ let app: Express;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ dashToken = mintDashboardToken();
+ });
+
+ beforeEach(async () => {
+ const db = getDb();
+ db.prepare('DELETE FROM api_keys').run();
+ db.prepare('DELETE FROM requests').run();
+ db.prepare('DELETE FROM rate_limit_cooldowns').run();
+ db.prepare('DELETE FROM rate_limit_usage').run();
+ db.prepare("DELETE FROM settings WHERE key = 'anthropic_model_map'").run();
+ const { status } = await request(app, '/api/keys',
+ { platform: 'groq', key: 'gsk_anthropic_test', label: 't' },
+ { Authorization: `Bearer ${dashToken}` });
+ expect(status).toBe(201);
+ });
+
+ afterEach(() => vi.restoreAllMocks());
+
+ it('rejects a request with no API key (Anthropic error envelope)', async () => {
+ const { status, body } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', max_tokens: 64, messages: [{ role: 'user', content: 'hi' }],
+ });
+ expect(status).toBe(401);
+ expect(body.type).toBe('error');
+ expect(body.error.type).toBe('authentication_error');
+ });
+
+ it('authenticates via the Anthropic x-api-key header and returns a Messages response', async () => {
+ mockJson(textCompletion('Hello from a free model.'));
+ const { status, body, headers } = await request(app, '/v1/messages', {
+ model: 'claude-3-5-sonnet-20241022', max_tokens: 64,
+ messages: [{ role: 'user', content: 'hi' }],
+ }, anthropicHeaders());
+
+ expect(status).toBe(200);
+ expect(body.type).toBe('message');
+ expect(body.role).toBe('assistant');
+ expect(body.model).toBe('claude-3-5-sonnet-20241022'); // echoes the requested id
+ expect(body.content).toEqual([{ type: 'text', text: 'Hello from a free model.' }]);
+ expect(body.stop_reason).toBe('end_turn');
+ expect(body.usage).toEqual({ input_tokens: 11, output_tokens: 7 });
+ expect(body.id).toMatch(/^msg_/);
+ expect(headers.get('x-routed-via')).toMatch(/^groq\//);
+ });
+
+ it('forwards the system prompt and tools, returns a tool_use block (stop_reason tool_use)', async () => {
+ const captured = mockJson(toolCompletion('get_weather', '{"city":"Karachi"}'));
+ const { status, body } = await request(app, '/v1/messages', {
+ model: 'claude-opus-4-1', max_tokens: 128,
+ system: 'You are a weather bot.',
+ messages: [{ role: 'user', content: 'weather in Karachi?' }],
+ tools: [WEATHER_TOOL],
+ tool_choice: { type: 'auto' },
+ }, anthropicHeaders());
+
+ expect(status).toBe(200);
+ // Inbound translation: system → system message, tool input_schema → parameters.
+ expect(captured.body.messages[0]).toEqual({ role: 'system', content: 'You are a weather bot.' });
+ expect(captured.body.tools[0].function.name).toBe('get_weather');
+ expect(captured.body.tools[0].function.parameters.required).toEqual(['city']);
+ expect(captured.body.tool_choice).toBe('auto');
+
+ // Outbound translation: tool_calls → tool_use block with parsed input.
+ expect(body.stop_reason).toBe('tool_use');
+ const toolUse = body.content.find((b: any) => b.type === 'tool_use');
+ expect(toolUse).toMatchObject({ type: 'tool_use', name: 'get_weather', input: { city: 'Karachi' } });
+ expect(typeof toolUse.id).toBe('string');
+ });
+
+ it('translates an assistant tool_use + user tool_result turn into OpenAI tool messages', async () => {
+ const captured = mockJson(textCompletion('It is sunny and 35C in Karachi.'));
+ const { status, body } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', max_tokens: 128,
+ messages: [
+ { role: 'user', content: 'weather in Karachi?' },
+ { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_abc', name: 'get_weather', input: { city: 'Karachi' } }] },
+ { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'toolu_abc', content: 'Sunny, 35C' }] },
+ ],
+ tools: [WEATHER_TOOL],
+ }, anthropicHeaders());
+
+ expect(status).toBe(200);
+ const msgs = captured.body.messages;
+ const assistant = msgs.find((m: any) => m.role === 'assistant');
+ expect(assistant.tool_calls[0]).toMatchObject({ id: 'toolu_abc', function: { name: 'get_weather', arguments: '{"city":"Karachi"}' } });
+ const toolMsg = msgs.find((m: any) => m.role === 'tool');
+ expect(toolMsg).toMatchObject({ role: 'tool', tool_call_id: 'toolu_abc', content: 'Sunny, 35C' });
+ expect(body.content[0]).toEqual({ type: 'text', text: 'It is sunny and 35C in Karachi.' });
+ });
+
+ it('accepts an Anthropic image block and forwards it as an image_url block', async () => {
+ const captured = mockJson(textCompletion('a cat'));
+ const { status } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', max_tokens: 64,
+ messages: [{
+ role: 'user',
+ content: [
+ { type: 'text', text: 'what is this?' },
+ { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'iVBORw0KGgo=' } },
+ ],
+ }],
+ }, anthropicHeaders());
+
+ // Schema accepts the image block (not a 400). If routing reached the mock,
+ // the image was translated to an OpenAI image_url block.
+ expect(status).not.toBe(400);
+ if (captured.body) {
+ const userMsg = captured.body.messages.find((m: any) => Array.isArray(m.content));
+ const img = userMsg.content.find((b: any) => b.type === 'image_url');
+ expect(img.image_url.url).toBe('data:image/png;base64,iVBORw0KGgo=');
+ }
+ });
+
+ it('streams the Anthropic SSE event sequence for a text response', async () => {
+ const chunk = (delta: any, finish: string | null = null) => ({ id: 'c1', object: 'chat.completion.chunk', created: 1, model: 'm', choices: [{ index: 0, delta, finish_reason: finish }] });
+ mockStream(sse(
+ chunk({ role: 'assistant' }),
+ chunk({ content: 'Hello' }),
+ chunk({ content: ' world' }),
+ chunk({}, 'stop'),
+ '[DONE]',
+ ));
+
+ const { status, headers, text } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', max_tokens: 64, stream: true,
+ messages: [{ role: 'user', content: 'hi' }],
+ }, anthropicHeaders());
+
+ expect(status).toBe(200);
+ expect(headers.get('content-type')).toMatch(/text\/event-stream/);
+ const events = sseEvents(text);
+ const order = events.map(e => e.event);
+ expect(order[0]).toBe('message_start');
+ expect(order).toContain('content_block_start');
+ expect(order).toContain('content_block_delta');
+ expect(order).toContain('content_block_stop');
+ expect(order[order.length - 2]).toBe('message_delta');
+ expect(order[order.length - 1]).toBe('message_stop');
+
+ const deltas = events.filter(e => e.event === 'content_block_delta').map(e => e.data.delta.text).join('');
+ expect(deltas).toBe('Hello world');
+ const msgDelta = events.find(e => e.event === 'message_delta');
+ expect(msgDelta!.data.delta.stop_reason).toBe('end_turn');
+ });
+
+ it('streams a buffered tool_use block (stop_reason tool_use)', async () => {
+ const chunk = (delta: any, finish: string | null = null) => ({ id: 'c1', object: 'chat.completion.chunk', created: 1, model: 'm', choices: [{ index: 0, delta, finish_reason: finish }] });
+ mockStream(sse(
+ chunk({ role: 'assistant' }),
+ chunk({ tool_calls: [{ index: 0, id: 'call_s', type: 'function', function: { name: 'get_weather', arguments: '' } }] }),
+ chunk({ tool_calls: [{ index: 0, function: { arguments: '{"city":' } }] }),
+ chunk({ tool_calls: [{ index: 0, function: { arguments: '"Karachi"}' } }] }),
+ chunk({}, 'tool_calls'),
+ '[DONE]',
+ ));
+
+ const { status, text } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', max_tokens: 64, stream: true,
+ messages: [{ role: 'user', content: 'weather?' }],
+ tools: [WEATHER_TOOL],
+ }, anthropicHeaders());
+
+ expect(status).toBe(200);
+ const events = sseEvents(text);
+ const startBlock = events.find(e => e.event === 'content_block_start' && e.data.content_block.type === 'tool_use');
+ expect(startBlock!.data.content_block).toMatchObject({ type: 'tool_use', id: 'call_s', name: 'get_weather' });
+ const jsonDelta = events.filter(e => e.event === 'content_block_delta' && e.data.delta.type === 'input_json_delta').map(e => e.data.delta.partial_json).join('');
+ expect(JSON.parse(jsonDelta)).toEqual({ city: 'Karachi' });
+ const msgDelta = events.find(e => e.event === 'message_delta');
+ expect(msgDelta!.data.delta.stop_reason).toBe('tool_use');
+ });
+
+ it('estimates tokens via /v1/messages/count_tokens', async () => {
+ const { status, body } = await request(app, '/v1/messages/count_tokens', {
+ model: 'claude-sonnet-4-5',
+ messages: [{ role: 'user', content: 'count these tokens please' }],
+ }, anthropicHeaders());
+ expect(status).toBe(200);
+ expect(body.input_tokens).toBeGreaterThan(0);
+ });
+
+ it('returns an Anthropic invalid_request_error on a malformed body', async () => {
+ const { status, body } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5', messages: [],
+ }, anthropicHeaders());
+ expect(status).toBe(400);
+ expect(body.type).toBe('error');
+ expect(body.error.type).toBe('invalid_request_error');
+ });
+
+ it('GET /v1/models returns the Anthropic shape for Anthropic clients', async () => {
+ const { status, body } = await send(app, 'GET', '/v1/models', undefined, anthropicHeaders());
+ expect(status).toBe(200);
+ expect(Array.isArray(body.data)).toBe(true);
+ expect(body.has_more).toBe(false);
+ expect(body.data[0]).toMatchObject({ type: 'model', id: 'auto' });
+ // Every entry is the Anthropic model object shape (no OpenAI `object` field).
+ for (const m of body.data) {
+ expect(m.type).toBe('model');
+ expect(typeof m.display_name).toBe('string');
+ expect(typeof m.created_at).toBe('string');
+ }
+ });
+
+ it('GET /v1/models falls through to the OpenAI shape without anthropic-version', async () => {
+ const { status, body } = await send(app, 'GET', '/v1/models', undefined, { Authorization: `Bearer ${getUnifiedApiKey()}` });
+ expect(status).toBe(200);
+ expect(body.object).toBe('list'); // OpenAI envelope, served by proxyRouter
+ expect(body.data[0].id).toBe('auto');
+ expect(body.data[0].object).toBe('model');
+ });
+
+ it('maps a Claude family to a pinned catalog model via the settings API', async () => {
+ // Pick a real enabled groq model to pin "sonnet" to.
+ const groqModel = (getDb().prepare("SELECT model_id FROM models WHERE platform = 'groq' AND enabled = 1 ORDER BY intelligence_rank LIMIT 1").get() as { model_id: string }).model_id;
+
+ const put = await send(app, 'PUT', '/api/settings/anthropic-map', { sonnet: groqModel }, { Authorization: `Bearer ${dashToken}` });
+ expect(put.status).toBe(200);
+ expect(put.body.map.sonnet).toBe(groqModel);
+ expect(put.body.map.opus).toBe('auto'); // untouched families stay auto
+
+ // A claude-sonnet-* request now pins to that model: the provider receives it.
+ const captured = mockJson(textCompletion('pinned answer'));
+ const { status, headers } = await request(app, '/v1/messages', {
+ model: 'claude-sonnet-4-5-20250929', max_tokens: 32,
+ messages: [{ role: 'user', content: 'hi' }],
+ }, anthropicHeaders());
+ expect(status).toBe(200);
+ expect(captured.body.model).toBe(groqModel);
+ expect(headers.get('x-routed-via')).toBe(`groq/${groqModel}`);
+ });
+
+ it('GET /api/settings/anthropic-map returns defaults (all auto) when unset', async () => {
+ const { status, body } = await send(app, 'GET', '/api/settings/anthropic-map', undefined, { Authorization: `Bearer ${dashToken}` });
+ expect(status).toBe(200);
+ expect(body.map).toEqual({ default: 'auto', opus: 'auto', sonnet: 'auto', haiku: 'auto' });
+ });
+});
diff --git a/server/src/app.ts b/server/src/app.ts
index 2cf175e1..241b6c47 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -7,6 +7,7 @@ import { keysRouter } from './routes/keys.js';
import { modelsRouter } from './routes/models.js';
import { proxyRouter } from './routes/proxy.js';
import { responsesRouter } from './routes/responses.js';
+import { anthropicRouter } from './routes/anthropic.js';
import { fallbackRouter } from './routes/fallback.js';
import { profilesRouter } from './routes/profiles.js';
import { embeddingsRouter } from './routes/embeddings.js';
@@ -79,6 +80,12 @@ export function createApp() {
// it throttles unauthenticated brute-force / flood attempts before any
// routing work. Tune via PROXY_RATE_LIMIT_RPM; 0 disables it.
app.use('/v1', createProxyRateLimiter());
+ // Anthropic-compatible Messages API (`POST /v1/messages`, `/count_tokens`) for
+ // Claude Code and anything else speaking the Anthropic SDK. Mounted BEFORE the
+ // OpenAI router so it can content-negotiate `GET /v1/models` (Anthropic shape
+ // when the caller sends `anthropic-version`, else it falls through). All other
+ // paths it doesn't own fall through to the OpenAI router untouched.
+ app.use('/v1', anthropicRouter);
app.use('/v1', proxyRouter);
// OpenAI Responses API shim (Codex CLI requires wire_api="responses"; see #96)
app.use('/v1', responsesRouter);
diff --git a/server/src/routes/anthropic.ts b/server/src/routes/anthropic.ts
new file mode 100644
index 00000000..b7a31566
--- /dev/null
+++ b/server/src/routes/anthropic.ts
@@ -0,0 +1,661 @@
+import crypto from 'crypto';
+import { Router } from 'express';
+import type { Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+import type {
+ ChatMessage,
+ ChatToolCall,
+ ChatToolDefinition,
+ ChatToolChoice,
+ ChatContent,
+ ChatContentBlock,
+} from '@freellmapi/shared/types.js';
+import { routeRequest, recordRateLimitHit, recordSuccess, type RouteResult } from '../services/router.js';
+import {
+ recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit,
+ PAYMENT_REQUIRED_COOLDOWN_MS, MODEL_FORBIDDEN_COOLDOWN_MS, learnLimitFromError,
+} from '../services/ratelimit.js';
+import { getUnifiedApiKey } from '../db/index.js';
+import { contentToString } from '../lib/content.js';
+import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';
+import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';
+import { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError } from '../lib/error-classify.js';
+import { logRequest } from '../lib/request-log.js';
+import { extractApiToken, timingSafeStringEqual, getStickyModel, setStickyModel } from './proxy.js';
+import { resolveAnthropicModel } from '../services/anthropic-map.js';
+import { buildModelListing } from '../services/model-listing.js';
+
+// Anthropic-compatible Messages API (`POST /v1/messages`). This is a thin
+// translation layer over the SAME router/fallback/analytics machinery the
+// OpenAI `/v1/chat/completions` route uses — it converts the Anthropic wire
+// format to our internal (OpenAI-shaped) ChatMessage form on the way in, runs
+// the normal routing loop, and converts the result back to Anthropic shape on
+// the way out. The OpenAI route is left untouched.
+//
+// The point is Claude Code (and anything else that speaks the Anthropic SDK):
+// point `ANTHROPIC_BASE_URL` at this server, set the API key to the unified
+// key, and every `claude-*` request transparently routes to whatever free
+// model the chain picks. Auth accepts Anthropic's native `x-api-key` header
+// (already handled by extractApiToken) as well as a bearer token.
+export const anthropicRouter = Router();
+
+const MAX_RETRIES = 20;
+// Anthropic requires `max_tokens`; mirror the OpenAI route's routing-budget
+// default when a client somehow omits it.
+const DEFAULT_MAX_TOKENS = 1024;
+const IMAGE_TOKEN_ESTIMATE = 1000;
+
+// ── Request schema ──────────────────────────────────────────────────────────
+// Permissive on purpose: the Anthropic content-block vocabulary grows over
+// time (thinking, document, server-tool blocks…) and Claude Code sends blocks
+// with extra fields like `cache_control`. We validate the envelope and handle
+// the block types we understand by `type`, ignoring the rest — same tolerance
+// philosophy as the OpenAI route (#200).
+const contentBlockSchema = z.object({ type: z.string() }).passthrough();
+
+const anthropicMessageSchema = z.object({
+ role: z.enum(['user', 'assistant']),
+ content: z.union([z.string(), z.array(contentBlockSchema)]),
+}).passthrough();
+
+const anthropicToolSchema = z.object({
+ name: z.string().min(1),
+ description: z.string().optional(),
+ input_schema: z.record(z.string(), z.unknown()).optional(),
+}).passthrough();
+
+const anthropicToolChoiceSchema = z.object({
+ type: z.enum(['auto', 'any', 'tool', 'none']),
+ name: z.string().optional(),
+}).passthrough();
+
+const messagesSchema = z.object({
+ model: z.string().optional(),
+ // Anthropic mandates max_tokens; accept omission and clamp non-positive
+ // values to the default rather than 400-ing (some clients send 0).
+ max_tokens: z.number().int().optional(),
+ messages: z.array(anthropicMessageSchema).min(1),
+ system: z.union([z.string(), z.array(contentBlockSchema)]).optional(),
+ temperature: z.number().min(0).max(2).optional(),
+ top_p: z.number().min(0).max(1).optional(),
+ stream: z.boolean().optional(),
+ stop_sequences: z.array(z.string()).optional(),
+ tools: z.array(anthropicToolSchema).optional(),
+ tool_choice: anthropicToolChoiceSchema.optional(),
+}).passthrough();
+
+type AnthropicRequest = z.infer<typeof messagesSchema>;
+
+// ── Response shape ──────────────────────────────────────────────────────────
+type AnthropicStopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | null;
+
+interface AnthropicTextBlock { type: 'text'; text: string }
+interface AnthropicToolUseBlock { type: 'tool_use'; id: string; name: string; input: unknown }
+type AnthropicResponseBlock = AnthropicTextBlock | AnthropicToolUseBlock;
+
+interface AnthropicMessageResponse {
+ id: string;
+ type: 'message';
+ role: 'assistant';
+ model: string;
+ content: AnthropicResponseBlock[];
+ stop_reason: AnthropicStopReason;
+ stop_sequence: string | null;
+ usage: { input_tokens: number; output_tokens: number };
+}
+
+// Carries an HTTP status + Anthropic error type through the routing loop.
+class AnthropicError extends Error {
+ constructor(readonly status: number, readonly errorType: string, message: string) {
+ super(message);
+ }
+}
+
+function sendError(res: Response, status: number, errorType: string, message: string): void {
+ res.status(status).json({ type: 'error', error: { type: errorType, message } });
+}
+
+function newMessageId(): string {
+ return `msg_${crypto.randomBytes(12).toString('hex')}`;
+}
+
+// ── Auth (shared with the OpenAI route) ─────────────────────────────────────
+function authenticate(req: Request, res: Response): boolean {
+ const token = extractApiToken(req);
+ const unifiedKey = getUnifiedApiKey();
+ if (!token || !timingSafeStringEqual(token, unifiedKey)) {
+ sendError(res, 401, 'authentication_error', 'Invalid API key');
+ return false;
+ }
+ return true;
+}
+
+// ── Request translation: Anthropic → internal (OpenAI-shaped) ───────────────
+function flattenSystem(system: AnthropicRequest['system']): string {
+ if (!system) return '';
+ if (typeof system === 'string') return system;
+ return system
+ .map(block => (typeof (block as any).text === 'string' ? (block as any).text : ''))
+ .filter(Boolean)
+ .join('\n');
+}
+
+// An Anthropic tool_result's content is a string or an array of blocks; flatten
+// to text for the internal `tool` message (we don't forward tool images).
+function flattenToolResult(content: unknown): string {
+ if (content == null) return '';
+ if (typeof content === 'string') return content;
+ if (!Array.isArray(content)) return JSON.stringify(content);
+ return content
+ .map(block => {
+ if (typeof block === 'string') return block;
+ if (block && typeof block === 'object' && typeof (block as any).text === 'string') return (block as any).text;
+ return '';
+ })
+ .filter(Boolean)
+ .join('\n');
+}
+
+// Anthropic image block → OpenAI `image_url` block, so vision models keep
+// working through the same routing path the OpenAI route uses.
+function imageBlockToUrl(block: any): string | null {
+ const src = block?.source;
+ if (!src || typeof src !== 'object') return null;
+ if (src.type === 'base64' && src.media_type && src.data) {
+ return `data:${src.media_type};base64,${src.data}`;
+ }
+ if (src.type === 'url' && typeof src.url === 'string') return src.url;
+ return null;
+}
+
+function convertToolChoice(choice: AnthropicRequest['tool_choice']): ChatToolChoice | undefined {
+ if (!choice) return undefined;
+ switch (choice.type) {
+ case 'auto': return 'auto';
+ case 'none': return 'none';
+ case 'any': return 'required'; // Anthropic "any" == OpenAI "required"
+ case 'tool': return choice.name ? { type: 'function', function: { name: choice.name } } : 'required';
+ default: return undefined;
+ }
+}
+
+interface ConvertedRequest {
+ messages: ChatMessage[];
+ tools?: ChatToolDefinition[];
+ tool_choice?: ChatToolChoice;
+ hasImage: boolean;
+ wantsTools: boolean;
+}
+
+function convertRequest(input: AnthropicRequest): ConvertedRequest {
+ const messages: ChatMessage[] = [];
+ let hasImage = false;
+
+ const system = flattenSystem(input.system);
+ if (system) messages.push({ role: 'system', content: system });
+
+ for (const message of input.messages) {
+ if (typeof message.content === 'string') {
+ messages.push({ role: message.role, content: message.content });
+ continue;
+ }
+
+ const textParts: string[] = [];
+ const imageBlocks: ChatContentBlock[] = [];
+ const toolCalls: ChatToolCall[] = [];
+ const toolResults: ChatMessage[] = [];
+
+ for (const block of message.content) {
+ const type = (block as any).type;
+ if (type === 'text') {
+ if (typeof (block as any).text === 'string' && (block as any).text.length > 0) {
+ textParts.push((block as any).text);
+ }
+ } else if (type === 'image') {
+ const url = imageBlockToUrl(block);
+ if (url) { imageBlocks.push({ type: 'image_url', image_url: { url } } as ChatContentBlock); hasImage = true; }
+ } else if (type === 'tool_use') {
+ toolCalls.push({
+ id: String((block as any).id ?? ''),
+ type: 'function',
+ function: { name: String((block as any).name ?? ''), arguments: JSON.stringify((block as any).input ?? {}) },
+ });
+ } else if (type === 'tool_result') {
+ toolResults.push({
+ role: 'tool',
+ tool_call_id: String((block as any).tool_use_id ?? ''),
+ content: flattenToolResult((block as any).content),
+ });
+ }
+ // Unknown block types (thinking, document, …) are intentionally dropped.
+ }
+
+ const text = textParts.join('\n');
+
+ if (message.role === 'assistant') {
+ messages.push({
+ role: 'assistant',
+ content: text.length > 0 ? text : null,
+ ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+ });
+ } else {
+ // User turn. Anthropic carries tool results inside a user message; split
+ // them into the `tool` messages OpenAI expects (which must directly
+ // follow the assistant's tool_calls), then any fresh user text/images.
+ messages.push(...toolResults);
+ if (imageBlocks.length > 0) {
+ const blocks: ChatContentBlock[] = [];
+ if (text.length > 0) blocks.push({ type: 'text', text });
+ blocks.push(...imageBlocks);
+ messages.push({ role: 'user', content: blocks });
+ } else if (text.length > 0) {
+ messages.push({ role: 'user', content: text });
+ }
+ }
+ }
+
+ const tools: ChatToolDefinition[] | undefined = input.tools?.map(t => ({
+ type: 'function',
+ function: { name: t.name, description: t.description, parameters: t.input_schema ?? { type: 'object', properties: {} } },
+ }));
+
+ return {
+ messages,
+ tools,
+ tool_choice: convertToolChoice(input.tool_choice),
+ hasImage,
+ wantsTools: (tools?.length ?? 0) > 0,
+ };
+}
+
+function estimateTokens(messages: ChatMessage[]): number {
+ return messages.reduce((sum, m) => sum + Math.ceil(contentToString(m.content).length / 4), 0);
+}
+
+// Model resolution (Claude family → auto | pinned catalog model) lives in
+// services/anthropic-map.ts so the dashboard mapping editor and this route
+// share one source of truth. Claude Code keeps its built-in `claude-*` names;
+// by default every family maps to "auto" (the router picks a free model).
+
+// A stable created_at for the Anthropic /v1/models entries; clients only use it
+// for display ordering, so a constant avoids needless churn.
+const MODEL_CREATED_AT = '2026-01-01T00:00:00Z';
+
+// ── Response translation: internal → Anthropic ──────────────────────────────
+function mapStopReason(finishReason: string | null | undefined, hadToolCalls: boolean): AnthropicStopReason {
+ if (hadToolCalls || finishReason === 'tool_calls') return 'tool_use';
+ if (finishReason === 'length') return 'max_tokens';
+ if (finishReason === 'stop' || finishReason === 'content_filter' || finishReason == null) return 'end_turn';
+ return 'end_turn';
+}
+
+function parseToolInput(raw: string): unknown {
+ try { return JSON.parse(raw); } catch { return {}; }
+}
+
+function toAnthropicContent(message: ChatMessage | undefined): AnthropicResponseBlock[] {
+ const blocks: AnthropicResponseBlock[] = [];
+ const text = contentToString(message?.content ?? '');
+ if (text.length > 0) blocks.push({ type: 'text', text });
+ for (const call of message?.tool_calls ?? []) {
+ blocks.push({ type: 'tool_use', id: call.id, name: call.function.name, input: parseToolInput(call.function.arguments) });
+ }
+ return blocks;
+}
+
+// ── SSE helpers ─────────────────────────────────────────────────────────────
+function writeSse(res: Response, event: string, data: unknown): void {
+ res.write(`event: ${event}\n`);
+ res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+
+// ── Routing (shared loop, trimmed for the translation layer) ────────────────
+// Returns the routed result + the converted (internal) response for the
+// non-streaming path. Streaming is handled inline so we can translate chunks
+// as they arrive. Mirrors the OpenAI route's cooldown/skip/analytics handling.
+function cooldownFor(route: RouteResult, err: any): number {
+ if (isPaymentRequiredError(err)) return PAYMENT_REQUIRED_COOLDOWN_MS;
+ if (isModelAccessForbiddenError(err)) return MODEL_FORBIDDEN_COOLDOWN_MS;
+ return getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }, err?.retryAfterMs);
+}
+
+anthropicRouter.post('/messages', async (req: Request, res: Response) => {
+ const start = Date.now();
+ if (!authenticate(req, res)) return;
+
+ const parsed = messagesSchema.safeParse(req.body);
+ if (!parsed.success) {
+ const detail = parsed.error.errors
+ .map(e => (e.path.length ? `${e.path.join('.')}: ${e.message}` : e.message))
+ .slice(0, 5).join(', ');
+ console.warn(`[anthropic] 400 invalid /v1/messages request: ${detail}`);
+ sendError(res, 400, 'invalid_request_error', `Invalid request: ${detail}`);
+ return;
+ }
+
+ const body = parsed.data;
+ const requestedModel = body.model ?? 'auto';
+ const max_tokens = body.max_tokens != null && body.max_tokens > 0 ? body.max_tokens : DEFAULT_MAX_TOKENS;
+ const { temperature, top_p, stream } = body;
+
+ const { messages, tools, tool_choice, hasImage, wantsTools } = convertRequest(body);
+ const completionOptions = { temperature, max_tokens, top_p, tools, tool_choice };
+
+ const estimatedInputTokens = estimateTokens(messages);
+ const imageCount = messages.reduce((n, m) =>
+ n + (Array.isArray(m.content) ? m.content.filter(b => (b as any)?.type === 'image_url').length : 0), 0);
+ const estimatedTotal = estimatedInputTokens + imageCount * IMAGE_TOKEN_ESTIMATE + max_tokens;
+
+ // Resolve the model through the operator's Claude-family map (opus/sonnet/
+ // haiku/default → auto | a pinned catalog model). A concrete catalog id pins
+ // directly. `pinned` drives the analytics requested-model label.
+ const resolved = resolveAnthropicModel(body.model);
+ const pinnedModelId = resolved.pinned ? (body.model ?? null) : null;
+
+ // Session affinity: Claude Code stamps every request in a session with
+ // X-Claude-Code-Session-Id. When auto-routing, stick the whole session to one
+ // model so it doesn't flap between free providers mid-conversation.
+ const rawSession = req.headers['x-claude-code-session-id'] ?? req.headers['x-session-id'];
+ const sessionId = Array.isArray(rawSession) ? rawSession[0] : rawSession;
+ let preferredModel = resolved.preferredModelDbId;
+ if (preferredModel == null) preferredModel = getStickyModel(messages, sessionId);
+
+ const skipKeys = new Set<string>();
+ const skipModels = new Set<number>();
+ let lastError: any = null;
+
+ for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+ let route: RouteResult;
+ try {
+ route = routeRequest(estimatedTotal, skipKeys.size > 0 ? skipKeys : undefined, preferredModel, hasImage, wantsTools, skipModels.size > 0 ? skipModels : undefined);
+ } catch (err: any) {
+ if (lastError) {
+ sendError(res, 429, 'rate_limit_error', `All models rate-limited. Last error: ${sanitizeProviderErrorMessage(lastError.message)}`);
+ } else {
+ sendError(res, err?.status ?? 503, 'api_error', err?.message ?? 'No model available to route this request');
+ }
+ return;
+ }
+
+ try {
+ if (stream) {
+ await streamCompletion(res, route, messages, completionOptions, {
+ start, attempt, requestedModel, estimatedInputTokens, tools, pinnedModelId,
+ sessionId, pinned: resolved.pinned,
+ });
+ return;
+ }
+
+ const result = await route.provider.chatCompletion(route.apiKey, messages, route.modelId, completionOptions);
+ const respMsg = result.choices?.[0]?.message;
+ const respText = contentToString(respMsg?.content ?? '');
+ const respToolCalls = respMsg?.tool_calls ?? [];
+
+ // Empty completion → fail over, exactly like the OpenAI route.
+ if (!respText && respToolCalls.length === 0) {
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, 'empty completion (no content, no tool_calls)', null, pinnedModelId);
+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);
+ setCooldown(route.platform, route.modelId, route.keyId, cooldownFor(route, {}));
+ recordRateLimitHit(route.modelDbId);
+ lastError = new Error(`empty completion from ${route.displayName}`);
+ continue;
+ }
+
+ // Repair double-encoded tool arguments against the request schemas, so
+ // strict Anthropic clients (Claude Code) get clean JSON inputs.
+ if (respToolCalls.length) {
+ const schemas = toolSchemaMap(tools);
+ for (const tc of respToolCalls) {
+ if (tc?.function?.arguments != null) {
+ tc.function.arguments = repairToolArguments(tc.function.arguments, schemas.get(tc.function.name));
+ }
+ }
+ }
+
+ const promptTokens = result.usage?.prompt_tokens ?? estimatedInputTokens;
+ const completionTokens = result.usage?.completion_tokens ?? Math.ceil((respText.length + respToolCalls.reduce((n, c) => n + c.function.arguments.length, 0)) / 4);
+
+ recordRequest(route.platform, route.modelId, route.keyId);
+ recordTokens(route.platform, route.modelId, route.keyId, result.usage?.total_tokens ?? promptTokens + completionTokens);
+ recordSuccess(route.modelDbId);
+ // Remember this model for the rest of the auto-routed session (no-op for
+ // a pinned request — the pin already fixes the model).
+ if (!resolved.pinned) setStickyModel(messages, route.modelDbId, sessionId);
+
+ const anthropicResponse: AnthropicMessageResponse = {
+ id: newMessageId(),
+ type: 'message',
+ role: 'assistant',
+ model: requestedModel,
+ content: toAnthropicContent(respMsg),
+ stop_reason: mapStopReason(result.choices?.[0]?.finish_reason ?? null, respToolCalls.length > 0),
+ stop_sequence: null,
+ usage: { input_tokens: promptTokens, output_tokens: completionTokens },
+ };
+
+ res.setHeader('X-Routed-Via', `${route.platform}/${route.modelId}`);
+ if (attempt > 0) res.setHeader('X-Fallback-Attempts', String(attempt));
+ logRequest(route.platform, route.modelId, route.keyId, 'success', promptTokens, completionTokens, Date.now() - start, null, null, pinnedModelId);
+ res.json(anthropicResponse);
+ return;
+ } catch (err: any) {
+ const safeError = sanitizeProviderErrorMessage(err.message);
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, safeError, null, pinnedModelId);
+
+ // A stream that already sent its `message_start` cannot fail over — the
+ // helper finished the SSE response itself. Bubble back without retrying.
+ if (err instanceof StreamAlreadyStarted) return;
+
+ if (isRetryableError(err)) {
+ if (isModelNotFoundError(err) || isModelAccessForbiddenError(err)) skipModels.add(route.modelDbId);
+ skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);
+ setCooldown(route.platform, route.modelId, route.keyId, cooldownFor(route, err));
+ recordRateLimitHit(route.modelDbId);
+ learnLimitFromError(route.modelDbId, err);
+ lastError = err;
+ continue;
+ }
+
+ sendError(res, 502, 'api_error', `Provider error (${route.displayName}): ${safeError}`);
+ return;
+ }
+ }
+
+ sendError(res, 429, 'rate_limit_error', `All models rate-limited after ${MAX_RETRIES} attempts. Last: ${sanitizeProviderErrorMessage(lastError?.message)}`);
+});
+
+// Thrown by streamCompletion once the SSE response is underway, so the outer
+// loop knows the request is finished (honestly errored mid-stream) and must
+// not fail over or send a second response.
+class StreamAlreadyStarted extends Error {}
+
+interface StreamCtx {
+ start: number;
+ attempt: number;
+ requestedModel: string;
+ estimatedInputTokens: number;
+ tools?: ChatToolDefinition[];
+ pinnedModelId: string | null;
+ sessionId?: string;
+ pinned: boolean;
+}
+
+// Consume the provider's OpenAI-style stream and re-emit it as the Anthropic
+// SSE event sequence Claude Code expects:
+// message_start → (content_block_start → content_block_delta* →
+// content_block_stop)* → message_delta → message_stop
+// Text is streamed incrementally as text_delta; tool calls are buffered across
+// deltas and emitted as tool_use blocks (input_json_delta) once complete — the
+// same buffering the OpenAI route does, since partial tool-call JSON isn't
+// safely forwardable mid-flight.
+async function streamCompletion(
+ res: Response,
+ route: RouteResult,
+ messages: ChatMessage[],
+ options: any,
+ ctx: StreamCtx,
+): Promise<void> {
+ let messageStarted = false; // doubles as "headers + message_start sent"
+ let textBlockOpen = false;
+ let textBlockIndex = -1;
+ let nextIndex = 0;
+ let outputChars = 0;
+ let upstreamFinish: string | null = null;
+ const toolAcc = new Map<number, { id?: string; name: string; args: string }>();
+
+ const ensureMessageStart = () => {
+ if (messageStarted) return;
+ res.setHeader('Content-Type', 'text/event-stream');
+ res.setHeader('Cache-Control', 'no-cache');
+ res.setHeader('Connection', 'keep-alive');
+ res.setHeader('X-Routed-Via', `${route.platform}/${route.modelId}`);
+ if (ctx.attempt > 0) res.setHeader('X-Fallback-Attempts', String(ctx.attempt));
+ writeSse(res, 'message_start', {
+ type: 'message_start',
+ message: {
+ id: newMessageId(), type: 'message', role: 'assistant', model: ctx.requestedModel,
+ content: [], stop_reason: null, stop_sequence: null,
+ usage: { input_tokens: ctx.estimatedInputTokens, output_tokens: 0 },
+ },
+ });
+ messageStarted = true;
+ };
+
+ try {
+ const gen = route.provider.streamChatCompletion(route.apiKey, messages, route.modelId, options);
+
+ for await (const chunk of gen) {
+ const anyChunk = chunk as Record<string, any>;
+
+ // In-band provider error frame (e.g. Groq emits {"error":…} inside a 200
+ // stream). Before message_start: retryable → fail over invisibly. After:
+ // surface an Anthropic `error` event and stop.
+ if (anyChunk.error && !anyChunk.choices) {
+ const msg = anyChunk.error.message ?? JSON.stringify(anyChunk.error).slice(0, 200);
+ if (!messageStarted) throw new Error(`in-band provider error from ${route.displayName}: ${msg}`);
+ writeSse(res, 'error', { type: 'error', error: { type: 'api_error', message: `Provider error (${route.displayName}): ${sanitizeProviderErrorMessage(String(msg))}` } });
+ res.end();
+ logRequest(route.platform, route.modelId, route.keyId, 'error', ctx.estimatedInputTokens, outputChars, Date.now() - ctx.start, `in-band error frame: ${sanitizeProviderErrorMessage(String(msg))}`, null, ctx.pinnedModelId);
+ throw new StreamAlreadyStarted();
+ }
+
+ const choice = anyChunk.choices?.[0];
+ if (!choice) continue;
+ if (choice.finish_reason) upstreamFinish = choice.finish_reason;
+
+ for (const tc of choice.delta?.tool_calls ?? []) {
+ const idx = (tc as any).index ?? 0;
+ if (!toolAcc.has(idx)) toolAcc.set(idx, { id: undefined, name: '', args: '' });
+ const acc = toolAcc.get(idx)!;
+ if (tc.id && !acc.id) acc.id = tc.id;
+ if (tc.function?.name) acc.name += tc.function.name;
+ if (tc.function?.arguments) acc.args += tc.function.arguments;
+ }
+
+ const text = typeof choice.delta?.content === 'string' ? choice.delta.content : '';
+ if (text.length === 0) continue;
+
+ ensureMessageStart();
+ if (!textBlockOpen) {
+ textBlockIndex = nextIndex++;
+ writeSse(res, 'content_block_start', { type: 'content_block_start', index: textBlockIndex, content_block: { type: 'text', text: '' } });
+ textBlockOpen = true;
+ }
+ writeSse(res, 'content_block_delta', { type: 'content_block_delta', index: textBlockIndex, delta: { type: 'text_delta', text } });
+ outputChars += text.length;
+ }
+
+ // Assemble buffered tool calls: synthesize missing ids, repair args against
+ // the request schemas, drop any that still aren't valid JSON.
+ const schemas = toolSchemaMap(ctx.tools);
+ let synthetic = 0;
+ const completedCalls = [...toolAcc.entries()]
+ .sort((a, b) => a[0] - b[0])
+ .map(([, acc]) => ({
+ id: acc.id && acc.id.length > 0 ? acc.id : `toolu_${crypto.randomBytes(8).toString('hex')}_${++synthetic}`,
+ name: acc.name,
+ arguments: repairToolArguments(acc.args || '{}', schemas.get(acc.name)),
+ }))
+ .filter(c => { try { JSON.parse(c.arguments); return c.name.length > 0; } catch { return false; } });
+
+ // Nothing usable came out — fail over (message_start was never sent, so the
+ // client never saw this attempt).
+ if (!messageStarted && completedCalls.length === 0) {
+ throw new Error(`empty completion from ${route.displayName} (stream produced no content and no tool calls)`);
+ }
+
+ ensureMessageStart();
+ if (textBlockOpen) writeSse(res, 'content_block_stop', { type: 'content_block_stop', index: textBlockIndex });
+
+ for (const call of completedCalls) {
+ const idx = nextIndex++;
+ writeSse(res, 'content_block_start', { type: 'content_block_start', index: idx, content_block: { type: 'tool_use', id: call.id, name: call.name, input: {} } });
+ writeSse(res, 'content_block_delta', { type: 'content_block_delta', index: idx, delta: { type: 'input_json_delta', partial_json: call.arguments } });
+ writeSse(res, 'content_block_stop', { type: 'content_block_stop', index: idx });
+ outputChars += call.arguments.length;
+ }
+
+ const stopReason = mapStopReason(upstreamFinish, completedCalls.length > 0);
+ const outputTokens = Math.ceil(outputChars / 4);
+ writeSse(res, 'message_delta', { type: 'message_delta', delta: { stop_reason: stopReason, stop_sequence: null }, usage: { output_tokens: outputTokens } });
+ writeSse(res, 'message_stop', { type: 'message_stop' });
+ res.end();
+
+ recordRequest(route.platform, route.modelId, route.keyId);
+ recordTokens(route.platform, route.modelId, route.keyId, ctx.estimatedInputTokens + outputTokens);
+ recordSuccess(route.modelDbId);
+ if (!ctx.pinned) setStickyModel(messages, route.modelDbId, ctx.sessionId);
+ logRequest(route.platform, route.modelId, route.keyId, 'success', ctx.estimatedInputTokens, outputTokens, Date.now() - ctx.start, null, null, ctx.pinnedModelId);
+ } catch (err: any) {
+ if (err instanceof StreamAlreadyStarted) throw err;
+ if (messageStarted) {
+ // Real payload already reached the client — finish the SSE response
+ // honestly instead of leaving Claude Code hanging, and stop the retry loop.
+ writeSse(res, 'error', { type: 'error', error: { type: 'api_error', message: `Provider error (${route.displayName}): stream interrupted` } });
+ try { res.end(); } catch { /* socket gone */ }
+ logRequest(route.platform, route.modelId, route.keyId, 'error', ctx.estimatedInputTokens, outputChars, Date.now() - ctx.start, sanitizeProviderErrorMessage(err.message), null, ctx.pinnedModelId);
+ throw new StreamAlreadyStarted();
+ }
+ // Headers never sent — bubble to the outer loop for failover.
+ throw err;
+ }
+}
+
+// Anthropic token-counting endpoint. Claude Code calls this to size context
+// windows; we return a heuristic estimate (the proxy doesn't run a tokenizer).
+anthropicRouter.post('/messages/count_tokens', (req: Request, res: Response) => {
+ if (!authenticate(req, res)) return;
+ const parsed = messagesSchema.safeParse(req.body);
+ if (!parsed.success) {
+ sendError(res, 400, 'invalid_request_error', 'Invalid request');
+ return;
+ }
+ const { messages } = convertRequest(parsed.data);
+ res.json({ input_tokens: estimateTokens(messages) });
+});
+
+// Anthropic-compatible GET /v1/models. Content-negotiated: only answers when
+// the caller speaks Anthropic (sends an `anthropic-version` header, as Claude
+// Code does) — otherwise it calls next() and the OpenAI-shaped handler in
+// proxyRouter serves the same path. Lists the SAME catalog as the OpenAI
+// endpoint (real free models that can serve a request right now, plus "auto") —
+// no fake Claude cloud models.
+//
+// Heads-up: Claude Code's gateway model picker (enabled via
+// CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1) only surfaces ids beginning
+// with `claude`/`anthropic`, so our ids won't populate its picker by design.
+// Routing still works because Claude Code keeps its built-in `claude-*` names,
+// which the model map sends to "auto" (or a pinned model).
+anthropicRouter.get('/models', (req: Request, res: Response, next: NextFunction) => {
+ if (!req.headers['anthropic-version']) return next(); // OpenAI client → proxyRouter
+ if (!authenticate(req, res)) return;
+
+ const { models } = buildModelListing();
+ const data = [
+ { type: 'model' as const, id: 'auto', display_name: 'Auto (router picks the best available model)', created_at: MODEL_CREATED_AT },
+ ...models
+ .filter(m => m.available === 1)
+ .map(m => ({ type: 'model' as const, id: m.id, display_name: m.name, created_at: MODEL_CREATED_AT })),
+ ];
+ res.json({ data, has_more: false, first_id: data[0]?.id ?? null, last_id: data[data.length - 1]?.id ?? null });
+});
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index ea3737e5..6e5a5173 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -17,6 +17,7 @@ import { isFusionModel, runFusion, fusionConfigSchema, FusionError, FUSION_MODEL
import { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError } from '../lib/error-classify.js';
import { logRequest } from '../lib/request-log.js';
import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';
+import { buildModelListing } from '../services/model-listing.js';
export const proxyRouter = Router();
@@ -175,90 +176,18 @@ proxyRouter.get('/models', (req: Request, res: Response) => {
// right now — the previous default behavior. `available` is computed as
// "enabled AND an enabled key can serve it"; dedup prefers an available
// instance of a model id over a disabled/keyless one.
- const availableExpr = `
- (CASE WHEN m.enabled = 1 AND EXISTS (
- SELECT 1 FROM api_keys k
- WHERE k.platform = m.platform
- AND k.enabled = 1
- AND (m.key_id IS NULL OR k.id = m.key_id)
- ) THEN 1 ELSE 0 END)`;
- const db = getDb();
-
- // A normalized listing row, whether we're grouping (unify ON) or not (OFF).
- let allListed: {
- id: string; name: string; ownedBy: string;
- available: number; enabled: number; contextWindow: number | null; intel: number;
- }[];
-
- if (isUnifyEnabled()) {
- // Unify ON: one entry per logical model group. Pull per-row availability +
- // context keyed by db id, then aggregate over each group's members.
- type AvailRow = { id: number; platform: string; intelligence_rank: number; context_window: number | null; enabled: number; available: number };
- const rows = db.prepare(`
- SELECT m.id, m.platform, m.intelligence_rank, m.context_window,
- m.enabled AS enabled, ${availableExpr} AS available
- FROM models m
- `).all() as AvailRow[];
- const byId = new Map(rows.map(r => [r.id, r]));
- allListed = getModelGroups().map(g => {
- const infos = g.members.map(m => byId.get(m.model_db_id)).filter(Boolean) as AvailRow[];
- const ctxs = infos.map(i => i.context_window).filter((c): c is number => c != null);
- return {
- id: g.canonicalId,
- name: g.groupLabel,
- ownedBy: 'freellmapi',
- available: infos.some(i => i.available === 1) ? 1 : 0,
- enabled: infos.some(i => i.enabled === 1) ? 1 : 0,
- contextWindow: ctxs.length ? Math.max(...ctxs) : null,
- intel: infos.length ? Math.min(...infos.map(i => i.intelligence_rank)) : Number.MAX_SAFE_INTEGER,
- };
- });
- } else {
- // Unify OFF: today's behavior — one entry per model_id (dedup picks the
- // available, smartest representative row).
- const models = db.prepare(`
- SELECT platform, model_id, display_name, context_window, enabled, available, intelligence_rank, id
- FROM (
- SELECT m.platform, m.model_id, m.display_name, m.context_window, m.intelligence_rank, m.id,
- m.enabled AS enabled,
- ${availableExpr} AS available,
- ROW_NUMBER() OVER (
- PARTITION BY m.model_id
- ORDER BY ${availableExpr} DESC, m.intelligence_rank ASC, m.id ASC
- ) AS rn
- FROM models m
- )
- WHERE rn = 1
- `).all() as (ModelListRow & { intelligence_rank: number; id: number })[];
- allListed = models.map(m => ({
- id: m.model_id, name: m.display_name, ownedBy: m.platform,
- available: m.available, enabled: m.enabled, contextWindow: m.context_window,
- intel: m.intelligence_rank,
- }));
- }
-
- // Stable order: usable first, then enabled, then smartest, then name.
- allListed.sort((a, b) =>
- (b.available - a.available) || (b.enabled - a.enabled) || (a.intel - b.intel) || a.name.localeCompare(b.name));
+ // Shared catalog listing (one source of truth for the OpenAI and Anthropic
+ // /v1/models endpoints — see services/model-listing.ts). `autoContextWindow`
+ // is the honest ceiling for the virtual "auto" model: the largest context
+ // window among models that can serve a request right now. Advertising null
+ // makes OpenAI-compatible clients (opencode, Continue) fall back to their own
+ // conservative default and truncate long inputs before they reach us (#282).
+ const { models: allListed, autoContextWindow } = buildModelListing();
const q = String(req.query.available ?? req.query.connected ?? '').toLowerCase();
const onlyAvailable = q === '1' || q === 'true' || q === 'yes';
const listed = onlyAvailable ? allListed.filter(m => m.available === 1) : allListed;
- // "auto" routes to whichever model fits, so its honest ceiling is the largest
- // context window among models that can serve a request right now. Advertising
- // null here makes OpenAI-compatible clients (opencode, Continue) fall back to
- // their own conservative default — commonly ~16k — and truncate long inputs
- // before they ever reach us (#282). Computed over currently-available models
- // (not the query-filtered `listed`) so the ceiling is honest even on the
- // default unfiltered list; null only when nothing is connected.
- const availableContextWindows = allListed
- .filter(m => m.available === 1 && m.contextWindow != null)
- .map(m => m.contextWindow as number);
- const autoContextWindow = availableContextWindows.length > 0
- ? Math.max(...availableContextWindows)
- : null;
-
res.json({
object: 'list',
data: [
diff --git a/server/src/routes/settings.ts b/server/src/routes/settings.ts
index a5d7dc6e..b2c3fda8 100644
--- a/server/src/routes/settings.ts
+++ b/server/src/routes/settings.ts
@@ -4,6 +4,7 @@ import { getUnifiedApiKey, regenerateUnifiedKey, getSetting, setSetting } from '
import { applyProxyUrl, applyProxyEnabled, applyProxyBypass, isProxyActive, getProxyUrl, isProxyEnabled, getProxyBypassPlatforms } from '../lib/proxy.js';
import { getSavedFusionConfig, setSavedFusionConfig, savedFusionConfigSchema, getFusionMaxK } from '../services/fusion.js';
import { isUnifyEnabled, setUnifyEnabled, getUnifyOverrides, setUnifyOverrides, unifyOverridesSchema } from '../services/model-groups.js';
+import { getClaudeModelMap, setClaudeModelMap } from '../services/anthropic-map.js';
import { z } from 'zod';
export const settingsRouter = Router();
@@ -52,6 +53,26 @@ settingsRouter.put('/fusion', (req: Request, res: Response) => {
res.json({ config: saved, maxK: getFusionMaxK() });
});
+// Get the Claude Code model map (opus/sonnet/haiku/default → 'auto' | model_id).
+// Drives how the Anthropic /v1/messages route resolves Claude Code's built-in
+// model names against the free pool.
+settingsRouter.get('/anthropic-map', (_req: Request, res: Response) => {
+ res.json({ map: getClaudeModelMap() });
+});
+
+// Update the Claude Code model map. Partial: send just the families you want to
+// change; each value is 'auto' or a catalog model_id.
+settingsRouter.put('/anthropic-map', (req: Request, res: Response) => {
+ try {
+ res.json({ map: setClaudeModelMap(req.body) });
+ } catch (err: any) {
+ const detail = err?.errors
+ ? err.errors.map((e: any) => (e.path?.length ? `${e.path.join('.')}: ${e.message}` : e.message)).slice(0, 5).join(', ')
+ : (err?.message ?? 'invalid');
+ res.status(400).json({ error: { message: `Invalid anthropic model map: ${detail}`, type: 'invalid_request_error' } });
+ }
+});
+
// Get the unified API key
settingsRouter.get('/api-key', (_req: Request, res: Response) => {
res.json({ apiKey: getUnifiedApiKey() });
diff --git a/server/src/services/anthropic-map.ts b/server/src/services/anthropic-map.ts
new file mode 100644
index 00000000..cdd483ed
--- /dev/null
+++ b/server/src/services/anthropic-map.ts
@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { getDb, getSetting, setSetting } from '../db/index.js';
+
+// Claude Code model mapping. Claude Code keeps its built-in model names
+// (e.g. `claude-sonnet-4-5` as the main model, `claude-3-5-haiku` as the
+// small/fast background model) and sends them verbatim to `/v1/messages`.
+// Since this proxy serves a free model pool (not the real Claude cloud
+// models), we map each Claude family to either "auto" (let the router pick —
+// the default and the common case) or a specific catalog model the operator
+// pins. A concrete catalog model id sent directly (e.g. the user set
+// ANTHROPIC_MODEL to one of our models) bypasses the map and pins as-is.
+//
+// Stored as a JSON blob in the `settings` table — no migration needed.
+
+const SETTING_KEY = 'anthropic_model_map';
+
+export const CLAUDE_FAMILIES = ['default', 'opus', 'sonnet', 'haiku'] as const;
+export type ClaudeFamily = (typeof CLAUDE_FAMILIES)[number];
+// Each value is either the sentinel 'auto' or a catalog model_id.
+export type AnthropicModelMap = Record<ClaudeFamily, string>;
+
+const DEFAULT_MAP: AnthropicModelMap = { default: 'auto', opus: 'auto', sonnet: 'auto', haiku: 'auto' };
+
+export const anthropicModelMapSchema = z.object({
+ default: z.string().min(1).optional(),
+ opus: z.string().min(1).optional(),
+ sonnet: z.string().min(1).optional(),
+ haiku: z.string().min(1).optional(),
+}).strict();
+
+export function getClaudeModelMap(): AnthropicModelMap {
+ const raw = getSetting(SETTING_KEY);
+ if (!raw) return { ...DEFAULT_MAP };
+ try {
+ const p = JSON.parse(raw) as Partial<AnthropicModelMap>;
+ return {
+ default: typeof p.default === 'string' && p.default ? p.default : 'auto',
+ opus: typeof p.opus === 'string' && p.opus ? p.opus : 'auto',
+ sonnet: typeof p.sonnet === 'string' && p.sonnet ? p.sonnet : 'auto',
+ haiku: typeof p.haiku === 'string' && p.haiku ? p.haiku : 'auto',
+ };
+ } catch {
+ return { ...DEFAULT_MAP };
+ }
+}
+
+export function setClaudeModelMap(input: unknown): AnthropicModelMap {
+ const patch = anthropicModelMapSchema.parse(input);
+ const current = getClaudeModelMap();
+ const next: AnthropicModelMap = {
+ default: patch.default ?? current.default,
+ opus: patch.opus ?? current.opus,
+ sonnet: patch.sonnet ?? current.sonnet,
+ haiku: patch.haiku ?? current.haiku,
+ };
+ setSetting(SETTING_KEY, JSON.stringify(next));
+ return next;
+}
+
+// Classify a requested model into a Claude family, or null when it's not a
+// Claude alias at all (a concrete catalog id meant to pin directly).
+export function classifyClaudeFamily(model?: string): ClaudeFamily | null {
+ const m = (model ?? '').trim().toLowerCase();
+ if (!m || m === 'auto' || m === 'default' || m === 'freellmapi-auto') return 'default';
+ if (m.includes('opus')) return 'opus';
+ if (m.includes('sonnet')) return 'sonnet';
+ if (m.includes('haiku')) return 'haiku';
+ // Any other claude-ish alias (incl. Claude Code's opusplan) → the catch-all.
+ if (m.startsWith('claude') || m === 'opusplan' || m === 'opusplan-4') return 'default';
+ return null;
+}
+
+export interface ResolvedAnthropicModel {
+ // The catalog model db id to pin, or undefined to auto-route.
+ preferredModelDbId?: number;
+ // True when we resolved to a specific model (for analytics/pinned labels).
+ pinned: boolean;
+}
+
+// Resolve the model a `/v1/messages` request should route to, honoring the
+// operator's family map. Returns undefined preferredModelDbId to mean
+// "auto-route" (the default for every family unless the operator pinned one).
+export function resolveAnthropicModel(model?: string): ResolvedAnthropicModel {
+ const db = getDb();
+ const lookupEnabled = (modelId: string): number | undefined => {
+ const row = db.prepare('SELECT id FROM models WHERE model_id = ? AND enabled = 1').get(modelId) as { id: number } | undefined;
+ return row?.id;
+ };
+
+ const family = classifyClaudeFamily(model);
+ if (family) {
+ const target = getClaudeModelMap()[family];
+ if (!target || target === 'auto') return { pinned: false };
+ const id = lookupEnabled(target);
+ // A pinned-but-now-disabled/removed target degrades gracefully to auto.
+ return id != null ? { preferredModelDbId: id, pinned: true } : { pinned: false };
+ }
+
+ // Not a Claude alias: treat as a concrete catalog model id and pin it if it
+ // exists and is enabled; otherwise auto-route (lenient, like the OpenAI route).
+ const id = lookupEnabled((model ?? '').trim());
+ return id != null ? { preferredModelDbId: id, pinned: true } : { pinned: false };
+}
diff --git a/server/src/services/model-listing.ts b/server/src/services/model-listing.ts
new file mode 100644
index 00000000..5aeeef2d
--- /dev/null
+++ b/server/src/services/model-listing.ts
@@ -0,0 +1,100 @@
+import type { ModelListRow } from '@freellmapi/shared/types.js';
+import { getDb } from '../db/index.js';
+import { isUnifyEnabled, getModelGroups } from './model-groups.js';
+
+// Shared catalog-listing logic behind both the OpenAI `GET /v1/models` and the
+// Anthropic `GET /v1/models` endpoints, so the two wire formats list the exact
+// same models (only the envelope differs). Extracted verbatim from the OpenAI
+// proxy route to keep a single source of truth.
+
+export interface NormalizedModel {
+ id: string;
+ name: string;
+ ownedBy: string;
+ available: number;
+ enabled: number;
+ contextWindow: number | null;
+ intel: number;
+}
+
+export interface ModelListing {
+ // Full catalog, sorted usable-first; callers apply their own `available` filter.
+ models: NormalizedModel[];
+ // Honest ceiling for the virtual "auto" model: the largest context window
+ // among models that can serve a request right now (null when nothing is
+ // connected). Computed over available models regardless of any caller filter.
+ autoContextWindow: number | null;
+}
+
+export function buildModelListing(): ModelListing {
+ const availableExpr = `
+ (CASE WHEN m.enabled = 1 AND EXISTS (
+ SELECT 1 FROM api_keys k
+ WHERE k.platform = m.platform
+ AND k.enabled = 1
+ AND (m.key_id IS NULL OR k.id = m.key_id)
+ ) THEN 1 ELSE 0 END)`;
+ const db = getDb();
+
+ let allListed: NormalizedModel[];
+
+ if (isUnifyEnabled()) {
+ // Unify ON: one entry per logical model group. Pull per-row availability +
+ // context keyed by db id, then aggregate over each group's members.
+ type AvailRow = { id: number; platform: string; intelligence_rank: number; context_window: number | null; enabled: number; available: number };
+ const rows = db.prepare(`
+ SELECT m.id, m.platform, m.intelligence_rank, m.context_window,
+ m.enabled AS enabled, ${availableExpr} AS available
+ FROM models m
+ `).all() as AvailRow[];
+ const byId = new Map(rows.map(r => [r.id, r]));
+ allListed = getModelGroups().map(g => {
+ const infos = g.members.map(m => byId.get(m.model_db_id)).filter(Boolean) as AvailRow[];
+ const ctxs = infos.map(i => i.context_window).filter((c): c is number => c != null);
+ return {
+ id: g.canonicalId,
+ name: g.groupLabel,
+ ownedBy: 'freellmapi',
+ available: infos.some(i => i.available === 1) ? 1 : 0,
+ enabled: infos.some(i => i.enabled === 1) ? 1 : 0,
+ contextWindow: ctxs.length ? Math.max(...ctxs) : null,
+ intel: infos.length ? Math.min(...infos.map(i => i.intelligence_rank)) : Number.MAX_SAFE_INTEGER,
+ };
+ });
+ } else {
+ // Unify OFF: one entry per model_id (dedup picks the available, smartest
+ // representative row).
+ const models = db.prepare(`
+ SELECT platform, model_id, display_name, context_window, enabled, available, intelligence_rank, id
+ FROM (
+ SELECT m.platform, m.model_id, m.display_name, m.context_window, m.intelligence_rank, m.id,
+ m.enabled AS enabled,
+ ${availableExpr} AS available,
+ ROW_NUMBER() OVER (
+ PARTITION BY m.model_id
+ ORDER BY ${availableExpr} DESC, m.intelligence_rank ASC, m.id ASC
+ ) AS rn
+ FROM models m
+ )
+ WHERE rn = 1
+ `).all() as (ModelListRow & { intelligence_rank: number; id: number })[];
+ allListed = models.map(m => ({
+ id: m.model_id, name: m.display_name, ownedBy: m.platform,
+ available: m.available, enabled: m.enabled, contextWindow: m.context_window,
+ intel: m.intelligence_rank,
+ }));
+ }
+
+ // Stable order: usable first, then enabled, then smartest, then name.
+ allListed.sort((a, b) =>
+ (b.available - a.available) || (b.enabled - a.enabled) || (a.intel - b.intel) || a.name.localeCompare(b.name));
+
+ const availableContextWindows = allListed
+ .filter(m => m.available === 1 && m.contextWindow != null)
+ .map(m => m.contextWindow as number);
+ const autoContextWindow = availableContextWindows.length > 0
+ ? Math.max(...availableContextWindows)
+ : null;
+
+ return { models: allListed, autoContextWindow };
+}