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.tsxindex 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.tsindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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. Eligibilitydiff --git a/server/src/providers/onomeo.ts b/server/src/providers/onomeo.tsnew file mode 100644index 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.tsindex 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.tsindex 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 | nullif (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 | nullfunction 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.tsindex 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.