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(catalog): 400 on explicit unknown/disabled model + sync docs (#24)
Tashfeen8257eff79d3e
diff --git a/docs/index.html b/docs/index.htmlindex f90a2b21..54d47b3a 100644--- a/docs/index.html+++ b/docs/index.html@@ -4,7 +4,7 @@<meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>FreeLLMAPI — One key. One billion free LLM tokens. Every month.</title>-<meta name="description" content="A self-hosted, OpenAI-compatible proxy that routes across 12 free-tier LLM providers — Gemini, OpenRouter, Cerebras, Groq, Mistral, GitHub Models, SambaNova, Cohere, Cloudflare, Hugging Face, Z.ai, NVIDIA. ~1B free tokens / month, 60 models." />+<meta name="description" content="A self-hosted, OpenAI-compatible proxy that routes across 11 free-tier LLM providers — Gemini, OpenRouter, Cerebras, Groq, Mistral, GitHub Models, SambaNova, Cohere, Cloudflare, Z.ai, NVIDIA. ~1B free tokens / month, 60 models." /><meta name="theme-color" content="#0a0a0a" /><link rel="canonical" href="https://tashfeenahmed.github.io/freellmapi/" />@@ -12,17 +12,17 @@<meta property="og:type" content="website" /><meta property="og:site_name" content="FreeLLMAPI" /><meta property="og:title" content="FreeLLMAPI — 1B free LLM tokens / month" />-<meta property="og:description" content="One self-hosted, OpenAI-compatible proxy across 12 free-tier LLM providers. 60 models. ~1B free tokens per month." />+<meta property="og:description" content="One self-hosted, OpenAI-compatible proxy across 11 free-tier LLM providers. 60 models. ~1B free tokens per month." /><meta property="og:url" content="https://tashfeenahmed.github.io/freellmapi/" /><meta property="og:image" content="https://tashfeenahmed.github.io/freellmapi/og.png" /><meta property="og:image:width" content="1200" /><meta property="og:image:height" content="630" />-<meta property="og:image:alt" content="FreeLLMAPI — 1B free tokens / month, across 12 providers and 60 models." />+<meta property="og:image:alt" content="FreeLLMAPI — 1B free tokens / month, across 11 providers and 60 models." /><!-- Twitter --><meta name="twitter:card" content="summary_large_image" /><meta name="twitter:title" content="FreeLLMAPI — 1B free LLM tokens / month" />-<meta name="twitter:description" content="One self-hosted, OpenAI-compatible proxy across 12 free-tier LLM providers. 60 models. ~1B free tokens per month." />+<meta name="twitter:description" content="One self-hosted, OpenAI-compatible proxy across 11 free-tier LLM providers. 60 models. ~1B free tokens per month." /><meta name="twitter:image" content="https://tashfeenahmed.github.io/freellmapi/og.png" /><link rel="icon" href="data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='9' fill='%230a0a0a'/%3E%3Ccircle cx='16' cy='16' r='9' fill='%23ffffff'/%3E%3Ccircle cx='16' cy='16' r='3.2' fill='%230a0a0a'/%3E%3C/svg%3E" /><style>@@ -292,7 +292,7 @@</nav><header class="hero">- <span class="badge"><span class="badge-dot"></span> 60 free models · 12 providers · self-hosted</span>+ <span class="badge"><span class="badge-dot"></span> 60 free models · 11 providers · self-hosted</span><h1>One key.<br><span class="gradient">One billion</span> free tokens.<br>Every month.</h1><p class="subtitle">A self-hosted, OpenAI-compatible proxy that routes across every credible free-tier LLM provider. Bring your own keys; we just point requests at whichever provider still has budget left.</p><div class="cta-row">@@ -305,7 +305,7 @@<div class="tokens-label">Aggregate monthly free budget</div><div class="tokens-number">1B</div><div class="tokens-unit">tokens · per month</div>- <div class="tokens-sub">Across 60 free-tier models on 12 providers. Mistral alone contributes ~1B; everything else is bonus.</div>+ <div class="tokens-sub">Across 60 free-tier models on 11 providers. Mistral alone contributes ~1B; everything else is bonus.</div></div><section id="providers">@@ -365,11 +365,6 @@<div class="provider-tokens"><span class="num">~1-2M</span><span class="unit">/mo</span><span class="label">shared</span></div><div class="provider-models">Command R+. Trial key: <b>1000 calls/month</b>, 20 RPM.</div></div>- <div class="provider-card">- <div class="provider-name"><span class="provider-icon"><img src="logos/huggingface.svg" alt="" /></span>Hugging Face</div>- <div class="provider-tokens"><span class="num">~1-3M</span><span class="unit">/mo</span><span class="label">est.</span></div>- <div class="provider-models">Llama 3.3 70B via Fireworks router. Modest credits but enough for sporadic use.</div>- </div><div class="provider-card"><div class="provider-name"><span class="provider-icon"><img src="logos/nvidia.svg" alt="" /></span>NVIDIA NIM</div><div class="provider-tokens"><span class="num">credits</span><span class="unit"></span><span class="label">disabled</span></div>diff --git a/docs/logos/huggingface.svg b/docs/logos/huggingface.svgdeleted file mode 100644index a52cbe3e..00000000--- a/docs/logos/huggingface.svg+++ /dev/null@@ -1 +0,0 @@-<svg fill="#FFD21E" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Hugging Face</title><path d="M12.025 1.13c-5.77 0-10.449 4.647-10.449 10.378 0 1.112.178 2.181.503 3.185.064-.222.203-.444.416-.577a.96.96 0 0 1 .524-.15c.293 0 .584.124.84.284.278.173.48.408.71.694.226.282.458.611.684.951v-.014c.017-.324.106-.622.264-.874s.403-.487.762-.543c.3-.047.596.06.787.203s.31.313.4.467c.15.257.212.468.233.542.01.026.653 1.552 1.657 2.54.616.605 1.01 1.223 1.082 1.912.055.537-.096 1.059-.38 1.572.637.121 1.294.187 1.967.187.657 0 1.298-.063 1.921-.178-.287-.517-.44-1.041-.384-1.581.07-.69.465-1.307 1.081-1.913 1.004-.987 1.647-2.513 1.657-2.539.021-.074.083-.285.233-.542.09-.154.208-.323.4-.467a1.08 1.08 0 0 1 .787-.203c.359.056.604.29.762.543s.247.55.265.874v.015c.225-.34.457-.67.683-.952.23-.286.432-.52.71-.694.257-.16.547-.284.84-.285a.97.97 0 0 1 .524.151c.228.143.373.388.43.625l.006.04a10.3 10.3 0 0 0 .534-3.273c0-5.731-4.678-10.378-10.449-10.378M8.327 6.583a1.5 1.5 0 0 1 .713.174 1.487 1.487 0 0 1 .617 2.013c-.183.343-.762-.214-1.102-.094-.38.134-.532.914-.917.71a1.487 1.487 0 0 1 .69-2.803m7.486 0a1.487 1.487 0 0 1 .689 2.803c-.385.204-.536-.576-.916-.71-.34-.12-.92.437-1.103.094a1.487 1.487 0 0 1 .617-2.013 1.5 1.5 0 0 1 .713-.174m-10.68 1.55a.96.96 0 1 1 0 1.921.96.96 0 0 1 0-1.92m13.838 0a.96.96 0 1 1 0 1.92.96.96 0 0 1 0-1.92M8.489 11.458c.588.01 1.965 1.157 3.572 1.164 1.607-.007 2.984-1.155 3.572-1.164.196-.003.305.12.305.454 0 .886-.424 2.328-1.563 3.202-.22-.756-1.396-1.366-1.63-1.32q-.011.001-.02.006l-.044.026-.01.008-.03.024q-.018.017-.035.036l-.032.04a1 1 0 0 0-.058.09l-.014.025q-.049.088-.11.19a1 1 0 0 1-.083.116 1.2 1.2 0 0 1-.173.18q-.035.029-.075.058a1.3 1.3 0 0 1-.251-.243 1 1 0 0 1-.076-.107c-.124-.193-.177-.363-.337-.444-.034-.016-.104-.008-.2.022q-.094.03-.216.087-.06.028-.125.063l-.13.074q-.067.04-.136.086a3 3 0 0 0-.135.096 3 3 0 0 0-.26.219 2 2 0 0 0-.12.121 2 2 0 0 0-.106.128l-.002.002a2 2 0 0 0-.09.132l-.001.001a1.2 1.2 0 0 0-.105.212q-.013.036-.024.073c-1.139-.875-1.563-2.317-1.563-3.203 0-.334.109-.457.305-.454m.836 10.354c.824-1.19.766-2.082-.365-3.194-1.13-1.112-1.789-2.738-1.789-2.738s-.246-.945-.806-.858-.97 1.499.202 2.362c1.173.864-.233 1.45-.685.64-.45-.812-1.683-2.896-2.322-3.295s-1.089-.175-.938.647 2.822 2.813 2.562 3.244-1.176-.506-1.176-.506-2.866-2.567-3.49-1.898.473 1.23 2.037 2.16c1.564.932 1.686 1.178 1.464 1.53s-3.675-2.511-4-1.297c-.323 1.214 3.524 1.567 3.287 2.405-.238.839-2.71-1.587-3.216-.642-.506.946 3.49 2.056 3.522 2.064 1.29.33 4.568 1.028 5.713-.624m5.349 0c-.824-1.19-.766-2.082.365-3.194 1.13-1.112 1.789-2.738 1.789-2.738s.246-.945.806-.858.97 1.499-.202 2.362c-1.173.864.233 1.45.685.64.451-.812 1.683-2.896 2.322-3.295s1.089-.175.938.647-2.822 2.813-2.562 3.244 1.176-.506 1.176-.506 2.866-2.567 3.49-1.898-.473 1.23-2.037 2.16c-1.564.932-1.686 1.178-1.464 1.53s3.675-2.511 4-1.297c.323 1.214-3.524 1.567-3.287 2.405.238.839 2.71-1.587 3.216-.642.506.946-3.49 2.056-3.522 2.064-1.29.33-4.568 1.028-5.713-.624"/></svg>\ No newline at end of filediff --git a/server/src/__tests__/integration/full-flow.test.ts b/server/src/__tests__/integration/full-flow.test.tsindex 2ede18a6..670d294f 100644--- a/server/src/__tests__/integration/full-flow.test.ts+++ b/server/src/__tests__/integration/full-flow.test.ts@@ -151,4 +151,25 @@ describe('Full Integration Flow', () => {});expect(s2).toBe(400);});++ it('Step 11: Explicit unknown model returns 400 (not silent fallthrough)', async () => {+ const { status, body } = await req(app, 'POST', '/v1/chat/completions', {+ model: 'definitely-not-a-real-model',+ messages: [{ role: 'user', content: 'hi' }],+ });+ expect(status).toBe(400);+ expect(body.error.code).toBe('model_not_found');+ expect(body.error.message).toContain('not in the catalog');+ });++ it('Step 12: Explicit disabled model returns 400 with disabled reason', async () => {+ // gemini-2.5-pro is disabled (V1 migration). Reuse it as a known-disabled fixture.+ const { status, body } = await req(app, 'POST', '/v1/chat/completions', {+ model: 'gemini-2.5-pro',+ messages: [{ role: 'user', content: 'hi' }],+ });+ expect(status).toBe(400);+ expect(body.error.code).toBe('model_not_found');+ expect(body.error.message).toContain('is disabled');+ });});diff --git a/server/src/__tests__/routes/proxy-tools.test.ts b/server/src/__tests__/routes/proxy-tools.test.tsindex 531cdc70..7bfdcc10 100644--- a/server/src/__tests__/routes/proxy-tools.test.ts+++ b/server/src/__tests__/routes/proxy-tools.test.ts@@ -88,7 +88,7 @@ describe('Proxy tool-calling support', () => {});const { status, body } = await request(app, 'POST', '/v1/chat/completions', {- model: 'auto',+ // No `model` → auto-route via fallback chain.messages: [{ role: 'user', content: 'What is the weather in Karachi?' }],tools: [{type: 'function',diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 275d79d9..1845fb76 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -225,15 +225,29 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {}, 0);const estimatedTotal = estimatedInputTokens + (max_tokens ?? 1000);- // Explicit `model` field pins routing; sticky-session is the fallback.+ // Explicit `model` field pins routing. If the catalog has no enabled row+ // matching the requested id, return 400 — silently auto-routing to a+ // different model would be surprising to OpenAI-compatible clients.+ // Sticky-session is the fallback when no `model` field was sent at all.let preferredModel: number | undefined;if (requestedModel) {- const row = getDb()- .prepare('SELECT id FROM models WHERE model_id = ? AND enabled = 1')- .get(requestedModel) as { id: number } | undefined;- if (row) preferredModel = row.id;- }- if (preferredModel === undefined) {+ const db = getDb();+ const enabled = db.prepare('SELECT id FROM models WHERE model_id = ? AND enabled = 1').get(requestedModel) as { id: number } | undefined;+ if (enabled) {+ preferredModel = enabled.id;+ } else {+ const disabled = db.prepare('SELECT id FROM models WHERE model_id = ?').get(requestedModel) as { id: number } | undefined;+ const reason = disabled ? 'is disabled' : 'is not in the catalog';+ res.status(400).json({+ error: {+ message: `Model '${requestedModel}' ${reason}. Omit the 'model' field to auto-route, or call /v1/models for the available list.`,+ type: 'invalid_request_error',+ code: 'model_not_found',+ },+ });+ return;+ }+ } else {preferredModel = getStickyModel(messages);}