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
fix(anthropic,gemini): client-profile keys authenticate /v1/messages and /v1beta (#1682)
tashdroid2af74e413fae
diff --git a/docs/en/api/01-rest-api.md b/docs/en/api/01-rest-api.mdindex 81453927..85dca22e 100644--- a/docs/en/api/01-rest-api.md+++ b/docs/en/api/01-rest-api.md@@ -197,6 +197,9 @@ curl "http://localhost:3001/v1beta/models/gemini-2.5-flash:generateContent" \Gemini model names like `gemini-2.5-flash` resolve through the Gemini family map (Keys → Gemini model mapping) rather than the catalog directly, so they route to Auto or whichever catalog model each family is pinned to. Catalog ids work verbatim too.+A client-profile key (`sk-cp-…`) authenticates the `/v1beta` generate/stream routes as+well, with its enforced prompt injected ahead of `systemInstruction`.+`contents` text, inline data, function calls/responses, system instructions,function declarations, structured JSON output, generation controls, andthinking budgets translate into the same internal chat/fallback pipeline.@@ -361,6 +364,10 @@ curl http://localhost:3001/v1/messages \}'```+A **client-profile key** (`sk-cp-…`, see the dashboard's Profiles page) authenticates+`/v1/messages` too: the profile's server-enforced system prompt is injected ahead of the+caller's `system` turn, exactly as on `/v1/chat/completions`.+Claude model names map to your free pool on the **Keys → Anthropic** tab: each family (`default`, `opus`, `sonnet`, `haiku`) routes to `auto` (the router picks a free model) or a model you pin. `POST /v1/messages/count_tokens` and a content-negotiated `GET /v1/models` (Anthropic shape when `anthropic-version` is sent) are implemented too. Streaming, system prompts, tool use, and image input all translate across the same router as the OpenAI endpoints.**Claude Code** — point it at your server and start it:diff --git a/docs/en/api/CHANGELOG.md b/docs/en/api/CHANGELOG.mdindex 9eebaeba..c80163b1 100644--- a/docs/en/api/CHANGELOG.md+++ b/docs/en/api/CHANGELOG.md@@ -4,6 +4,10 @@Doc revision history for `docs/api/`, seeded from API-relevant commits.+## 2026-10-23++- **fix(api): client-profile keys now authenticate `/v1/messages` and `/v1beta`** — the `sk-cp-*` keys from #411 were accepted only by `/v1/chat/completions` and `/v1/responses`; the Anthropic and Gemini surfaces still compared the unified key alone, so a downstream app speaking the Claude or Gemini wire format got `401` with its own profile key. Both routes now resolve through `resolveAuth`: profile keys carry their server-enforced system prompt (injected first, after compression on `/v1/messages`, ahead of `systemInstruction` on `/v1beta` — same ordering contract), and a disabled profile fails like a bad key. Source: `server/src/routes/anthropic.ts`, `server/src/routes/gemini.ts`.+## 2026-10-20- **docs(api): document `GET /v1/usage`** — the endpoint shipped with #1600 and gained a per-key breakdown in #1614 but was never in `01-rest-api.md`. Added a Usage API section: response shape (`month`, `resetsAt`, `requests`, `tokens`, `byPlatform[]`, `byKey[]` with `requestCap`/`tokenCap`, `null` = unlimited), unified-key-only auth (`403` for client profiles), deleted keys surfacing under platform `removed`, and the ledger-not-clamped-at-cap semantics that match `429 quota_exceeded`. Source: `server/src/routes/proxy.ts` (`GET /v1/usage` handler).diff --git a/docs/zh-cn/api/01-rest-api.md b/docs/zh-cn/api/01-rest-api.mdindex a038edeb..ce9c185b 100644--- a/docs/zh-cn/api/01-rest-api.md+++ b/docs/zh-cn/api/01-rest-api.md@@ -175,6 +175,8 @@ curl "http://localhost:3001/v1beta/models/gemini-2.5-flash:generateContent" \像 `gemini-2.5-flash` 这样的 Gemini 模型名,是通过 Gemini 系列映射(密钥 → Gemini 模型映射)解析的,而不是直接查目录,所以它们会路由到 Auto,或者路由到你为每个系列固定的那个目录模型。直接写目录里的 id 也一样能用。+客户端档案密钥(`sk-cp-…`)同样可以通过 `/v1beta` 的生成/流式路由鉴权,其强制提示词会注入在 `systemInstruction` 之前。+`contents` 里的文本、内联数据、函数调用与响应、系统指令、函数声明、结构化 JSON 输出、生成控制参数和思考额度,都会翻译进同一套内部的聊天与回退流程。Bearer 认证同样可用。Gemini 的 `?key=` 查询参数只在 `/v1beta` 下被接受;建议优先用请求头,因为写在 URL 里的凭据会泄漏到历史记录和日志中。## Ollama 模拟@@ -277,6 +279,8 @@ curl http://localhost:3001/v1/messages \}'```+**客户端档案密钥**(`sk-cp-…`,见仪表盘的档案页)同样可以通过 `/v1/messages` 鉴权:档案的服务端强制系统提示词会注入在调用方 `system` 轮之前,与 `/v1/chat/completions` 上的行为完全一致。+Claude 的模型名在 **密钥 → Anthropic** 标签页里映射到你的免费池:每个系列(`default`、`opus`、`sonnet`、`haiku`)可以路由到 `auto`(由路由器挑一个免费模型),也可以固定到你指定的模型。`POST /v1/messages/count_tokens` 和一个按内容协商的 `GET /v1/models`(发送了 `anthropic-version` 时返回 Anthropic 的结构)也都实现了。流式、系统提示词、工具使用和图像输入,都经由和 OpenAI 端点相同的那套路由翻译。**Claude Code** —— 把它指向你的服务器再启动:diff --git a/docs/zh-cn/api/CHANGELOG.md b/docs/zh-cn/api/CHANGELOG.mdindex 6d28dd5a..91014aef 100644--- a/docs/zh-cn/api/CHANGELOG.md+++ b/docs/zh-cn/api/CHANGELOG.md@@ -4,6 +4,10 @@`docs/api/` 的文档修订历史。最近的在前。+## 2026-10-23++- **fix(api):客户端档案密钥现在可通过 `/v1/messages` 与 `/v1beta` 鉴权** —— #411 的 `sk-cp-*` 密钥此前只被 `/v1/chat/completions` 与 `/v1/responses` 接受;Anthropic 与 Gemini 路由仍只比对统一密钥,导致下游应用拿着自己的档案密钥得到 `401`。两条路由现在都经由 `resolveAuth` 解析:档案密钥携带其服务端强制系统提示词(最先注入——`/v1/messages` 在压缩之后、`/v1beta` 在 `systemInstruction` 之前——排序契约一致),被禁用的档案按坏密钥处理。来源:`server/src/routes/anthropic.ts`、`server/src/routes/gemini.ts`。+## 2026-08-23 —— 文档重组- **36850e8** `docs(api): fold API guide into api domain` — `docs/api.md` → `docs/api/01-rest-api.md`,补 `OVERVIEW.md` + `CHANGELOG.md` 脚手架。(经 #979 合入)diff --git a/server/src/__tests__/routes/client-profiles.test.ts b/server/src/__tests__/routes/client-profiles.test.tsindex 15566b7d..8356b34e 100644--- a/server/src/__tests__/routes/client-profiles.test.ts+++ b/server/src/__tests__/routes/client-profiles.test.ts@@ -237,4 +237,75 @@ describe('client profiles (#411)', () => {expect(sent[1]).toMatchObject({ role: 'system', content: 'caller instructions' });});});++ describe('the Anthropic surface (/v1/messages) honors profile keys', () => {+ const anthropicBody = {+ model: 'auto',+ max_tokens: 64,+ system: 'caller instructions',+ messages: [{ role: 'user', content: 'hi' }],+ };++ it('accepts a profile key on x-api-key and injects the enforced prompt first', async () => {+ const created = await createProfile('anthropic-bot', 'ENFORCED PROMPT');+ const { status } = await request(app, 'POST', '/v1/messages', {+ token: created.key, body: anthropicBody,+ });+ expect(status).toBe(200);+ const sent = seenMessages[0];+ // Same ordering contract as /v1/chat/completions: enforced first, the+ // caller's system turn survives after it.+ expect(sent[0]).toMatchObject({ role: 'system', content: 'ENFORCED PROMPT' });+ expect(sent.some(m => m.role === 'system' && m.content === 'caller instructions')).toBe(true);+ });++ it('the unified key injects nothing on /v1/messages', async () => {+ const { status } = await request(app, 'POST', '/v1/messages', {+ token: unifiedKey, body: anthropicBody,+ });+ expect(status).toBe(200);+ expect(seenMessages[0][0]).toMatchObject({ role: 'system', content: 'caller instructions' });+ });++ it('a disabled profile key gets 401 on /v1/messages too', async () => {+ const created = await createProfile('anthropic-off', 'x');+ await request(app, 'PATCH', `/api/client-profiles/${created.id}`, {+ token: dashToken, body: { enabled: false },+ });+ const { status } = await request(app, 'POST', '/v1/messages', {+ token: created.key, body: anthropicBody,+ });+ expect(status).toBe(401);+ });+ });++ describe('the Gemini surface (/v1beta) honors profile keys', () => {+ const geminiBody = {+ contents: [{ role: 'user', parts: [{ text: 'hi' }] }],+ systemInstruction: { parts: [{ text: 'caller instructions' }] },+ };+ const geminiPath = '/v1beta/models/gemini-2.5-flash:generateContent';++ it('accepts a profile key and injects the enforced prompt first', async () => {+ const created = await createProfile('gemini-bot', 'ENFORCED PROMPT');+ const { status } = await request(app, 'POST', geminiPath, {+ token: created.key, body: geminiBody,+ });+ expect(status).toBe(200);+ const sent = seenMessages[0];+ expect(sent[0]).toMatchObject({ role: 'system', content: 'ENFORCED PROMPT' });+ expect(sent.some(m => m.role === 'system' && m.content === 'caller instructions')).toBe(true);+ });++ it('a disabled profile key gets 401 on /v1beta too', async () => {+ const created = await createProfile('gemini-off', 'x');+ await request(app, 'PATCH', `/api/client-profiles/${created.id}`, {+ token: dashToken, body: { enabled: false },+ });+ const { status } = await request(app, 'POST', geminiPath, {+ token: created.key, body: geminiBody,+ });+ expect(status).toBe(401);+ });+ });});diff --git a/server/src/routes/anthropic.ts b/server/src/routes/anthropic.tsindex 6cfc47e1..a3538d34 100644--- a/server/src/routes/anthropic.ts+++ b/server/src/routes/anthropic.ts@@ -10,7 +10,8 @@ import type {ChatContentBlock,} from '@freellmapi/shared/types.js';import { routeRequest, resolveModelGroupCandidates, resolveRoutingChain, resolveStickyPreference, routingReserveTokens, failureAttributionFor, type RouteResult, type ResolvedChain, type ChainRow } from '../services/router.js';-import { getSetting, getUnifiedApiKey } from '../db/index.js';+import { getSetting } from '../db/index.js';+import { resolveAuth, prependSystemPrompt, type ResolvedAuth } from '../lib/system-prompt.js';import { contentToString, estimateInputTokens } from '../lib/content.js';import { routeOutputBudget } from '../lib/output-cap.js';import { resolveTaskType } from '../lib/task-type.js';@@ -21,7 +22,7 @@ import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';import { convertDocumentBlock, documentRejectionMessage } from '../lib/anthropic-documents.js';import { isClientAbortError, newClientAbortError, newHedgeAbortError, isUpstreamClassificationOutput } from '../lib/error-classify.js';import { logRequest } from '../lib/request-log.js';-import { extractApiToken, timingSafeStringEqual, getStickyModel, setStickyModel } from './proxy.js';+import { extractApiToken, getStickyModel, setStickyModel } from './proxy.js';import { runFallbackLoop, newFallbackState, fallbackRoutingTokens, recordUpstreamSuccess, type ExhaustionBody, setFallbackHeaders, setExhaustionHeaders, type AttemptRecord, type FallbackState, REASONING_HOLD_MAX_MS } from '../lib/fallback-loop.js';import { routedViaValue } from '../lib/header-value.js';import { startStreamKeepalive, streamKeepaliveMs } from '../lib/stream-keepalive.js';@@ -205,14 +206,17 @@ function newMessageId(): string {}// ── 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)) {+// Resolves both credential kinds (#411): the unified key behaves exactly as+// before; a client-profile key (sk-cp-*) authenticates inference only and+// carries its server-enforced system prompt. A disabled/unknown profile fails+// like a bad key so a revoked client learns nothing extra.+function authenticate(req: Request, res: Response): ResolvedAuth | null {+ const auth = resolveAuth(extractApiToken(req));+ if (!auth) {sendError(res, 401, 'authentication_error', 'Invalid API key');- return false;+ return null;}- return true;+ return auth;}// ── Request translation: Anthropic → internal (OpenAI-shaped) ───────────────@@ -461,7 +465,8 @@ anthropicRouter.post('/messages', async (req: Request, res: Response) => {export async function handleMessages(req: Request, res: Response): Promise<void> {const start = Date.now();- if (!authenticate(req, res)) return;+ const auth = authenticate(req, res);+ if (!auth) return;const parsed = messagesSchema.safeParse(req.body);if (!parsed.success) {@@ -520,6 +525,12 @@ export async function handleMessages(req: Request, res: Response): Promise<void>messages = compressionResult.messages;res.setHeader('X-FreeLLM-Compress', formatCompressionHeader(compressionResult));+ // Server-enforced system prompt (#411): injected AFTER compression so it is+ // never compressed away, and FIRST in the list so a caller-supplied system+ // turn follows it and cannot override it. Neutral no-op for the unified key+ // and for profiles without a prompt.+ messages = prependSystemPrompt(messages, auth.systemPrompt);+const estimatedInputTokens = estimateInputTokens(messages, tools);const imageCount = messages.reduce((n, m) =>n + (Array.isArray(m.content) ? m.content.filter(b => (b as any)?.type === 'image_url').length : 0), 0);diff --git a/server/src/routes/gemini.ts b/server/src/routes/gemini.tsindex 4b9414ce..e9b4f568 100644--- a/server/src/routes/gemini.ts+++ b/server/src/routes/gemini.ts@@ -1,9 +1,9 @@import { Router } from 'express';import type { Request, Response } from 'express';import { z } from 'zod';-import { getUnifiedApiKey } from '../db/index.js';import { buildModelListing, type NormalizedModel } from '../services/model-listing.js';-import { extractApiToken, timingSafeStringEqual } from './proxy.js';+import { extractApiToken } from './proxy.js';+import { resolveAuth, prependSystemPrompt, type ResolvedAuth } from '../lib/system-prompt.js';import { runInboundChat, type InboundChatWire } from '../lib/inbound-chat.js';import {effortFromGeminiThinking,@@ -44,7 +44,10 @@ function sendError(res: Response, status: number, message: string, code = 'INVAL});}-function authenticate(req: Request, res: Response): boolean {+// Resolves both credential kinds (#411): unified key as before; a+// client-profile key (sk-cp-*) authenticates inference only and carries its+// server-enforced system prompt (injected by handleGenerate below).+function authenticate(req: Request, res: Response): ResolvedAuth | null {const queryKey = typeof req.query.key === 'string' ? req.query.key.trim() : '';if (queryKey) {// Query credentials are a Gemini compatibility escape hatch and are@@ -52,12 +55,12 @@ function authenticate(req: Request, res: Response): boolean {// shell history, reverse-proxy logs, and referrer telemetry.console.warn('[Gemini] API key supplied in ?key=; prefer x-goog-api-key to avoid URL leakage');}- const token = extractApiToken(req) ?? queryKey;- if (!token || !timingSafeStringEqual(token, getUnifiedApiKey())) {+ const auth = resolveAuth(extractApiToken(req) ?? queryKey);+ if (!auth) {sendError(res, 401, 'Invalid API key', 'UNAUTHENTICATED');- return false;+ return null;}- return true;+ return auth;}function modelShape(model: NormalizedModel | null, autoContextWindow: number | null, id = 'auto') {@@ -185,7 +188,8 @@ function streamWire(altSse: boolean): InboundChatWire {}async function handleGenerate(req: Request, res: Response, stream: boolean): Promise<void> {- if (!authenticate(req, res)) return;+ const auth = authenticate(req, res);+ if (!auth) return;const body = parseGenerateBody(req, res);if (!body) return;const generation = body.generationConfig;@@ -198,7 +202,10 @@ async function handleGenerate(req: Request, res: Response, stream: boolean): Proconst tools = geminiToolsToChatTools(body.tools);await runInboundChat(req, res, {model: resolveGeminiModel(model),- messages: geminiContentsToMessages(body),+ // Server-enforced system prompt (#411): enforced prompt FIRST so the+ // caller's systemInstruction follows it and cannot override it. Neutral+ // no-op for the unified key and for profiles without a prompt.+ messages: prependSystemPrompt(geminiContentsToMessages(body), auth.systemPrompt),stream,// Gemini CLI never sends maxOutputTokens; the shared 1024-token default// would truncate every response, so match Gemini's own model default.