feat: add FreeTheAi as OpenAI-compatible gateway provider (#6670) (#7602)

* feat(providers): add FreeTheAi as an OpenAI-compatible gateway provider (#6670) FreeTheAi is a free-tier, Discord-signup gateway aggregator — same shape as hackclub/chutes: OpenAI-compatible chat/completions + /v1/models discovery, no custom executor/translator needed. - Registry entry: open-sse/config/providers/registry/freetheai/index.ts (format: openai, executor: default, apikey/bearer auth, passthroughModels) - Provider metadata: src/shared/constants/providers/apikey/gateways.ts - Listed in AGGREGATOR_PROVIDER_IDS (src/shared/constants/providers.ts) - Unit test verifying registry entry, getExecutor() resolution, aggregator classification, and provider metadata (tests/unit/provider-registry-freetheai.test.ts) * chore(providers): sync counts (APIKEY 170, providers 253) after rebase onto advanced release (#6670) The release advanced heavily since this branch was cut; realign the family-partition count to the true post-rebase value (170) and the doc provider totals to 253. freetheai adds exactly one gateway; the rest of the delta is pre-existing release drift. All partition/dedup checks enforced.
2026-08-06 07:12:12 +03:00 · 2026-07-17 11:36:58 -03:00
parent 6695cbbf7a
commit 7eb0204901
11 changed files with 114 additions and 15 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,12 +3,12 @@
 ## Project

 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-with **251 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+with **253 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
 Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
 SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
 with **MCP Server** (94 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.

-> **Live counts (v3.8.49)**: providers 251 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
+> **Live counts (v3.8.49)**: providers 253 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
 > open-sse services 134 · routing strategies 17 · auto-combo scoring factors 12 ·
 > DB modules 95 · DB migrations 110 · base tables 17 · search providers 11 ·
 > i18n locales 42. **Refresh with `npm run check:docs-all`.**
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,7 +35,7 @@ For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep archit

 ## Project at a Glance

-**OmniRoute** — unified AI proxy/router. One endpoint, 251 LLM providers, auto-fallback.
+**OmniRoute** — unified AI proxy/router. One endpoint, 253 LLM providers, auto-fallback.

 | Layer         | Location                | Purpose                                                                                                                                                |
 | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@

 # 🚀 OmniRoute — The Free AI Gateway

-### Never stop coding. Connect every AI tool to **251 providers** — **90+ free** — through one endpoint.
+### Never stop coding. Connect every AI tool to **253 providers** — **90+ free** — through one endpoint.

 **Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.**
 <br/>
@@ -149,11 +149,11 @@

 </div>

-> One endpoint. **251 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.
+> One endpoint. **253 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.

 <table>
  <tr>
-    <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 251 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
+    <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 253 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
    <td width="33%" valign="top"><b>💸 Save up to 95% tokens</b><br/><sub>RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).</sub></td>
    <td width="33%" valign="top"><b>🆓 $0 to start</b><br/><sub>90+ providers with a free tier, 11 free <i>forever</i> (Kiro, Qoder, Pollinations, LongCat…). No card needed.</sub></td>
  </tr>
@@ -399,7 +399,7 @@ Result: 4 layers of fallback = zero downtime

 </div>

-> The most complete catalog of any open-source router: **251 providers**, **90+ with a free tier**, **11 free forever**.
+> The most complete catalog of any open-source router: **253 providers**, **90+ with a free tier**, **11 free forever**.

 <div align="center">

@@ -907,7 +907,7 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
 **Will I be charged by OmniRoute?** No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system.
 **Are FREE providers really unlimited?** Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0.
 **Will compression hurt quality?** No — it only compresses the **input**; code, URLs, JSON are always protected.
-**Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 251 providers.
+**Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 253 providers.

 📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md)

--- a/changelog.d/features/6670-freetheai-gateway-provider.md
+++ b/changelog.d/features/6670-freetheai-gateway-provider.md
@@ -0,0 +1 @@
+- feat(providers): add FreeTheAi as an OpenAI-compatible gateway provider with a free Discord-signup tier (#6670)
--- a/docs/reference/PROVIDER_REFERENCE.md
+++ b/docs/reference/PROVIDER_REFERENCE.md
@@ -10,7 +10,7 @@ lastUpdated: 2026-07-17
 > Regenerate with: `npm run gen:provider-reference`
 > **Last generated:** 2026-07-17

-Total providers: **251**. See category breakdown below.
+Total providers: **253**. See category breakdown below.

 ## Categories

@@ -89,7 +89,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
 | `zai-web` | `zw` | Z.ai Web (Free) | Web cookie | [link](https://chat.z.ai) | Paste the full Cookie header from chat.z.ai (must include the token=<JWT> cookie) |
 | `zenmux-free` | `zmf` | ZenMux Free (Web) | Web cookie | [link](https://zenmux.ai) | Login at zenmux.ai, then export all cookies using EditThisCookie or Cookie-Editor and paste the full Cookie header string here. Refresh every ~30 days. |

-## API Key Providers (paid / paid-with-free-credits) (168)
+## API Key Providers (paid / paid-with-free-credits) (170)

 | ID | Alias | Name | Tags | Website | Notes |
 |----|-------|------|------|---------|-------|
@@ -118,6 +118,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
 | `bytez` | `bytez` | Bytez | API key | [link](https://bytez.com) | $1 free credits, refreshes every 4 weeks |
 | `cerebras` | `cerebras` | Cerebras | API key | [link](https://inference.cerebras.ai) | Free Trial: 1M tokens/day, 30K TPM, 5 RPM — no credit card. |
 | `charm-hyper` | `charm-hyper` | Charm Hyper | API key | [link](https://hyper.charm.land) | 100 free monthly Hypercredits on signup |
+| `chenzk` | `chenzk` | Chenzk API | API key | [link](https://chenzk.top) | — |
 | `chutes` | `chutes` | Chutes.ai | API key, aggregator | [link](https://chutes.ai) | Bearer API key for the Chutes OpenAI-compatible gateway. |
 | `clarifai` | `clarifai` | Clarifai | API key, enterprise | [link](https://docs.clarifai.com) | Use your Clarifai PAT or app-specific API key. OmniRoute targets the OpenAI-compatible endpoint at https://api.clarifai.com/v2/ext/openai/v1 and authenticates with Authorization: Key <token>. |
 | `cloudflare-ai` | `cf` | Cloudflare Workers AI | API key | [link](https://developers.cloudflare.com/workers-ai) | Requires API Token AND Account ID (found at dash.cloudflare.com) |
@@ -144,6 +145,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
 | `fireworks` | `fireworks` | Fireworks AI | API key | [link](https://fireworks.ai) | $1 free starter credits on signup for API testing |
 | `freeaiapikey` | `faik` | FreeAIAPIKey | API key | [link](https://freeaiapikey.com) | — |
 | `freemodel-dev` | `fmd` | FreeModel.dev | API key | [link](https://freemodel.dev) | $300 free credits on signup — no credit card required. Access GPT-5.4 and GPT-5.5 (OpenAI's latest flagship models) through an OpenAI-compatible API. |
+| `freetheai` | `fta` | FreeTheAi | API key, aggregator | [link](https://freetheai.xyz) | Join the FreeTheAi Discord to get your free API key. |
 | `friendliai` | `friendli` | FriendliAI | API key | [link](https://friendli.ai) | Free tier for serverless inference — no credit card required |
 | `galadriel` | `galadriel` | Galadriel | API key | [link](https://galadriel.com) | ⚠️ **DEPRECATED.** api.galadriel.ai no longer resolves (sweep 2026-06-19); the inference API appears discontinued. |
 | `gemini` | `gemini` | Gemini (Google AI Studio) | API key | [link](https://aistudio.google.com) | Free forever: 1,500 req/day for Gemini 2.5 Flash — no credit card, get key at aistudio.google.com |
--- a/open-sse/config/providers/index.ts
+++ b/open-sse/config/providers/index.ts
@@ -65,6 +65,7 @@ import { cohereProvider } from "./registry/cohere/index.ts";
 import { cursorProvider } from "./registry/cursor/index.ts";
 import { volcengineProvider } from "./registry/volcengine/index.ts";
 import { hackclubProvider } from "./registry/hackclub/index.ts";
+import { freetheaiProvider } from "./registry/freetheai/index.ts";
 import { tencentProvider } from "./registry/tencent/index.ts";
 import { cozeProvider } from "./registry/coze/index.ts";
 import { ai21Provider } from "./registry/ai21/index.ts";
@@ -254,6 +255,7 @@ export const REGISTRY: Record<string, RegistryEntry> = {
  cursor: cursorProvider,
  volcengine: volcengineProvider,
  hackclub: hackclubProvider,
+  freetheai: freetheaiProvider,
  tencent: tencentProvider,
  coze: cozeProvider,
  ai21: ai21Provider,
--- a/open-sse/config/providers/registry/freetheai/index.ts
+++ b/open-sse/config/providers/registry/freetheai/index.ts
@@ -0,0 +1,23 @@
+import type { RegistryEntry } from "../../shared.ts";
+
+// FreeTheAi — OpenAI-compatible gateway with a Discord-signup free tier
+// (issue #6670). Same shape as the hackclub/chutes aggregator entries:
+// standard OpenAI chat/completions + /v1/models discovery, so no custom
+// executor/translator is needed.
+export const freetheaiProvider: RegistryEntry = {
+  id: "freetheai",
+  alias: "fta",
+  format: "openai",
+  executor: "default",
+  baseUrl: "https://api.freetheai.xyz/v1/chat/completions",
+  modelsUrl: "https://api.freetheai.xyz/v1/models",
+  authType: "apikey",
+  authHeader: "bearer",
+  passthroughModels: true,
+  defaultContextLength: 128000,
+  models: [
+    { id: "gpt-4o-mini", name: "GPT-4o Mini" },
+    { id: "llama-3.3-70b-instruct", name: "Llama 3.3 70B" },
+    { id: "deepseek-chat", name: "DeepSeek Chat" },
+  ],
+};
--- a/src/shared/constants/providers.ts
+++ b/src/shared/constants/providers.ts
@@ -77,6 +77,7 @@ export const AGGREGATOR_PROVIDER_IDS = new Set([
  "poe",
  "chutes",
  "hackclub",
+  "freetheai",
 ]);

 export const ENTERPRISE_CLOUD_PROVIDER_IDS = new Set([
--- a/src/shared/constants/providers/apikey/gateways.ts
+++ b/src/shared/constants/providers/apikey/gateways.ts
@@ -238,6 +238,19 @@ export const APIKEY_PROVIDERS_GATEWAYS = {
    passthroughModels: true,
    authHint: "Sign in with your Hack Club account at ai.hackclub.com.",
  },
+  freetheai: {
+    id: "freetheai",
+    alias: "fta",
+    name: "FreeTheAi",
+    icon: "hub",
+    color: "#22C55E",
+    textIcon: "FTA",
+    website: "https://freetheai.xyz",
+    hasFree: true,
+    freeNote: "Free OpenAI-compatible gateway — sign up via Discord for an API key.",
+    passthroughModels: true,
+    authHint: "Join the FreeTheAi Discord to get your free API key.",
+  },
  "vercel-ai-gateway": {
    id: "vercel-ai-gateway",
    alias: "vag",
--- a/tests/unit/provider-registry-freetheai.test.ts
+++ b/tests/unit/provider-registry-freetheai.test.ts
@@ -0,0 +1,57 @@
+/**
+ * Issue #6670 — Add FreeTheAi as an OpenAI-compatible gateway provider
+ * (free tier via Discord signup).
+ *
+ * Verifies the new provider is wired end-to-end the same way as the other
+ * aggregator/gateway providers (hackclub, chutes, glhf, ...):
+ *   - present in the executor REGISTRY with an OpenAI-compatible shape
+ *   - resolvable through getExecutor() (falls through to DefaultExecutor,
+ *     same as every other `executor: "default"` registry entry)
+ *   - listed in AGGREGATOR_PROVIDER_IDS so it shows up in the aggregator
+ *     category on the dashboard
+ *   - has provider metadata (name/website/free-tier note) in the apikey
+ *     gateway catalog
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { REGISTRY } = await import("../../open-sse/config/providerRegistry.ts");
+const { getExecutor, DefaultExecutor } = await import("../../open-sse/executors/index.ts");
+const { AGGREGATOR_PROVIDER_IDS } = await import("../../src/shared/constants/providers.ts");
+const { APIKEY_PROVIDERS } = await import("../../src/shared/constants/providers/apikey/index.ts");
+
+test("#6670 freetheai is registered in the executor registry with an OpenAI-compatible shape", () => {
+  const entry = (REGISTRY as Record<string, Record<string, unknown>>).freetheai;
+  assert.ok(entry, "freetheai should be present in the executor registry");
+  assert.equal(entry.format, "openai");
+  assert.equal(entry.executor, "default");
+  assert.equal(entry.baseUrl, "https://api.freetheai.xyz/v1/chat/completions");
+  assert.equal(entry.modelsUrl, "https://api.freetheai.xyz/v1/models");
+  assert.equal(entry.authType, "apikey");
+  assert.equal(entry.authHeader, "bearer");
+  assert.equal(entry.passthroughModels, true);
+  assert.ok(Array.isArray(entry.models) && entry.models.length > 0, "must seed a fallback model list");
+});
+
+test("#6670 freetheai resolves through getExecutor() as a DefaultExecutor instance", () => {
+  const executor = getExecutor("freetheai");
+  assert.ok(executor instanceof DefaultExecutor, "freetheai has no custom executor — must fall through to DefaultExecutor");
+});
+
+test("#6670 freetheai is classified as an aggregator/gateway provider", () => {
+  assert.ok(
+    AGGREGATOR_PROVIDER_IDS.has("freetheai"),
+    "freetheai must be listed in AGGREGATOR_PROVIDER_IDS alongside hackclub/chutes/etc"
+  );
+});
+
+test("#6670 freetheai has provider metadata with free-tier info", () => {
+  const meta = (APIKEY_PROVIDERS as Record<string, Record<string, unknown>>).freetheai;
+  assert.ok(meta, "freetheai should have an APIKEY_PROVIDERS metadata entry");
+  assert.equal(meta.id, "freetheai");
+  assert.equal(meta.name, "FreeTheAi");
+  assert.equal(meta.website, "https://freetheai.xyz");
+  assert.equal(meta.hasFree, true);
+  assert.equal(typeof meta.freeNote, "string");
+  assert.ok((meta.freeNote as string).length > 0);
+});
--- a/tests/unit/providers-constants-split.test.ts
+++ b/tests/unit/providers-constants-split.test.ts
@@ -37,12 +37,12 @@ test("barrel still exports every catalog + key helpers", () => {
  }
 });

-test("APIKEY_PROVIDERS merges the 6 family files into 168 entries (no loss / no dup)", async () => {
+test("APIKEY_PROVIDERS merges the 6 family files into 170 entries (no loss / no dup)", async () => {
  const keys = Object.keys((P as Record<string, object>).APIKEY_PROVIDERS);
-  assert.equal(keys.length, 168);
-  assert.equal(new Set(keys).size, 168, "duplicate keys after spread-merge");
+  assert.equal(keys.length, 170);
+  assert.equal(new Set(keys).size, 170, "duplicate keys after spread-merge");
  // the merged object's entry-count equals the sum of the 6 semantic family files; families are a
-  // strict partition (every provider in exactly one), so the sum must be exactly 168.
+  // strict partition (every provider in exactly one), so the sum must be exactly 170.
  const families: [string, string][] = [
    ["gateways", "APIKEY_PROVIDERS_GATEWAYS"],
    ["frontier-labs", "APIKEY_PROVIDERS_FRONTIER"],
@@ -62,7 +62,7 @@ test("APIKEY_PROVIDERS merges the 6 family files into 168 entries (no loss / no
      seen.add(k);
    }
  }
-  assert.equal(famTotal, 168, "families must partition all 168 providers");
+  assert.equal(famTotal, 170, "families must partition all 170 providers");
 });

 test("AI_PROVIDERS Proxy aggregates all sections; lookups resolve", () => {
				`@@ -0,0 +1 @@`
				`- feat(providers): add FreeTheAi as an OpenAI-compatible gateway provider with a free Discord-signup tier (#6670)`