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 Speka chat and embeddings (#1323)
Tashfeen2dc97a56f4e7
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsxindex 013276b2..0386e883 100644--- a/client/src/components/keys/shared.tsx+++ b/client/src/components/keys/shared.tsx@@ -27,6 +27,7 @@ export function GetKeyLink({ url }: { url: string }) {// routing treats the platform as configured.export const PLATFORMS: { value: Platform; label: string; url: string; keyless?: boolean }[] = [{ value: 'aclide', label: 'ACLIDE (shared monthly credits)', url: 'https://aclide.com/en/dashboard/api-keys' },+ { value: 'speka', label: 'Speka ($1 shared monthly credits)', url: 'https://speka.me/dashboard/keys' },{ value: 'moondream', label: 'Moondream ($5 shared monthly credits)', url: 'https://moondream.ai/c/cloud/api-keys' },{ value: 'google', label: 'Google AI Studio', url: 'https://aistudio.google.com/apikey' },{ value: 'groq', label: 'Groq', url: 'https://console.groq.com/keys' },diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.tsindex 952f3218..18efb560 100644--- a/client/src/lib/routing.ts+++ b/client/src/lib/routing.ts@@ -404,6 +404,7 @@ export const platformColors: Record<string, string> = {cerebras: '#8b5cf6',sail: '#0ea5e9',aclide: '#6366f1',+ speka: '#0d9488',moondream: '#6d5dfc',electronhub: '#6366f1',experiential: '#14b8a6',diff --git a/docs/providers/speka.md b/docs/providers/speka.mdnew file mode 100644index 00000000..34d75a25--- /dev/null+++ b/docs/providers/speka.md@@ -0,0 +1,29 @@+# Speka++Speka uses `https://speka.me/v1` with bearer authentication and OpenAI-compatible+chat completions (including streaming) and embeddings. Add a key in the Keys+page or import it as `SPEKA_API_KEY` in a key file; `speka` is also recognized+in imported auth JSON. This provider is not Speko.ai.++The Free plan advertises **$1 of model usage per month**, shared across models,+with no card required. It is not unlimited or a separate grant for each model.+The pricing page also describes paid overage: check the account's billing+settings rather than assuming all requests beyond the grant remain free.++Model rows are published through the signed hosted catalog only. Adding the+adapter or importing a key does not seed models or bypass the existing+Premium-now / Free-after-30-days release gate. Older app versions must update+to recognize the provider. Image generation is not enabled by this adapter.++Key validation uses a nonexistent model against the authenticated chat+endpoint. A controlled `400/model_not_found` confirms authentication without+running inference. `/models` is public and cannot validate a key. Authentication+errors are rejected; quota errors and outages remain inconclusive.++The embedding integration preserves the requested model and checks vector+dimensions through the existing embedding router. The separately tested+`nvidia/nemotron-3-embed-1b` route returned 2,048-dimensional vectors. Do not+assume interchangeability with another model merely because dimensions match.++Sources, checked 2026-09-24: [API reference](https://speka.me/docs),+[pricing](https://speka.me/pricing).diff --git a/server/src/__tests__/providers/speka.test.ts b/server/src/__tests__/providers/speka.test.tsnew file mode 100644index 00000000..271333dd--- /dev/null+++ b/server/src/__tests__/providers/speka.test.ts@@ -0,0 +1,83 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import type { ChatCompletionChunk } from '@freellmapi/shared/types.js';+import { SpekaProvider } from '../../providers/speka.js';+import { getProvider } from '../../providers/index.js';+import { AUTH_JSON_PROVIDER_MAP, detectPlatform, parseKeysFromFile } from '../../lib/key-parser.js';++const model = 'z-ai/glm-5.3';+const completion = {+ id: 'speka-test', object: 'chat.completion', created: 1, model,+ choices: [{ index: 0, message: { role: 'assistant', content: 'OK' }, finish_reason: 'stop' }],+ usage: { prompt_tokens: 4, completion_tokens: 2, total_tokens: 6 },+};+const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers });++describe('Speka provider', () => {+ afterEach(() => vi.restoreAllMocks());++ it('registers separately from Speko and supports key-file imports', () => {+ expect(getProvider('speka')).toBeInstanceOf(SpekaProvider);+ expect(detectPlatform('SPEKA_')).toBe('speka');+ expect(AUTH_JSON_PROVIDER_MAP.speka).toBe('speka');+ expect(parseKeysFromFile('SPEKA_API_KEY=sk-speka-live-test-not-a-real-key', 'keys.env').keys[0].platform).toBe('speka');+ });++ it('uses bearer auth and preserves the requested model, options, usage and attribution', async () => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json(completion));+ const result = await getProvider('speka')!.chatCompletion('test-key', [{ role: 'user', content: 'Reply OK' }], model, {+ max_tokens: 128, temperature: 0.2, response_format: { type: 'json_object' },+ tools: [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }],+ });+ const [url, init] = fetch.mock.calls[0];+ expect(url).toBe('https://speka.me/v1/chat/completions');+ expect(new Headers(init?.headers).get('authorization')).toBe('Bearer test-key');+ expect(JSON.parse(String(init?.body)).stream).not.toBe(true);+ expect(JSON.parse(String(init?.body))).toMatchObject({ model, max_tokens: 128, temperature: 0.2,+ response_format: { type: 'json_object' }, tools: [{ function: { name: 'lookup' } }] });+ expect(result.usage).toEqual(completion.usage);+ expect(result.choices[0].message.content).toBe('OK');+ expect(result._routed_via).toEqual({ platform: 'speka', model });+ });++ it('streams OpenAI SSE and preserves usage', async () => {+ const chunks = [+ { id: 's', object: 'chat.completion.chunk', created: 1, model, choices: [{ index: 0, delta: { content: 'OK' }, finish_reason: null }] },+ { id: 's', object: 'chat.completion.chunk', created: 1, model, choices: [], usage: completion.usage },+ ];+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(new Response(chunks.map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n', { headers: { 'Content-Type': 'text/event-stream' } }));+ const out: ChatCompletionChunk[] = [];+ for await (const chunk of getProvider('speka')!.streamChatCompletion('test-key', [{ role: 'user', content: 'Hi' }], model)) out.push(chunk);+ expect(out.flatMap(c => c.choices).map(c => c.delta.content ?? '').join('')).toBe('OK');+ expect(out.some(c => c.usage?.total_tokens === 6)).toBe(true);+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body)).stream).toBe(true);+ });++ it('validates through authenticated model resolution, never the public model list', async () => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'model_not_found', code: 400 } }, 400));+ await expect(getProvider('speka')!.validateKey('test-key')).resolves.toBe(true);+ expect(fetch).toHaveBeenCalledTimes(1);+ expect(fetch.mock.calls[0][0]).toBe('https://speka.me/v1/chat/completions');+ expect(new Headers(fetch.mock.calls[0][1]?.headers).get('authorization')).toBe('Bearer test-key');+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toMatchObject({ model: '__freellmapi_key_validation__', max_tokens: 1, stream: false });+ });++ it.each([401, 403])('rejects authentication errors (%s)', async status => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'authentication_error', message: 'Invalid API key' } }, status));+ await expect(getProvider('speka')!.validateKey('bad-key')).resolves.toMatchObject({ valid: false });+ });++ it.each([200, 400, 402, 429, 500])('does not accept an inconclusive key check (%s)', async status => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'other' } }, status, { 'Retry-After': '17' }));+ await expect(getProvider('speka')!.validateKey('test-key')).rejects.toMatchObject({ status, retryAfterMs: 17_000 });+ });++ it('does not accept a malformed validation response', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response('not JSON', { status: 400 }));+ await expect(getProvider('speka')!.validateKey('test-key')).rejects.toMatchObject({ status: 400 });+ });++ it.each([402, 429])('preserves exhausted-credit/rate-limit responses and Retry-After (%s)', async status => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { message: 'Allowance exhausted' } }, status, { 'Retry-After': '30' }));+ await expect(getProvider('speka')!.chatCompletion('test-key', [], model)).rejects.toMatchObject({ status, retryAfterMs: 30_000 });+ });+});diff --git a/server/src/__tests__/routes/keys.test.ts b/server/src/__tests__/routes/keys.test.tsindex dd5ca20e..4a2de5ce 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(['aclide', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare'])('accepts a %s key without seeding gated model rows', async platform => {+ it.each(['aclide', 'speka', '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/catalog-sync.test.ts b/server/src/__tests__/services/catalog-sync.test.tsindex c3f41e31..39af3ee1 100644--- a/server/src/__tests__/services/catalog-sync.test.ts+++ b/server/src/__tests__/services/catalog-sync.test.ts@@ -254,6 +254,20 @@ describe('applyCatalog', () => {expect(getDb().prepare("SELECT model_id, modality, enabled FROM media_models WHERE platform = 'speechify'").get()).toEqual({ model_id: 'test-simba', modality: 'audio', enabled: 1 });});+ it('adds Speka chat and embedding rows only when the signed catalog supplies them', () => {+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'speka'").get()).toBeUndefined();+ expect(getDb().prepare("SELECT id FROM embedding_models WHERE platform = 'speka'").get()).toBeUndefined();+ const catalog = catalogOf([...existingAsCatalogModels(), baseModel({ platform: 'speka', modelId: 'z-ai/glm-5.3' })]);+ catalog.embeddings = [...existingAsCatalogEmbeddings(), {+ family: 'nemotron-3-embed-1b-speka', platform: 'speka', modelId: 'nvidia/nemotron-3-embed-1b',+ displayName: 'Nemotron 3 Embed 1B (Speka)', dimensions: 2048, maxInputTokens: 8192,+ priority: 1, enabled: true, quotaLabel: '$1/month shared',+ }];+ applyCatalog(getDb(), catalog);+ expect(getDb().prepare("SELECT enabled FROM models WHERE platform = 'speka'").get()).toEqual({ enabled: 1 });+ expect(getDb().prepare("SELECT dimensions, enabled FROM embedding_models WHERE platform = 'speka'").get()).toEqual({ dimensions: 2048, enabled: 1 });+ });+it('applies the full embedding snapshot and retires a replaced provider id', () => {const embeddings = existingAsCatalogEmbeddings();const openRouter = embeddings.find(diff --git a/server/src/__tests__/services/embeddings.test.ts b/server/src/__tests__/services/embeddings.test.tsindex 390c27a0..2c2b40f8 100644--- a/server/src/__tests__/services/embeddings.test.ts+++ b/server/src/__tests__/services/embeddings.test.ts@@ -121,6 +121,33 @@ describe('embeddings service', () => {});describe('runEmbeddings', () => {+ it('routes catalog-managed Speka embeddings with bearer auth, sorted vectors and usage', async () => {+ addKey('speka');+ getDb().prepare(`INSERT INTO embedding_models+ (family, platform, model_id, display_name, dimensions, priority, enabled, quota_label)+ VALUES ('speka-test-embed', 'speka', 'nvidia/nemotron-3-embed-1b', 'Speka embedding', 2, 1, 1, '$1/month shared')`).run();+ const fetchMock = mockFetch(async () => new Response(JSON.stringify({+ data: [{ index: 1, embedding: [0.3, 0.4] }, { index: 0, embedding: [0.1, 0.2] }], usage: { prompt_tokens: 7 },+ })));+ const result = await runEmbeddings('speka-test-embed', ['first', 'second']);+ expect(fetchMock.mock.calls[0][0]).toBe('https://speka.me/v1/embeddings');+ expect(new Headers(fetchMock.mock.calls[0][1]?.headers).get('authorization')).toBe('Bearer speka-test-key');+ expect(JSON.parse(String(fetchMock.mock.calls[0][1]?.body))).toEqual({+ model: 'nvidia/nemotron-3-embed-1b', input: ['first', 'second'], encoding_format: 'float',+ });+ expect(result).toMatchObject({ platform: 'speka', modelId: 'nvidia/nemotron-3-embed-1b', dimensions: 2,+ inputTokens: 7, vectors: [[0.1, 0.2], [0.3, 0.4]] });+ });++ it('retains Speka embedding rate-limit backoff', async () => {+ addKey('speka');+ getDb().prepare(`INSERT INTO embedding_models+ (family, platform, model_id, display_name, dimensions, priority, enabled, quota_label)+ VALUES ('speka-test-embed', 'speka', 'nvidia/nemotron-3-embed-1b', 'Speka embedding', 2, 1, 1, '$1/month shared')`).run();+ mockFetch(async () => new Response('rate limited', { status: 429, headers: { 'Retry-After': '20' } }));+ await expect(runEmbeddings('speka-test-embed', ['hello'])).rejects.toMatchObject({ status: 429, retryAfterMs: 20_000 });+ });+it('rejects unknown models with a 400', async () => {await expect(runEmbeddings('no-such-model', ['hi'])).rejects.toMatchObject({ status: 400 });});diff --git a/server/src/__tests__/services/provider-quota.test.ts b/server/src/__tests__/services/provider-quota.test.tsindex 8ddf27de..d640ed3e 100644--- a/server/src/__tests__/services/provider-quota.test.ts+++ b/server/src/__tests__/services/provider-quota.test.ts@@ -51,6 +51,7 @@ describe('provider-quota: pool inference', () => {expect(inferQuotaPoolKey('septor', 'minimax-m2.5-free')).toBe('septor::daily-free');for (const model of ['first-model', 'another-model']) {expect(inferQuotaPoolKey('aclide', model)).toBe('aclide::monthly-credit');+ expect(inferQuotaPoolKey('speka', model)).toBe('speka::monthly-credit');expect(inferQuotaPoolKey('clod', model)).toBe('clod::daily-free');expect(inferQuotaPoolKey('blaze', model)).toBe('blaze::daily-free');expect(inferQuotaPoolKey('speechify', model)).toBe('speechify::monthly-characters');diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.tsindex 353bbf4b..7eee2536 100644--- a/server/src/lib/key-parser.ts+++ b/server/src/lib/key-parser.ts@@ -45,6 +45,7 @@ export interface ParseResult {export const PREFIX_MAP: Record<string, string> = {ACLIDE_: 'aclide',+ SPEKA_: 'speka',MOONDREAM_: 'moondream',GOOGLE_: 'google',GEMINI_: 'google',@@ -140,6 +141,7 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {groq: 'groq',sail: 'sail',aclide: 'aclide',+ speka: 'speka',moondream: 'moondream','sail-research': 'sail',sailresearch: 'sail',diff --git a/server/src/providers/index.ts b/server/src/providers/index.tsindex f099a587..354145a7 100644--- a/server/src/providers/index.ts+++ b/server/src/providers/index.ts@@ -10,6 +10,7 @@ import { PollinationsProvider } from './pollinations.js';import { ZhipuProvider } from './zhipu.js';import { SailProvider } from './sail.js';import { AclideProvider } from './aclide.js';+import { SpekaProvider } from './speka.js';import { MoondreamProvider } from './moondream.js';import { ElectronHubProvider } from './electronhub.js';import { ExperientialProvider } from './experiential.js';@@ -57,6 +58,7 @@ register(new OpenAICompatProvider({// stay in Oracle so the existing Premium-now / Free-after-30-days gate applies.register(new SailProvider());register(new AclideProvider());+register(new SpekaProvider());register(new MoondreamProvider());// Free-plan grants are shared wallets, not free credits per model. Eligibilitydiff --git a/server/src/providers/speka.ts b/server/src/providers/speka.tsnew file mode 100644index 00000000..a234a26b--- /dev/null+++ b/server/src/providers/speka.ts@@ -0,0 +1,37 @@+import { providerHttpError, type KeyValidationResult } from './base.js';+import { OpenAICompatProvider } from './openai-compat.js';+import { providerTimeoutMs } from '../lib/provider-timeout.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';++export const SPEKA_BASE_URL = 'https://speka.me/v1';+const VALIDATION_MODEL = '__freellmapi_key_validation__';++/** OpenAI-compatible chat; model rows are delivered only by the signed catalog.+ * Free's $1/month is shared across chat and embeddings, not a per-model grant.+ * Docs: https://speka.me/docs and https://speka.me/pricing. */+export class SpekaProvider extends OpenAICompatProvider {+ constructor() {+ super({ platform: 'speka', name: 'Speka', baseUrl: SPEKA_BASE_URL });+ }++ override async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult> {+ // /models is public, so a 200 there does not validate a key. Speka checks+ // authentication before resolving a model: this deliberately nonexistent+ // model returns 400/model_not_found only after auth, without generating+ // tokens. Verified against both a valid key and an invalid-key control.+ const res = await this.fetchWithTimeout(`${SPEKA_BASE_URL}/chat/completions`, {+ method: 'POST',+ headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },+ body: JSON.stringify({ model: VALIDATION_MODEL, messages: [{ role: 'user', content: 'key validation' }], max_tokens: 1, stream: false }),+ }, providerTimeoutMs('speka', 30_000), { timeoutBounds: 'request' });+ recordQuotaObservationsFromResponse(res, { ...quotaContext, platform: 'speka', endpoint: 'key-validation' });+ if ([401, 403].includes(res.status)) return this.validationResult(res);+ if (res.status === 400) {+ const body = await res.clone().json().catch(() => null) as { error?: { type?: string } } | null;+ if (body?.error?.type === 'model_not_found') return true;+ }+ // Rate limits, exhausted allowances, malformed responses and outages are+ // inconclusive, not proof that a key is valid or invalid.+ throw providerHttpError(res, 'Speka key validation is temporarily inconclusive');+ }+}diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.tsindex 68ecba82..d2273220 100644--- a/server/src/routes/keys.ts+++ b/server/src/routes/keys.ts@@ -31,6 +31,7 @@ export const keysRouter = Router();// SambaNova was dropped in V23 (free tier permanently retired).const PLATFORMS = ['aclide',+ 'speka','moondream','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',diff --git a/server/src/services/embeddings.ts b/server/src/services/embeddings.tsindex a1e35649..618527cc 100644--- a/server/src/services/embeddings.ts+++ b/server/src/services/embeddings.ts@@ -16,6 +16,7 @@ import { reserveProviderCredential } from './provider-credential.js';import { proxyFetch } from '../lib/proxy.js';import { customEndpointKeyIds } from './custom-endpoint.js';import type { Db } from '../db/types.js';+import { SPEKA_BASE_URL } from '../providers/speka.js';export interface EmbeddingModelRow {id: number;@@ -112,6 +113,7 @@ export const EMBEDDING_PLATFORMS = new Set(['huggingface','cohere','sealion',+ 'speka',]);interface ProviderCallResult {@@ -260,6 +262,8 @@ async function callProvider(row: EmbeddingModelRow, credential: ProviderCredentireturn openAiStyleEmbed('https://models.github.ai/inference/embeddings', row.platform, key, row.model_id, inputs, {}, dimensions);case 'sealion':return openAiStyleEmbed('https://api.sea-lion.ai/v1/embeddings', row.platform, key, row.model_id, inputs, {}, dimensions);+ case 'speka':+ return openAiStyleEmbed(`${SPEKA_BASE_URL}/embeddings`, row.platform, key, row.model_id, inputs, { encoding_format: 'float' }, dimensions);case 'cloudflare': {// Key is stored as "account_id:token".const sep = key.indexOf(':');diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.tsindex 6b125fec..fe7d9fb2 100644--- a/server/src/services/provider-quota.ts+++ b/server/src/services/provider-quota.ts@@ -117,6 +117,7 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | nullif (platform === 'cerebras') return 'cerebras::shared';if (platform === 'sail') return 'sail::monthly-credit';if (platform === 'aclide') return 'aclide::monthly-credit';+ if (platform === 'speka') return 'speka::monthly-credit';if (platform === 'electronhub') return normalizedModelId.endsWith(':free') ? 'electronhub::daily-free' : 'electronhub::weekly-credit';if (platform === 'experiential') return 'experiential::monthly-credit';if (platform === 'router9') return 'router9::monthly-credit';@@ -178,6 +179,7 @@ export function inferPoolForPlatform(platform: Platform, modelId?: string | nullfunction isSharedPool(platform: Platform): boolean {if (platform === 'aclide') return true;+ if (platform === 'speka') 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.tsindex e4bc2a86..c5672fac 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -70,6 +70,8 @@ export type Platform =| 'sail'// Responses-only gateway; a shared monthly free allowance, not per model.| 'aclide'+ // OpenAI-compatible chat and embeddings; one shared $1 monthly allowance.+ | 'speka'// Hosted vision API: $5/workspace in recurring monthly credits, shared// across models. Signed catalog only; no bundled model seeds.| 'moondream'