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 catalog-managed LLMTR integration (#1366)
Tashfeen076315a855ed
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsxindex c9d737e3..ac1ee5c6 100644--- a/client/src/components/keys/shared.tsx+++ b/client/src/components/keys/shared.tsx@@ -29,6 +29,7 @@ export function GetKeyLink({ url }: { url: string }) {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: 'llmtr', label: 'LLMTR (daily free-model quotas)', url: 'https://llmtr.com' },{ 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 a9622536..38cc0ae4 100644--- a/client/src/lib/routing.ts+++ b/client/src/lib/routing.ts@@ -405,6 +405,7 @@ export const platformColors: Record<string, string> = {sail: '#0ea5e9',aclide: '#6366f1',speka: '#0d9488',+ llmtr: '#0f766e',moondream: '#6d5dfc',electronhub: '#6366f1',experiential: '#14b8a6',diff --git a/docs/providers/llmtr.md b/docs/providers/llmtr.mdnew file mode 100644index 00000000..3341ab97--- /dev/null+++ b/docs/providers/llmtr.md@@ -0,0 +1,46 @@+# LLMTR++LLMTR exposes an OpenAI-compatible API at `https://llmtr.com/v1`. Create an account,+verify email, and create a dashboard API key. Add it under **Keys → LLMTR**, or+import `LLMTR_API_KEY` from an environment file. Never commit the key.++Selected routes are zero-priced with daily or rolling quotas, not monthly cash+credits. The [migration guide](https://llmtr.com/docs/en/migration/openai-openrouter/)+documents free requests at zero balance. Account caps can vary; this integration+does not invent numeric quotas or make the whole provider roster free.+New accounts have a reduced free allowance that increases automatically once+the account is 24 hours old. A quota response observed during testing confirmed+this waiting option; no top-up is required. A streaming smoke test reached that+quota, so only non-streaming inference was live-verified in this publication.++## Catalog and release timing++Model rows are supplied only by the hosted signed catalog. There are no bundled+seeds or automatic discovery of LLMTR's paid models. Existing Premium-immediate+and Free-after-30-days release logic is unchanged.+Older app versions need an update to recognize the new provider.++Five routes returned matching model IDs and valid text completions on 2026-09-29:++- `qwen/qwen3.8-27b-free`+- `nvidia/nemotron-3-ultra-550b-a55b`+- `nvidia/nemotron-3-super-120b-a12b`+- `motif/motif-3`+- `inclusionai/ling-3.0-flash-fin`++These checks are not independent proof of the underlying model weights. Tools,+vision and context limits require separate verification before catalog flags are+enabled. Motif's [quota](https://llmtr.com/docs/en/gateway/motif-3/) replenishes each+request after 24 hours. Expiring promotions and EVREN BYOK routes are excluded.++## Authentication and errors++The public `/v1/models` endpoint cannot validate a key. Dashboard `/api/usage`+rejected API-key authentication during testing. Instead, key validation submits+a deliberately nonexistent model without generating tokens. Live valid/invalid+controls returned `404/model_not_found` and `401/auth_error`, respectively.+Other errors remain inconclusive; quota exhaustion does not mark a key invalid.++Chat and streaming use the shared OpenAI-compatible transport, preserve usage and+backoff, and reject mismatched response model IDs rather than silently accepting+substitutions. No automatic paid fallback is introduced by this adapter.diff --git a/server/src/__tests__/providers/llmtr.test.ts b/server/src/__tests__/providers/llmtr.test.tsnew file mode 100644index 00000000..8657649f--- /dev/null+++ b/server/src/__tests__/providers/llmtr.test.ts@@ -0,0 +1,89 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import type { ChatCompletionChunk } from '@freellmapi/shared/types.js';+import { LlmtrProvider } from '../../providers/llmtr.js';+import { getProvider } from '../../providers/index.js';+import { AUTH_JSON_PROVIDER_MAP, detectPlatform, parseKeysFromFile } from '../../lib/key-parser.js';+import { BUILTIN_DISCOVERY_PLATFORMS } from '../../services/builtin-model-discovery.js';++const model = 'qwen/qwen3.8-27b-free';+const completion = { id: 'llmtr-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 });+const sse = (returnedModel: string) => new Response([+ { id: 's', object: 'chat.completion.chunk', created: 1, model: returnedModel, choices: [{ index: 0, delta: { content: 'OK' }, finish_reason: 'stop' }] },+ { id: 's', object: 'chat.completion.chunk', created: 1, model: returnedModel, choices: [], usage: completion.usage },+].map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n', { headers: { 'Content-Type': 'text/event-stream' } });++describe('LLMTR provider', () => {+ afterEach(() => vi.restoreAllMocks());++ it('registers, imports keys and leaves model discovery to the signed catalog', () => {+ expect(getProvider('llmtr')).toBeInstanceOf(LlmtrProvider);+ expect(detectPlatform('LLMTR_')).toBe('llmtr');+ expect(AUTH_JSON_PROVIDER_MAP.llmtr).toBe('llmtr');+ expect(parseKeysFromFile('LLMTR_API_KEY=llmtr-test-not-a-real-key', 'keys.env').keys[0].platform).toBe('llmtr');+ expect(BUILTIN_DISCOVERY_PLATFORMS).not.toContain('llmtr');+ });++ it('preserves auth, exact model, options, usage and routing attribution', async () => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json(completion));+ const response = await getProvider('llmtr')!.chatCompletion('test-key', [{ role: 'user', content: 'OK' }], model,+ { max_tokens: 128, temperature: 0.2, response_format: { type: 'json_object' } });+ expect(fetch.mock.calls[0][0]).toBe('https://llmtr.com/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, max_tokens: 128, temperature: 0.2, response_format: { type: 'json_object' } });+ expect(response.choices[0].message.content).toBe('OK');+ expect(response.usage).toEqual(completion.usage);+ expect(response._routed_via).toEqual({ platform: 'llmtr', model });+ });++ it('streams content and usage with the requested model', async () => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(sse(model));+ const chunks: ChatCompletionChunk[] = [];+ for await (const chunk of getProvider('llmtr')!.streamChatCompletion('test-key', [], model)) chunks.push(chunk);+ expect(chunks.flatMap(c => c.choices).map(c => c.delta.content ?? '').join('')).toBe('OK');+ expect(chunks.some(c => c.usage?.total_tokens === 6)).toBe(true);+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body)).stream).toBe(true);+ });++ it.each(['other-model', undefined])('rejects mismatched or missing completion model (%s)', async returnedModel => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ ...completion, model: returnedModel }));+ await expect(getProvider('llmtr')!.chatCompletion('test-key', [], model)).rejects.toMatchObject({ status: 502 });+ });++ it('rejects a substituted stream before yielding its content', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue(sse('other-model'));+ const stream = getProvider('llmtr')!.streamChatCompletion('test-key', [], model);+ await expect(stream.next()).rejects.toMatchObject({ status: 502 });+ });++ it('validates via authenticated model resolution, not the public roster', async () => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'model_not_found', message: 'Model not found' } }, 404));+ await expect(getProvider('llmtr')!.validateKey('test-key')).resolves.toBe(true);+ expect(fetch).toHaveBeenCalledTimes(1);+ expect(fetch.mock.calls[0][0]).toBe('https://llmtr.com/v1/chat/completions');+ 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 invalid credentials (%s)', async status => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'auth_error', message: 'Invalid API key' } }, status));+ await expect(getProvider('llmtr')!.validateKey('bad-key')).resolves.toMatchObject({ valid: false });+ });++ it.each([200, 400, 402, 404, 429, 500])('keeps inconclusive validation errors inconclusive (%s)', async status => {+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'other' } }, status, { 'Retry-After': '17' }));+ await expect(getProvider('llmtr')!.validateKey('test-key')).rejects.toMatchObject({ status, retryAfterMs: 17_000 });+ });++ it('does not accept an HTML 404', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response('not JSON', { status: 404 }));+ await expect(getProvider('llmtr')!.validateKey('test-key')).rejects.toMatchObject({ status: 404 });+ });++ it.each([402, 429])('preserves upstream quota status and backoff without retry (%s)', async status => {+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { message: 'Quota exhausted' } }, status, { 'Retry-After': '30' }));+ await expect(getProvider('llmtr')!.chatCompletion('test-key', [], model)).rejects.toMatchObject({ status, retryAfterMs: 30_000 });+ expect(fetch).toHaveBeenCalledTimes(1);+ });+});diff --git a/server/src/__tests__/routes/keys-providers-checklist.test.ts b/server/src/__tests__/routes/keys-providers-checklist.test.tsindex 48b68979..77673d3c 100644--- a/server/src/__tests__/routes/keys-providers-checklist.test.ts+++ b/server/src/__tests__/routes/keys-providers-checklist.test.ts@@ -55,6 +55,8 @@ describe('GET /api/keys/providers — provider checklist (#543)', () => {expect(typeof groq.keyless).toBe('boolean');expect(body.providers.find((p: { platform: string }) => p.platform === 'moondream')).toMatchObject({ platform: 'moondream', name: 'Moondream', configured: false, keyless: false });+ expect(body.providers.find((p: { platform: string }) => p.platform === 'llmtr'))+ .toMatchObject({ platform: 'llmtr', name: 'LLMTR', configured: false, keyless: false });expect(body.summary).toEqual({total: body.providers.length,configured: 0,diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.tsindex 7eee2536..15e02c76 100644--- a/server/src/lib/key-parser.ts+++ b/server/src/lib/key-parser.ts@@ -46,6 +46,7 @@ export interface ParseResult {export const PREFIX_MAP: Record<string, string> = {ACLIDE_: 'aclide',SPEKA_: 'speka',+ LLMTR_: 'llmtr',MOONDREAM_: 'moondream',GOOGLE_: 'google',GEMINI_: 'google',@@ -142,6 +143,7 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {sail: 'sail',aclide: 'aclide',speka: 'speka',+ llmtr: 'llmtr',moondream: 'moondream','sail-research': 'sail',sailresearch: 'sail',diff --git a/server/src/providers/index.ts b/server/src/providers/index.tsindex 354145a7..4e055b3b 100644--- a/server/src/providers/index.ts+++ b/server/src/providers/index.ts@@ -11,6 +11,7 @@ import { ZhipuProvider } from './zhipu.js';import { SailProvider } from './sail.js';import { AclideProvider } from './aclide.js';import { SpekaProvider } from './speka.js';+import { LlmtrProvider } from './llmtr.js';import { MoondreamProvider } from './moondream.js';import { ElectronHubProvider } from './electronhub.js';import { ExperientialProvider } from './experiential.js';@@ -59,6 +60,7 @@ register(new OpenAICompatProvider({register(new SailProvider());register(new AclideProvider());register(new SpekaProvider());+register(new LlmtrProvider());register(new MoondreamProvider());// Free-plan grants are shared wallets, not free credits per model. Eligibilitydiff --git a/server/src/providers/llmtr.ts b/server/src/providers/llmtr.tsnew file mode 100644index 00000000..5f975de5--- /dev/null+++ b/server/src/providers/llmtr.ts@@ -0,0 +1,57 @@+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';+import { providerHttpError, type CompletionOptions, 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 LLMTR_BASE_URL = 'https://llmtr.com/v1';+const VALIDATION_MODEL = '__freellmapi_key_validation__';++function checkModel(requested: string, returned: string): void {+ if (returned !== requested) {+ throw Object.assign(new Error('LLMTR returned a different or missing model identity'), { status: 502 });+ }+}++/** Selected zero-priced routes have renewable daily/rolling quotas, not a+ * monthly cash grant. Only the signed catalog supplies model rows: the public+ * roster also contains paid models, expiring promotions and BYOK-only rows. */+export class LlmtrProvider extends OpenAICompatProvider {+ constructor() {+ super({ platform: 'llmtr', name: 'LLMTR', baseUrl: LLMTR_BASE_URL });+ }++ override async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult> {+ // /models is public; /api/usage expects a dashboard token. This nonexistent+ // model checks authentication without generating tokens: live controls on+ // 2026-09-29 returned 401/auth_error for an invalid key and+ // 404/model_not_found for the valid key. Do not accept generic 404s.+ const res = await this.fetchWithTimeout(`${LLMTR_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(this.platform, 30_000), { timeoutBounds: 'request' });+ recordQuotaObservationsFromResponse(res, { ...quotaContext, platform: this.platform, endpoint: 'key-validation' });+ if ([401, 403].includes(res.status)) return this.validationResult(res);+ if (res.status === 404) {+ const body = await res.clone().json().catch(() => null) as { error?: { type?: string } } | null;+ if (body?.error?.type === 'model_not_found') return true;+ }+ throw providerHttpError(res, 'LLMTR key validation is temporarily inconclusive');+ }++ 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.tsindex 47af0573..b0bacbd9 100644--- a/server/src/routes/keys.ts+++ b/server/src/routes/keys.ts@@ -44,6 +44,7 @@ export const keysRouter = Router();const PLATFORMS = ['aclide','speka',+ 'llmtr','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/shared/types.ts b/shared/types.tsindex cebb5b3d..44045391 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -72,6 +72,9 @@ export type Platform =| 'aclide'// OpenAI-compatible chat and embeddings; one shared $1 monthly allowance.| 'speka'+ // Selected zero-priced routes have daily/rolling quotas without a top-up;+ // signed catalog only. The public roster also includes paid/promotional IDs.+ | 'llmtr'// Hosted vision API: $5/workspace in recurring monthly credits, shared// across models. Signed catalog only; no bundled model seeds.| 'moondream'