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

feat(providers): add Lucidity Composite, Api.Airforce, DreamPrompting, Waterfall and Logfare adapters (#1237)

Tashfeenbf5c778392d4
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsx
index 3d9b8f25..ae7cffaf 100644
--- a/client/src/components/keys/shared.tsx
+++ b/client/src/components/keys/shared.tsx
@@ -37,6 +37,11 @@ export const PLATFORMS: { value: Platform; label: string; url: string; keyless?:
{ value: 'clod', label: 'CLōD (shared daily free requests)', url: 'https://newapp.clod.io' },
{ value: 'speechify', label: 'Speechify (monthly free TTS characters)', url: 'https://platform.speechify.ai' },
{ value: 'blaze', label: 'BlazeAPI (daily free tokens; Discord verification)', url: 'https://blazeapi.org/dashboard' },
+ { value: 'lucidity', label: 'Lucidity Composite (daily free-model requests)', url: 'https://composite.lucidity.sh' },
+ { value: 'airforce', label: 'Api.Airforce (daily free requests; 1 per minute)', url: 'https://api.airforce' },
+ { value: 'dreamprompting', label: 'DreamPrompting (rolling 24h free tokens and requests)', url: 'https://dreamprompting.com' },
+ { value: 'waterfall', label: 'Waterfall (community free models)', url: 'https://getwaterfall.org' },
+ { value: 'logfare', label: 'Logfare (fair-use free models)', url: 'https://logfare.ai' },
{ value: 'bai', label: 'B.AI (promotional free model)', url: 'https://b.ai' },
{ value: 'radeon', label: 'AMD Radeon Cloud (free shared models)', url: 'https://developer.amd.com.cn/radeon/tokenfactory' },
{ value: 'nvidia', label: 'NVIDIA NIM', url: 'https://build.nvidia.com/settings/api-keys' },
diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.ts
index 9620a43a..7a5fd46d 100644
--- a/client/src/lib/routing.ts
+++ b/client/src/lib/routing.ts
@@ -408,6 +408,11 @@ export const platformColors: Record<string, string> = {
clod: '#16a34a',
speechify: '#7c3aed',
blaze: '#f97316',
+ lucidity: '#6366f1',
+ airforce: '#0ea5e9',
+ dreamprompting: '#db2777',
+ waterfall: '#0d9488',
+ logfare: '#ca8a04',
bai: '#111827',
radeon: '#ed1c24',
nvidia: '#76b900',
diff --git a/docs/lucidity-airforce-dreamprompting-waterfall-logfare.md b/docs/lucidity-airforce-dreamprompting-waterfall-logfare.md
new file mode 100644
index 00000000..61b242b8
--- /dev/null
+++ b/docs/lucidity-airforce-dreamprompting-waterfall-logfare.md
@@ -0,0 +1,62 @@
+# Lucidity Composite, Api.Airforce, DreamPrompting, Waterfall and Logfare
+
+All five are first-class OpenAI-compatible chat providers. Select them on the
+Keys page or import `LUCIDITY_API_KEY` / `AIRFORCE_API_KEY` /
+`DREAMPROMPTING_API_KEY` / `WATERFALL_API_KEY` / `LOGFARE_API_KEY`. This
+integration does not seed model rows: the signed Oracle catalog controls
+availability and the existing Premium-immediate / Free-after-30-days release
+gate.
+
+## Free access (checked 2026-09-15)
+
+- [Lucidity Composite](https://composite.lucidity.sh): 250 free-model requests
+ per day, shared across the account (`lucidity::daily-free`). Tested catalog
+ routes: `lucidityai/synth-2.5-flash:free`, `lucidityai/synth-2.5-pro:free`,
+ `inclusionai/ling-3.0-flash:free` and `mistralai/mistral-nemo:free`.
+- [Api.Airforce](https://api.airforce): 1,000 requests per day and 1 request
+ per minute per account (`airforce::daily-free`). The response echoed the
+ requested id on all 20 tested routes.
+- [DreamPrompting](https://dreamprompting.com): 500K tokens and 5,000 requests
+ per rolling 24 hours (`dreamprompting::daily-free`).
+- [Waterfall](https://getwaterfall.org): community free `-free` routes
+ (`waterfall::community-free`). The response echoed the requested id exactly
+ on every tested route.
+- [Logfare](https://logfare.ai): fair-use free models (`logfare::fair-use`).
+ `logfare/auto` echoes `logfare/auto` and `gemma-4-26b` echoes itself.
+
+## Integration details
+
+Every provider authenticates `GET /models` with the bearer key, so key
+validation is a non-generating request: 401/403 is invalid, any other failure
+stays inconclusive rather than disabling a valid key.
+
+Each adapter rejects a mismatched or missing response model id with a
+retryable 502, including before yielding stream content, instead of silently
+reporting a substituted model. The accepted identities differ per gateway:
+
+- Lucidity drops the `:free` suffix in its echo, and both `lucidityai/synth-*`
+ routes legitimately report the gateway's own `synth-2.5-preview`. Its
+ `open/*` routes were observed silently answering as `synth-2.5-preview`; the
+ adapter rejects that, and no `open/*` route is published.
+- Api.Airforce, Waterfall and Logfare must echo the requested id exactly.
+- DreamPrompting is a fail-over router. Routes are addressed as
+ `<upstream>/<upstream model id>` and the response reports the upstream id
+ (`groq/openai/gpt-oss-20b` answers as `openai/gpt-oss-20b`,
+ `codestral/codestral-latest` as `codestral-latest`, `chat/ch.at` as `ch.at`),
+ with any `:free` suffix dropped. The `auto` route legitimately reports
+ whichever upstream served the call, so its identity is not checked.
+
+Api.Airforce's per-minute limit answers 429 with `Retry-After`; the adapter
+surfaces that as the key cooldown and never retries into it. Waterfall's
+upstream outages arrive as a 503 with a structured `detail` object
+(`waterfall_transport_error` / `upstream_unavailable`) and surface as a 503
+provider error. Logfare answers 403 for premium routes (surfaced as a 403
+provider error), includes `reasoning_content` in responses and reports an extra
+`neurons` usage field; both fields pass through untouched.
+
+No quota headers are parsed for these providers: none was verified, so no
+per-model budget is invented. Model-ID matching is provider response evidence,
+not independent verification of underlying weights.
+
+No keys, paid plans, catalog snapshots, DB model migrations, or release-gate
+changes are included in this integration.
diff --git a/server/src/__tests__/lib/key-parser.test.ts b/server/src/__tests__/lib/key-parser.test.ts
index ce66e995..8cc02601 100644
--- a/server/src/__tests__/lib/key-parser.test.ts
+++ b/server/src/__tests__/lib/key-parser.test.ts
@@ -78,6 +78,13 @@ describe('key parser', () => {
expect(detectPlatform('EXPLABS_')).toBe('experiential');
expect(detectPlatform('ROUTER9_')).toBe('router9');
expect(detectPlatform('ROUTER_9_')).toBe('router9');
+ expect(detectPlatform('LUCIDITY_')).toBe('lucidity');
+ expect(detectPlatform('AIRFORCE_')).toBe('airforce');
+ expect(detectPlatform('API_AIRFORCE_')).toBe('airforce');
+ expect(detectPlatform('DREAMPROMPTING_')).toBe('dreamprompting');
+ expect(detectPlatform('DREAM_PROMPTING_')).toBe('dreamprompting');
+ expect(detectPlatform('WATERFALL_')).toBe('waterfall');
+ expect(detectPlatform('LOGFARE_')).toBe('logfare');
expect(detectPlatform('SEPTOR_')).toBe('septor');
expect(detectPlatform('SEPTORLABS_')).toBe('septor');
expect(detectPlatform('SEPTOR_LABS_')).toBe('septor');
@@ -107,6 +114,13 @@ describe('key parser', () => {
expect(AUTH_JSON_PROVIDER_MAP['septor']).toBe('septor');
expect(AUTH_JSON_PROVIDER_MAP['septor-labs']).toBe('septor');
expect(AUTH_JSON_PROVIDER_MAP['septorlabs']).toBe('septor');
+ expect(AUTH_JSON_PROVIDER_MAP['lucidity']).toBe('lucidity');
+ expect(AUTH_JSON_PROVIDER_MAP['airforce']).toBe('airforce');
+ expect(AUTH_JSON_PROVIDER_MAP['api.airforce']).toBe('airforce');
+ expect(AUTH_JSON_PROVIDER_MAP['dreamprompting']).toBe('dreamprompting');
+ expect(AUTH_JSON_PROVIDER_MAP['dream-prompting']).toBe('dreamprompting');
+ expect(AUTH_JSON_PROVIDER_MAP['waterfall']).toBe('waterfall');
+ expect(AUTH_JSON_PROVIDER_MAP['logfare']).toBe('logfare');
const result = parseAuthJson(JSON.stringify({
credential_pool: {
gemini: [{ id: '1', label: 'Gemini', auth_type: 'api_key', access_token: 'AIza-test' }],
@@ -127,7 +141,7 @@ describe('key parser', () => {
expect(result.skipped).toEqual(['PORT: value does not look like an API key']);
});
- it.each([['CLOD', 'clod'], ['SPEECHIFY', 'speechify'], ['BLAZE', 'blaze'], ['BLAZEAPI', 'blaze']])('imports %s environment keys', (prefix, platform) => {
+ it.each([['CLOD', 'clod'], ['SPEECHIFY', 'speechify'], ['BLAZE', 'blaze'], ['BLAZEAPI', 'blaze'], ['LUCIDITY', 'lucidity'], ['AIRFORCE', 'airforce'], ['API_AIRFORCE', 'airforce'], ['DREAMPROMPTING', 'dreamprompting'], ['DREAM_PROMPTING', 'dreamprompting'], ['WATERFALL', 'waterfall'], ['LOGFARE', 'logfare']])('imports %s environment keys', (prefix, platform) => {
const result = parseKeysFromFile(`${prefix}_API_KEY=not-a-real-provider-key`, 'keys.env');
expect(result.keys).toHaveLength(1);
expect(result.keys[0].platform).toBe(platform);
diff --git a/server/src/__tests__/providers/lucidity-airforce-dreamprompting-waterfall-logfare.test.ts b/server/src/__tests__/providers/lucidity-airforce-dreamprompting-waterfall-logfare.test.ts
new file mode 100644
index 00000000..0451e575
--- /dev/null
+++ b/server/src/__tests__/providers/lucidity-airforce-dreamprompting-waterfall-logfare.test.ts
@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getProvider, hasProvider } from '../../providers/index.js';
+
+const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
+ new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json', ...headers } });
+const completion = (model: string) => ({ id: 'test', object: 'chat.completion', created: 1, model,
+ choices: [{ index: 0, message: { role: 'assistant', content: '17' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 8, completion_tokens: 1, total_tokens: 9 } });
+const stream = (model: string) => new Response(`data: ${JSON.stringify({ id: 'test', object: 'chat.completion.chunk', created: 1, model,
+ choices: [{ index: 0, delta: { content: '17' }, finish_reason: 'stop' }] })}\n\ndata: [DONE]\n\n`, { headers: { 'Content-Type': 'text/event-stream' } });
+
+const PLATFORMS = ['lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare'] as const;
+const BASE: Record<(typeof PLATFORMS)[number], string> = {
+ lucidity: 'https://composite.lucidity.sh/v1',
+ airforce: 'https://api.airforce/v1',
+ dreamprompting: 'https://dreamprompting.com/api/v1',
+ waterfall: 'https://api.getwaterfall.org/v1',
+ logfare: 'https://logfare.ai/v1',
+};
+
+describe('Lucidity Composite, Api.Airforce, DreamPrompting, Waterfall and Logfare adapters', () => {
+ afterEach(() => vi.restoreAllMocks());
+
+ it.each(PLATFORMS)('%s validates on the authenticated /models endpoint', async platform => {
+ expect(hasProvider(platform)).toBe(true);
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json({ data: [] }));
+ await expect(getProvider(platform)!.validateKey('test-key')).resolves.toBe(true);
+ expect(fetch.mock.calls[0][0]).toBe(`${BASE[platform]}/models`);
+ expect(fetch.mock.calls[0][1]?.method).toBe('GET');
+ expect(new Headers(fetch.mock.calls[0][1]?.headers).get('Authorization')).toBe('Bearer test-key');
+ fetch.mockResolvedValue(json({ error: 'Invalid key' }, 401));
+ await expect(getProvider(platform)!.validateKey('test-key')).resolves.toMatchObject({ valid: false });
+ fetch.mockResolvedValue(json({ error: 'Unavailable' }, 503));
+ await expect(getProvider(platform)!.validateKey('test-key')).rejects.toThrow();
+ });
+
+ it.each([
+ // Lucidity: `:free` is dropped in the echo; synth routes report the gateway's preview id.
+ ['lucidity', 'lucidityai/synth-2.5-flash:free', 'synth-2.5-preview'],
+ ['lucidity', 'lucidityai/synth-2.5-pro:free', 'synth-2.5-preview'],
+ ['lucidity', 'inclusionai/ling-3.0-flash:free', 'inclusionai/ling-3.0-flash'],
+ ['lucidity', 'mistralai/mistral-nemo:free', 'mistralai/mistral-nemo'],
+ ['airforce', 'gpt-oss-120b', 'gpt-oss-120b'],
+ // DreamPrompting: the upstream prefix is dropped in the echo; `auto` may report anything.
+ ['dreamprompting', 'groq/openai/gpt-oss-20b', 'openai/gpt-oss-20b'],
+ ['dreamprompting', 'nvidia/nvidia/nemotron-3-super-120b-a12b', 'nvidia/nemotron-3-super-120b-a12b'],
+ ['dreamprompting', 'codestral/codestral-latest', 'codestral-latest'],
+ ['dreamprompting', 'chat/ch.at', 'ch.at'],
+ ['dreamprompting', 'openrouter/some/model:free', 'some/model'],
+ ['dreamprompting', 'auto', 'whatever/served-it'],
+ ['waterfall', 'llama-3.3-70b-free', 'llama-3.3-70b-free'],
+ ['logfare', 'logfare/auto', 'logfare/auto'],
+ ['logfare', 'gemma-4-26b', 'gemma-4-26b'],
+ ] as const)('%s sends exact requested IDs and accepts a matching upstream identity (%s)', async (platform, requested, returned) => {
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json(completion(returned)));
+ const provider = getProvider(platform)!;
+ const result = await provider.chatCompletion('test-key', [{ role: 'user', content: '8+9' }], requested, { max_tokens: 64, temperature: 0.2 });
+ expect(result.model).toBe(returned);
+ expect(result.usage.total_tokens).toBe(9);
+ expect(result._routed_via).toEqual({ platform, model: requested });
+ expect(fetch.mock.calls[0][0]).toBe(`${BASE[platform]}/chat/completions`);
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toMatchObject({ model: requested, max_tokens: 64, temperature: 0.2 });
+ fetch.mockResolvedValue(stream(returned));
+ const emitted = [];
+ for await (const chunk of provider.streamChatCompletion('test-key', [], requested)) emitted.push(chunk);
+ expect(emitted.flatMap(c => c.choices).map(c => c.delta.content ?? '').join('')).toBe('17');
+ });
+
+ it.each([
+ // Lucidity's `open/*` routes were observed silently answering as synth-2.5-preview.
+ ['lucidity', 'open/some-model:free', ['synth-2.5-preview', 'mistralai/mistral-nemo', '']],
+ ['airforce', 'gpt-oss-120b', ['gpt-oss-20b', 'openai/gpt-oss-120b', '']],
+ ['dreamprompting', 'groq/openai/gpt-oss-20b', ['openai/gpt-oss-120b', 'gpt-oss-20b', '']],
+ ['waterfall', 'llama-3.3-70b-free', ['llama-3.3-70b', '']],
+ ['logfare', 'gemma-4-26b', ['logfare/auto', '']],
+ ] as const)('%s rejects substitutions and missing identity before emitting content', async (platform, requested, substitutions) => {
+ const fetch = vi.spyOn(globalThis, 'fetch');
+ const provider = getProvider(platform)!;
+ for (const returned of substitutions) {
+ fetch.mockResolvedValue(json(completion(returned)));
+ await expect(provider.chatCompletion('test-key', [], requested)).rejects.toMatchObject({ status: 502 });
+ fetch.mockResolvedValue(stream(returned));
+ const emitted = [];
+ const consume = async () => { for await (const c of provider.streamChatCompletion('test-key', [], requested)) emitted.push(c); };
+ await expect(consume()).rejects.toMatchObject({ status: 502 });
+ expect(emitted).toEqual([]);
+ }
+ });
+
+ it.each(PLATFORMS)('%s preserves provider backoff and never retries a 429', async platform => {
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json({ error: { message: 'Quota exhausted' } }, 429, { 'Retry-After': '60' }));
+ await expect(getProvider(platform)!.chatCompletion('test-key', [], 'test-model')).rejects.toMatchObject({ status: 429, retryAfterMs: 60000 });
+ expect(fetch).toHaveBeenCalledTimes(1);
+ });
+
+ it('Waterfall surfaces a structured upstream_unavailable body as a 503 provider error', async () => {
+ const body = { detail: { type: 'waterfall_transport_error', code: 'upstream_unavailable' } };
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json(body, 503));
+ const provider = getProvider('waterfall')!;
+ await expect(provider.chatCompletion('test-key', [], 'llama-3.3-70b-free')).rejects.toMatchObject({ status: 503 });
+ await expect(provider.streamChatCompletion('test-key', [], 'llama-3.3-70b-free').next()).rejects.toMatchObject({ status: 503 });
+ expect(fetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('Logfare surfaces a premium-model 403 as a provider error and passes reasoning_content and neurons through', async () => {
+ const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(json({ error: { message: 'This is a premium model' } }, 403));
+ const provider = getProvider('logfare')!;
+ await expect(provider.chatCompletion('test-key', [], 'premium-model')).rejects.toMatchObject({ status: 403, message: expect.stringContaining('premium model') });
+ expect(fetch).toHaveBeenCalledTimes(1);
+ fetch.mockResolvedValue(json({ ...completion('gemma-4-26b'),
+ choices: [{ index: 0, message: { role: 'assistant', content: '17', reasoning_content: '8+9=17' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 8, completion_tokens: 1, total_tokens: 9, neurons: 3 } }));
+ const result = await provider.chatCompletion('test-key', [], 'gemma-4-26b');
+ expect(result.choices[0].message).toMatchObject({ content: '17', reasoning_content: '8+9=17' });
+ expect(result.usage).toMatchObject({ total_tokens: 9, neurons: 3 });
+ });
+});
diff --git a/server/src/__tests__/routes/keys.test.ts b/server/src/__tests__/routes/keys.test.ts
index e46f6d9c..f1f0ff5d 100644
--- a/server/src/__tests__/routes/keys.test.ts
+++ b/server/src/__tests__/routes/keys.test.ts
@@ -154,7 +154,7 @@ describe('Keys API', () => {
expect(status).toBe(400);
});
- it.each(['electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze'])('accepts a %s key without seeding gated model rows', async platform => {
+ it.each(['electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare'])('accepts a %s key without seeding gated model rows', async platform => {
const { status, body } = await request(app, 'POST', '/api/keys', {
platform, key: 'not-a-real-test-key-12345', label: 'Gateway test',
});
diff --git a/server/src/__tests__/services/provider-quota.test.ts b/server/src/__tests__/services/provider-quota.test.ts
index c2f6f0c2..78f9d635 100644
--- a/server/src/__tests__/services/provider-quota.test.ts
+++ b/server/src/__tests__/services/provider-quota.test.ts
@@ -53,6 +53,11 @@ describe('provider-quota: pool inference', () => {
expect(inferQuotaPoolKey('clod', model)).toBe('clod::daily-free');
expect(inferQuotaPoolKey('blaze', model)).toBe('blaze::daily-free');
expect(inferQuotaPoolKey('speechify', model)).toBe('speechify::monthly-characters');
+ expect(inferQuotaPoolKey('lucidity', model)).toBe('lucidity::daily-free');
+ expect(inferQuotaPoolKey('airforce', model)).toBe('airforce::daily-free');
+ expect(inferQuotaPoolKey('dreamprompting', model)).toBe('dreamprompting::daily-free');
+ expect(inferQuotaPoolKey('waterfall', model)).toBe('waterfall::community-free');
+ expect(inferQuotaPoolKey('logfare', model)).toBe('logfare::fair-use');
}
expect(inferQuotaPoolKey('openrouter', 'meta-llama/llama-3.1-8b-instruct:free')).toBe('openrouter::free');
expect(inferQuotaPoolKey('openrouter', 'openai/gpt-4o')).toBe('openrouter::account');
diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.ts
index 8254f5ca..795aac91 100644
--- a/server/src/lib/key-parser.ts
+++ b/server/src/lib/key-parser.ts
@@ -60,6 +60,13 @@ export const PREFIX_MAP: Record<string, string> = {
SPEECHIFY_: 'speechify',
BLAZE_: 'blaze',
BLAZEAPI_: 'blaze',
+ LUCIDITY_: 'lucidity',
+ AIRFORCE_: 'airforce',
+ API_AIRFORCE_: 'airforce',
+ DREAMPROMPTING_: 'dreamprompting',
+ DREAM_PROMPTING_: 'dreamprompting',
+ WATERFALL_: 'waterfall',
+ LOGFARE_: 'logfare',
BAI_: 'bai',
B_AI_: 'bai',
RADEON_: 'radeon',
@@ -141,6 +148,13 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {
speechify: 'speechify',
blaze: 'blaze',
blazeapi: 'blaze',
+ lucidity: 'lucidity',
+ airforce: 'airforce',
+ 'api.airforce': 'airforce',
+ dreamprompting: 'dreamprompting',
+ 'dream-prompting': 'dreamprompting',
+ waterfall: 'waterfall',
+ logfare: 'logfare',
bai: 'bai',
'b-ai': 'bai',
radeon: 'radeon',
diff --git a/server/src/providers/airforce.ts b/server/src/providers/airforce.ts
new file mode 100644
index 00000000..5a01fb71
--- /dev/null
+++ b/server/src/providers/airforce.ts
@@ -0,0 +1,44 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+
+function checkModel(requested: string, returned: string): void {
+ if (!returned || returned !== requested) {
+ throw Object.assign(new Error('Api.Airforce returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+export class AirforceProvider extends OpenAICompatProvider {
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (!response.ok && ![401, 403].includes(response.status)) {
+ throw providerHttpError(response, 'Api.Airforce key validation is temporarily inconclusive');
+ }
+ return super.validationResult(response);
+ }
+
+ constructor() {
+ // One request per minute per account: a 429 carries Retry-After and is
+ // surfaced as-is so the router backs off instead of retrying into it.
+ super({ platform: 'airforce', name: 'Api.Airforce', baseUrl: 'https://api.airforce/v1' });
+ }
+
+ override async chatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/providers/dreamprompting.ts b/server/src/providers/dreamprompting.ts
new file mode 100644
index 00000000..2c9432fe
--- /dev/null
+++ b/server/src/providers/dreamprompting.ts
@@ -0,0 +1,54 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+
+function checkModel(requested: string, returned: string): void {
+ // DreamPrompting is a fail-over router. `auto` legitimately reports
+ // whichever upstream served the call. Every other route is addressed as
+ // `<upstream>/<upstream model id>` and the response reports the upstream
+ // id: `groq/openai/gpt-oss-20b` -> `openai/gpt-oss-20b`,
+ // `codestral/codestral-latest` -> `codestral-latest`, `chat/ch.at` ->
+ // `ch.at`, with any `:free` suffix dropped. Anything else is a substitution.
+ if (requested === 'auto') return;
+ const stripped = requested.replace(/:free$/, '');
+ const unprefixed = stripped.includes('/') ? stripped.slice(stripped.indexOf('/') + 1) : stripped;
+ const accepted = typeof returned === 'string' && returned.length > 0 && (
+ returned === requested || returned === stripped || returned === unprefixed
+ );
+ if (!accepted) {
+ throw Object.assign(new Error('DreamPrompting returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+export class DreamPromptingProvider extends OpenAICompatProvider {
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (!response.ok && ![401, 403].includes(response.status)) {
+ throw providerHttpError(response, 'DreamPrompting key validation is temporarily inconclusive');
+ }
+ return super.validationResult(response);
+ }
+
+ constructor() {
+ super({ platform: 'dreamprompting', name: 'DreamPrompting', baseUrl: 'https://dreamprompting.com/api/v1' });
+ }
+
+ override async chatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/providers/index.ts b/server/src/providers/index.ts
index eb62a5d2..29a11c31 100644
--- a/server/src/providers/index.ts
+++ b/server/src/providers/index.ts
@@ -16,6 +16,11 @@ import { SeptorProvider } from './septor.js';
import { ClodProvider } from './clod.js';
import { SpeechifyProvider } from './speechify.js';
import { BlazeProvider } from './blaze.js';
+import { LucidityProvider } from './lucidity.js';
+import { AirforceProvider } from './airforce.js';
+import { DreamPromptingProvider } from './dreamprompting.js';
+import { WaterfallProvider } from './waterfall.js';
+import { LogfareProvider } from './logfare.js';
const providers = new Map<Platform, BaseProvider>();
@@ -62,6 +67,13 @@ register(new SeptorProvider());
register(new ClodProvider());
register(new SpeechifyProvider());
register(new BlazeProvider());
+// Five more OpenAI-compatible gateways. Each pins the response model to the
+// requested route (502 on substitution); rows stay in the hosted catalog.
+register(new LucidityProvider());
+register(new AirforceProvider());
+register(new DreamPromptingProvider());
+register(new WaterfallProvider());
+register(new LogfareProvider());
// B.AI — OpenAI-compatible gateway. Provider support is first-class, but the
// only free catalog row currently published is a limited-time 0-credit promo;
diff --git a/server/src/providers/logfare.ts b/server/src/providers/logfare.ts
new file mode 100644
index 00000000..cbd83329
--- /dev/null
+++ b/server/src/providers/logfare.ts
@@ -0,0 +1,45 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+
+function checkModel(requested: string, returned: string): void {
+ if (!returned || returned !== requested) {
+ throw Object.assign(new Error('Logfare returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+export class LogfareProvider extends OpenAICompatProvider {
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (!response.ok && ![401, 403].includes(response.status)) {
+ throw providerHttpError(response, 'Logfare key validation is temporarily inconclusive');
+ }
+ return super.validationResult(response);
+ }
+
+ constructor() {
+ // Responses carry `reasoning_content` (handled by the shared fold) and an
+ // extra `neurons` usage field that is passed through untouched. Premium
+ // routes answer 403 and surface as a provider error, never as a retry.
+ super({ platform: 'logfare', name: 'Logfare', baseUrl: 'https://logfare.ai/v1' });
+ }
+
+ override async chatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/providers/lucidity.ts b/server/src/providers/lucidity.ts
new file mode 100644
index 00000000..f98056b8
--- /dev/null
+++ b/server/src/providers/lucidity.ts
@@ -0,0 +1,51 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+
+function checkModel(requested: string, returned: string): void {
+ // Catalog routes carry a `:free` suffix that the response omits, and the
+ // `lucidityai/synth-2.5-*:free` routes legitimately report the gateway's
+ // own `synth-2.5-preview`. Anything else (including the `open/*` routes
+ // observed silently answering as synth-2.5-preview) is a substitution.
+ const accepted = typeof returned === 'string' && returned.length > 0 && (
+ returned === requested ||
+ returned === requested.replace(/:free$/, '') ||
+ (requested.startsWith('lucidityai/synth-') && returned.startsWith('synth-'))
+ );
+ if (!accepted) {
+ throw Object.assign(new Error('Lucidity Composite returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+export class LucidityProvider extends OpenAICompatProvider {
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (!response.ok && ![401, 403].includes(response.status)) {
+ throw providerHttpError(response, 'Lucidity Composite key validation is temporarily inconclusive');
+ }
+ return super.validationResult(response);
+ }
+
+ constructor() {
+ super({ platform: 'lucidity', name: 'Lucidity Composite', baseUrl: 'https://composite.lucidity.sh/v1' });
+ }
+
+ override async chatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/providers/waterfall.ts b/server/src/providers/waterfall.ts
new file mode 100644
index 00000000..8394294f
--- /dev/null
+++ b/server/src/providers/waterfall.ts
@@ -0,0 +1,45 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+
+function checkModel(requested: string, returned: string): void {
+ if (!returned || returned !== requested) {
+ throw Object.assign(new Error('Waterfall returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+export class WaterfallProvider extends OpenAICompatProvider {
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (!response.ok && ![401, 403].includes(response.status)) {
+ throw providerHttpError(response, 'Waterfall key validation is temporarily inconclusive');
+ }
+ return super.validationResult(response);
+ }
+
+ constructor() {
+ // Upstream outages arrive as 503 with a structured `detail` object
+ // ({"type":"waterfall_transport_error","code":"upstream_unavailable"});
+ // the shared error path keeps the status and falls back to statusText.
+ super({ platform: 'waterfall', name: 'Waterfall', baseUrl: 'https://api.getwaterfall.org/v1' });
+ }
+
+ override async chatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index d1e9b8fa..f8d128b6 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -30,7 +30,7 @@ export const keysRouter = Router();
// was dropped in V4 and re-added in V13 via the router.huggingface.co route.
// SambaNova was dropped in V23 (free tier permanently retired).
const PLATFORMS = [
- 'google', 'groq', 'cerebras', 'sail', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'bai', 'radeon', 'nvidia', 'mistral',
+ 'google', 'groq', 'cerebras', 'sail', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare', 'bai', 'radeon', 'nvidia', 'mistral',
'openrouter', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama',
'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'ovh', 'agnes', 'reka', 'siliconflow',
'routeway', 'bazaarlink', 'ainative', 'aion', 'anyapi', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'modelscope',
diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.ts
index 9675f412..dff6a18b 100644
--- a/server/src/services/provider-quota.ts
+++ b/server/src/services/provider-quota.ts
@@ -123,6 +123,11 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | null
if (platform === 'clod') return 'clod::daily-free';
if (platform === 'speechify') return 'speechify::monthly-characters';
if (platform === 'blaze') return 'blaze::daily-free';
+ if (platform === 'lucidity') return 'lucidity::daily-free';
+ if (platform === 'airforce') return 'airforce::daily-free';
+ if (platform === 'dreamprompting') return 'dreamprompting::daily-free';
+ if (platform === 'waterfall') return 'waterfall::community-free';
+ if (platform === 'logfare') return 'logfare::fair-use';
if (platform === 'bai') return 'bai::promo';
if (platform === 'radeon') return 'radeon::daily-free';
if (platform === 'sambanova') return 'sambanova::shared';
@@ -171,7 +176,7 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | null
}
function isSharedPool(platform: Platform): boolean {
- if (['electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze'].includes(platform)) return true;
+ if (['electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare'].includes(platform)) return true;
return ['openrouter', 'google', 'groq', 'cerebras', 'sail', 'bai', 'radeon', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aion', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'anyapi', 'modelscope', 'aihorde'].includes(platform);
}
diff --git a/shared/types.ts b/shared/types.ts
index 788bbd61..f390441b 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -78,6 +78,13 @@ export type Platform =
| 'clod'
| 'speechify'
| 'blaze'
+ // Lucidity Composite, Api.Airforce and DreamPrompting expose daily free
+ // allowances; Waterfall and Logfare publish community / fair-use tiers.
+ | 'lucidity'
+ | 'airforce'
+ | 'dreamprompting'
+ | 'waterfall'
+ | 'logfare'
// B.AI — OpenAI-compatible gateway. Its catalog row is a live-tested,
// limited-time 0-credit promotion, not a recurring free allowance.
| 'bai'