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 onomeo free OpenAI-compatible gateway (#1460) (#1610)

tashdroid215cd91e5b9a
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsx
index 01b7041e..19870120 100644
--- a/client/src/components/keys/shared.tsx
+++ b/client/src/components/keys/shared.tsx
@@ -34,6 +34,7 @@ export const PLATFORMS: { value: Platform; label: string; url: string; keyless?:
{ value: 'speka', label: 'Speka ($1 shared monthly credits)', url: 'https://speka.me/dashboard/keys' },
{ value: 'beatapi', label: 'BeatAPI (JEV decisions; temporary free offer)', url: 'https://beatapi.io' },
{ value: 'apinex', label: 'APINex (shared daily free chat and decisions)', url: 'https://apinex.bond/keys' },
+ { value: 'onomeo', label: 'onomeo (30 free calls / 5 hours, shared)', url: 'https://onomeo.com/dashboard' },
{ value: 'typhoon', label: 'Typhoon (free research API)', url: 'https://playground.opentyphoon.ai' },
{ value: 'plugsky', label: 'Plugsky (free chat aliases)', url: 'https://plugsky.com/dashboard' },
{ value: 'inferbase', label: 'Inferbase (shared monthly and daily allowance)', url: 'https://inferbase.ai' },
diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.ts
index 35d97feb..9cb9256b 100644
--- a/client/src/lib/routing.ts
+++ b/client/src/lib/routing.ts
@@ -484,6 +484,7 @@ export const platformColors: Record<string, string> = {
serpsearch: '#2563eb',
beatapi: '#8b5cf6',
apinex: '#06b6d4',
+ onomeo: '#f97316',
}
// ── Grouped (unified) rendering ──────────────────────────────────────────────
diff --git a/docs/ONOMEO.md b/docs/ONOMEO.md
new file mode 100644
index 00000000..2d1f998f
--- /dev/null
+++ b/docs/ONOMEO.md
@@ -0,0 +1,40 @@
+# onomeo
+
+onomeo uses `https://onomeo.com/v1`, with Bearer API-key authentication.
+Add a key in the dashboard or import `ONOMEO_API_KEY` from an environment file.
+
+- Chat and SSE: `POST /chat/completions`, OpenAI request/response shape.
+- Key validation: read-only `GET /models`. Anonymous and invalid keys both get
+ `401 {error: {code: "bad_key"}}` (verified live 2026-10-20), so it is a real
+ credential probe; a valid key gets `{data: [...]}`.
+- A `403` with `account_quota` or `network_quota`, and a `429` with `site_busy`
+ or `too_fast`, are quota/throttle verdicts on a VALID key — validation treats
+ them as inconclusive so the health pass can never auto-disable a good key
+ whose 5-hour calls ran out.
+- Other endpoints on the same key (not routed by this adapter): `/v1/messages`
+ (paid models only), `/v1/responses`, `/v1/embeddings`, `/v1/rerank`,
+ `/v1/audio/transcriptions`, `/v1/images/generations`. `GET /api/me` (outside
+ `/v1`) reports balance and limits.
+
+## Free eligibility, verified 2026-10-20
+
+Free models are counted in CALLS, not tokens: 30 calls per account every
+5 hours, of which the whole site shares 1,500 per window; a long request
+counts as several calls (one per 50,000 counted characters). A payment grants
+90 calls/5h for 35 days. Quota responses name themselves: `account_quota`
+(403), `network_quota` (403), `site_busy` (429), `too_fast` (429).
+`bad_key` (401) is the only authentication verdict. Answers to balance-less
+accounts end with an "— via onomeo.com" signature line (tool-call,
+structured-output and pure-JSON answers are exempt). The adapter strips it from
+completions and streams (live 2026-10-21 it arrives as its own final delta), so
+clients and agents never see it.
+
+Model rows are published only through the signed Oracle catalog. No seeds,
+model-discovery enrollment, or database migration bypasses the existing
+Premium-now / Free-after-30-days release gate.
+
+Sources:
+
+- <https://onomeo.com/integrations>
+- <https://onomeo.com/help>
+- <https://onomeo.com/free-models>
diff --git a/server/src/__tests__/services/onomeo.test.ts b/server/src/__tests__/services/onomeo.test.ts
new file mode 100644
index 00000000..d5fbf207
--- /dev/null
+++ b/server/src/__tests__/services/onomeo.test.ts
@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { initDb, getDb } from '../../db/index.js';
+import { getProvider } from '../../providers/index.js';
+import { OnomeoProvider, ONOMEO_BASE_URL } from '../../providers/onomeo.js';
+import { AUTH_JSON_PROVIDER_MAP, parseKeysFromFile } from '../../lib/key-parser.js';
+import { inferPoolForPlatform } from '../../services/provider-quota.js';
+import { applyCatalog } from '../../services/catalog-sync.js';
+import { isBuiltinDiscoveryEligible } from '../../services/builtin-model-discovery.js';
+
+const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers });
+const modelList = { object: 'list', data: [{ id: 'glm-5.3', object: 'model' }] };
+const completion = (model?: string) => ({ id: 'c', object: 'chat.completion', created: 1, model,
+ choices: [{ index: 0, message: { role: 'assistant', content: 'OK' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 3, completion_tokens: 1, total_tokens: 4 } });
+
+beforeEach(() => { process.env.ENCRYPTION_KEY = '0'.repeat(64); initDb(':memory:'); });
+afterEach(() => { vi.restoreAllMocks(); getDb().close(); });
+
+describe('onomeo registration and import', () => {
+ it('registers the adapter, the env import alias and one shared quota pool (#1460)', () => {
+ expect(getProvider('onomeo')).toBeInstanceOf(OnomeoProvider);
+ expect(getProvider('onomeo')!.keyless).toBe(false);
+ expect(parseKeysFromFile('ONOMEO_API_KEY=test-key', 'keys.env').keys[0].platform).toBe('onomeo');
+ expect(AUTH_JSON_PROVIDER_MAP.onomeo).toBe('onomeo');
+ // One 30-calls/5-hour allowance shared across every free model, so a 429
+ // on one model benches the platform, not the model.
+ expect(inferPoolForPlatform('onomeo', 'glm-5.3')).toBe(inferPoolForPlatform('onomeo', 'qwen3.8-max'));
+ });
+});
+
+describe('onomeo key validation', () => {
+ it('accepts a model list from the read-only probe', async () => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json(modelList));
+ await expect(new OnomeoProvider().validateKey('test-key')).resolves.toBe(true);
+ expect(fetch.mock.calls[0][0]).toBe(`${ONOMEO_BASE_URL}/models`);
+ expect(new Headers(fetch.mock.calls[0][1]?.headers).get('authorization')).toBe('Bearer test-key');
+ });
+
+ it('marks 401 bad_key invalid', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { code: 'bad_key', message: 'Invalid API key, or the key has been revoked.' } }, 401));
+ await expect(new OnomeoProvider().validateKey('bad-key')).resolves.toMatchObject({ valid: false });
+ });
+
+ // The whole point of the override: base validationResult() treats 403 as an
+ // invalid key, and onomeo returns 403 account_quota/network_quota for a
+ // VALID key that used its 5-hour calls. Auto-disabling there would evict a
+ // good key that recovers on its own five hours later.
+ it.each([
+ [403, { error: { code: 'account_quota' } }],
+ [403, { error: { code: 'network_quota' } }],
+ [429, { error: { code: 'site_busy' } }],
+ [429, { error: { code: 'too_fast' } }],
+ [503, { error: { message: 'upstream down' } }],
+ ])('keeps quota/throttle/outage %s inconclusive, never invalid', async (status, body) => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json(body, status, { 'Retry-After': '300' }));
+ await expect(new OnomeoProvider().validateKey('test-key')).rejects.toMatchObject({ status, retryAfterMs: 300_000 });
+ });
+
+ it.each(['{}', 'null', '<html>Sign in</html>'])('rejects malformed probe bodies', async body => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response(body));
+ await expect(new OnomeoProvider().validateKey('test-key')).rejects.toMatchObject({ status: 502 });
+ });
+});
+
+describe('onomeo chat', () => {
+ it('forwards OpenAI-shape completions with attribution', async () => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json(completion('glm-5.3')));
+ const result = await new OnomeoProvider().chatCompletion('test-key', [{ role: 'user', content: 'Hi' }], 'glm-5.3', { max_tokens: 512 });
+ expect(fetch.mock.calls[0][0]).toBe(`${ONOMEO_BASE_URL}/chat/completions`);
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toMatchObject({ model: 'glm-5.3', max_tokens: 512 });
+ expect(result.choices[0].message.content).toBe('OK');
+ expect(result._routed_via).toEqual({ platform: 'onomeo', model: 'glm-5.3' });
+ });
+
+ it('strips the free-tier "— via onomeo.com" signature from a completion', async () => {
+ const body = completion('glm-5.2');
+ body.choices[0].message.content = '12\nGLM\n\n— via onomeo.com';
+ vi.spyOn(global, 'fetch').mockResolvedValue(json(body));
+ const result = await new OnomeoProvider().chatCompletion('test-key', [{ role: 'user', content: 'Hi' }], 'glm-5.2');
+ expect(result.choices[0].message.content).toBe('12\nGLM');
+ });
+
+ it.each([
+ ['as its own final delta (live shape)', ['Hello', ', my friend.', '\n\n— via onomeo.com']],
+ ['split across deltas', ['Hello, my friend.', '\n\n— via', ' onomeo.com']],
+ ])('strips the signature from a stream %s', async (_name, pieces) => {
+ const frames = [
+ { choices: [{ index: 0, delta: { role: 'assistant', content: '' }, finish_reason: null }] },
+ ...pieces.map(content => ({ choices: [{ index: 0, delta: { content }, finish_reason: null }] })),
+ { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+ ].map(f => `data: ${JSON.stringify({ id: 'c', object: 'chat.completion.chunk', created: 1, model: 'deepseek-v4-flash', ...f })}\n\n`);
+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response(frames.join('') + 'data: [DONE]\n\n', {
+ status: 200, headers: { 'content-type': 'text/event-stream' },
+ }));
+ const chunks = [];
+ for await (const c of new OnomeoProvider().streamChatCompletion('test-key', [], 'deepseek-v4-flash')) chunks.push(c);
+ expect(chunks.map(c => c.choices[0]?.delta?.content ?? '').join('')).toBe('Hello, my friend.');
+ expect(chunks[0].choices[0].delta.role).toBe('assistant');
+ expect(chunks.at(-1)!.choices[0].finish_reason).toBe('stop');
+ });
+
+ it('keeps a stream that only looks like the start of the signature', async () => {
+ const frames = ['Use a dash ', '\n—', ' or a comma.'].map(content =>
+ `data: ${JSON.stringify({ id: 'c', object: 'chat.completion.chunk', created: 1, model: 'm', choices: [{ index: 0, delta: { content }, finish_reason: null }] })}\n\n`);
+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response(frames.join('') + 'data: [DONE]\n\n', {
+ status: 200, headers: { 'content-type': 'text/event-stream' },
+ }));
+ const chunks = [];
+ for await (const c of new OnomeoProvider().streamChatCompletion('test-key', [], 'm')) chunks.push(c);
+ expect(chunks.map(c => c.choices[0]?.delta?.content ?? '').join('')).toBe('Use a dash \n— or a comma.');
+ });
+
+ it.each([403, 429])('preserves inference quota HTTP %s as failover-able, not key-fatal', async status => {
+ const code = status === 403 ? 'account_quota' : 'site_busy';
+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { code } }, status, { 'Retry-After': '60' }));
+ await expect(new OnomeoProvider().chatCompletion('test-key', [], 'glm-5.3')).rejects.toMatchObject({ status, retryAfterMs: 60_000 });
+ });
+});
+
+describe('onomeo catalog gate', () => {
+ it('does not seed or discover models; only ingests tier-selected catalog rows', () => {
+ const db = getDb();
+ expect(db.prepare('SELECT COUNT(*) AS n FROM models WHERE platform=?').get('onomeo')).toEqual({ n: 0 });
+ expect(isBuiltinDiscoveryEligible(db, 'onomeo')).toBe(false);
+ const result = applyCatalog(db, { version: '2099.01.01', generatedAt: new Date().toISOString(), tier: 'live', quirks: [],
+ models: [{ platform: 'onomeo', modelId: 'glm-5.3', displayName: 'GLM 5.3', intelligenceRank: 50, speedRank: 50, sizeLabel: '',
+ limits: { rpm: null, rpd: null, tpm: null, tpd: null }, monthlyTokenBudget: '30 calls / 5 h, shared', contextWindow: 128000,
+ enabled: true, supportsTools: true, supportsVision: false }] });
+ expect(result.skippedUnknownPlatform).toBe(0);
+ expect(db.prepare('SELECT model_id FROM models WHERE platform=?').all('onomeo')).toEqual([{ model_id: 'glm-5.3' }]);
+ });
+});
diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.ts
index 06261264..9eca8b4d 100644
--- a/server/src/lib/key-parser.ts
+++ b/server/src/lib/key-parser.ts
@@ -48,6 +48,7 @@ export const PREFIX_MAP: Record<string, string> = {
SPEKA_: 'speka',
BEATAPI_: 'beatapi',
APINEX_: 'apinex',
+ ONOMEO_: 'onomeo',
BEAT_API_: 'beatapi',
SERPSEARCH_: 'serpsearch',
SERP_SEARCH_: 'serpsearch',
@@ -163,6 +164,7 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {
speka: 'speka',
beatapi: 'beatapi',
apinex: 'apinex',
+ onomeo: 'onomeo',
serpsearch: 'serpsearch',
typhoon: 'typhoon',
plugsky: 'plugsky',
diff --git a/server/src/providers/index.ts b/server/src/providers/index.ts
index 2d7325bc..f7c096e1 100644
--- a/server/src/providers/index.ts
+++ b/server/src/providers/index.ts
@@ -39,6 +39,7 @@ import { WaterfallProvider } from './waterfall.js';
import { LogfareProvider } from './logfare.js';
import { BeatApiProvider } from './beatapi.js';
import { ApinexProvider } from './apinex.js';
+import { OnomeoProvider } from './onomeo.js';
import { SerpSearchProvider } from './serpsearch.js';
const providers = new Map<Platform, BaseProvider>();
@@ -85,6 +86,7 @@ register(new BlockRunProvider());
register(new MoondreamProvider());
register(new BeatApiProvider());
register(new ApinexProvider());
+register(new OnomeoProvider());
register(new SerpSearchProvider());
// Free-plan grants are shared wallets, not free credits per model. Eligibility
diff --git a/server/src/providers/onomeo.ts b/server/src/providers/onomeo.ts
new file mode 100644
index 00000000..755d8822
--- /dev/null
+++ b/server/src/providers/onomeo.ts
@@ -0,0 +1,115 @@
+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';
+
+export const ONOMEO_BASE_URL = 'https://onomeo.com/v1';
+
+// Free-tier answers end with this line (verified live 2026-10-21: every text
+// reply, streamed as its own final delta "\n\n— via onomeo.com"; tool-call
+// turns carry none). It is provider branding, not model output, so it must not
+// reach clients or agents that parse the text.
+const SIGNATURE = '— via onomeo.com';
+const SIGNATURE_TAIL = /\s*— via onomeo\.com\s*$/;
+const SIGNATURE_FORMS = [`\n\n${SIGNATURE}`, `\n${SIGNATURE}`, SIGNATURE];
+
+export function stripOnomeoSignature(text: string): string {
+ return text.replace(SIGNATURE_TAIL, '');
+}
+
+/** Length of the longest suffix of `text` that could still grow into the
+ * signature, so a stream holds back only what might be branding. */
+function heldSuffixLength(text: string): number {
+ let held = 0;
+ for (const form of SIGNATURE_FORMS) {
+ for (let n = Math.min(form.length, text.length); n > held; n--) {
+ if (form.startsWith(text.slice(text.length - n))) { held = n; break; }
+ }
+ }
+ return held;
+}
+
+/**
+ * onomeo (#1460): an OpenAI-compatible gateway whose free models share one
+ * call-counted allowance — 30 calls per 5-hour window per account, with a
+ * site-wide pool and a `too_fast` per-minute guard on top. Model rows are
+ * published only through the signed catalog; nothing here enrolls models.
+ *
+ * Error vocabulary (from https://onomeo.com/integrations):
+ * - 401 `bad_key` — the only authentication verdict; invalid.
+ * - 403 `account_quota` / `network_quota` and 429 `site_busy` / `too_fast` —
+ * quota and throttle answers on a VALID key. Treating 403 as an invalid key
+ * (the base `validationResult` rule) would auto-disable a good key the first
+ * time its 5-hour calls run out, so those statuses stay inconclusive here.
+ */
+export class OnomeoProvider extends OpenAICompatProvider {
+ constructor() {
+ // GET /v1/models is the keyed endpoint: anonymous and bad-key callers both
+ // get 401 (verified live), so it is a real credential probe.
+ super({ platform: 'onomeo', name: 'onomeo', baseUrl: ONOMEO_BASE_URL, validateUrl: `${ONOMEO_BASE_URL}/models` });
+ }
+
+ protected override async validationResult(response: Response): Promise<KeyValidationResult> {
+ if (response.status === 401) return super.validationResult(response);
+ // 403/429 are quota/throttle verdicts on a valid key (see class docs), and
+ // every other failure is an outage — all inconclusive, none key-fatal.
+ if (!response.ok) throw providerHttpError(response, 'onomeo key validation is temporarily inconclusive');
+ const body = await response.json().catch(() => null) as { data?: unknown; error?: unknown } | null;
+ if (!Array.isArray(body?.data) || body?.error) {
+ throw Object.assign(new Error('onomeo returned an invalid model list'), { status: 502 });
+ }
+ return true;
+ }
+
+ 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);
+ for (const choice of response.choices ?? []) {
+ if (typeof choice.message?.content === 'string') {
+ choice.message.content = stripOnomeoSignature(choice.message.content);
+ }
+ }
+ return response;
+ }
+
+ override async *streamChatCompletion(
+ apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext,
+ ): AsyncGenerator<ChatCompletionChunk> {
+ // Text that might be the start of the signature is held back until the
+ // next delta settles it; a signature at the end of the stream is dropped.
+ let held = '';
+ let lastChunk: ChatCompletionChunk | null = null;
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ lastChunk = chunk;
+ const delta = chunk.choices?.[0]?.delta;
+ if (typeof delta?.content !== 'string') {
+ if (held && chunk.choices?.[0]?.finish_reason) {
+ const tail = stripOnomeoSignature(held);
+ held = '';
+ if (tail && delta) delta.content = tail;
+ }
+ yield chunk;
+ continue;
+ }
+ const hadText = delta.content.length > 0;
+ let text = held + delta.content;
+ if (text.trimEnd().endsWith(SIGNATURE)) text = stripOnomeoSignature(text);
+ const keep = heldSuffixLength(text);
+ held = text.slice(text.length - keep);
+ delta.content = text.slice(0, text.length - keep);
+ // Skip only a delta whose text was entirely held back or stripped; role
+ // and finish chunks with empty content still pass through.
+ if (delta.content || !hadText || chunk.choices[0].finish_reason) yield chunk;
+ }
+ const tail = stripOnomeoSignature(held);
+ if (tail && lastChunk) {
+ yield {
+ ...lastChunk,
+ choices: [{ index: 0, delta: { content: tail }, finish_reason: null }],
+ } as ChatCompletionChunk;
+ }
+ }
+}
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index 2798b1fd..a096836c 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -64,6 +64,7 @@ const PLATFORMS = [
'moondream',
'beatapi',
'apinex',
+ 'onomeo',
'serpsearch',
'freeai',
'google', 'groq', 'cerebras', 'sail', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare', 'bai', 'radeon', 'nvidia', 'mistral',
diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.ts
index 6038ba87..d5df50d5 100644
--- a/server/src/services/provider-quota.ts
+++ b/server/src/services/provider-quota.ts
@@ -119,6 +119,9 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | null
if (platform === 'aclide') return 'aclide::monthly-credit';
if (platform === 'speka') return 'speka::monthly-credit';
if (platform === 'apinex') return 'apinex::daily-free';
+ // onomeo: one 30-calls/5-hour account allowance across every free model,
+ // so one pool (issue #1460).
+ if (platform === 'onomeo') return 'onomeo::five-hour-free';
if (platform === 'plugsky') return 'plugsky::fair-use';
if (platform === 'inferbase') return 'inferbase::managed-free';
if (platform === 'simplellm') return 'simplellm::free';
@@ -182,6 +185,7 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | null
function isSharedPool(platform: Platform): boolean {
if (platform === 'apinex') return true;
+ if (platform === 'onomeo') return true;
if (platform === 'aclide') return true;
if (platform === 'speka') return true;
if (platform === 'plugsky') return true;
diff --git a/shared/types.ts b/shared/types.ts
index ce70df27..c1c2cda8 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -76,6 +76,9 @@ export type Platform =
| 'beatapi'
// Free-category chat and decisions share one weighted daily allowance.
| 'apinex'
+ // OpenAI-compatible gateway; free models share a 30-calls/5-hour account
+ // allowance on top of a site-wide pool (issue #1460).
+ | 'onomeo'
// Ongoing free research API for chat and speech recognition; catalog only.
| 'typhoon'
// Permanent free chat aliases, shared fair-use quota; signed catalog only.