Production-ready OpenRouter multi-LLM API client for Payaar chatbot platform
npm install py-openrouter> Production-ready OpenRouter client for Node.js
> FREE models by default • Zero-cost dev • Smart fallbacks • Framework-ready
November 04, 2025 – v2.0.0 released
✅ All new requests are FREE by default
✅ DeepSeek & Qwen 2.5 auto-selected
✅ 100 % test coverage
---
``ts
import { OpenRouterClient } from 'py-openrouter';
const client = new OpenRouterClient({
apiKey: process.env.OPENROUTER_API_KEY!,
appName: 'My Awesome App', // Shows in OpenRouter dashboard
});
// ← No model specified → FREE model picked
const res = await client.sendMessage('Hello, world!');
console.log('Model:', res.model);
// → deepseek/deepseek-chat
console.log('Cost:', res.cost);
// → 0
`
> 📱 App Dashboard Tracking: To see your app in OpenRouter's dashboard:
>
> 1. Visit openrouter.ai/dashboard
> 2. Create an app with the same appName as your config
> 3. Your requests will show under that app instead of "unknown"
---
- 300+ models (GPT-4o, Claude 3.5, Gemini, Llama, DeepSeek, Qwen…)
- FREE-by-default routing (deepseek/deepseek-chat or qwen/qwen-2.5-72b-instruct)cost
- 4 smart strategies: • balanced • performance • capability
- Zero-cost dev mode – never pay while testing
- Streaming (SSE) with live token chunks
- Cost tracker + budget alerts
- Express / Fastify / NestJS adapters
- Full TypeScript + 42 files
---
`bash`
npm i py-openrouterpnpm / yarn
pnpm add py-openrouter
---
`ts
import { OpenRouterClient } from 'py-openrouter';
const client = new OpenRouterClient({
apiKey: process.env.OPENROUTER_API_KEY!,
});
// 1. Auto FREE
const r1 = await client.sendMessage('What is AI?');
console.log(r1.choices[0].message.content);
// 2. Pin a FREE coding model
const r2 = await client.sendMessage('Write a binary search', {
model: 'deepseek/deepseek-chat', // FREE
});
// 3. Pin a FREE multilingual model
const r3 = await client.sendMessage('Translate to Japanese', {
model: 'qwen/qwen-2.5-72b-instruct', // FREE
});
// 4. Production (paid) with FREE fallback
const r4 = await client.sendMessage('Critical report', {
model: 'anthropic/claude-3.5-sonnet',
modelSelection: { strategy: 'balanced', fallbackEnabled: true },
});
`
---
| Strategy | Code | Result | Reason |
| ---------------------- | -------------------------------- | ------------------------ | ---------------------------------------- |
| cost (cheapest) | strategy: 'cost' | deepseek/deepseek-chat | "FREE model: DeepSeek Chat" |strategy: 'balanced'
| balanced (default) | | deepseek or qwen | "Best FREE balanced model: score 100.50" |strategy: 'performance'
| performance | | fastest FREE | low latency |capabilities: { vision: true }
| capability | | vision model | auto-detect |
`ts`
await client.sendMessage('Describe this image', {
modelSelection: {
strategy: 'capability',
capabilities: { vision: true },
},
});
---
`ts
// Dev / Playground → $0
new OpenRouterClient({ apiKey })
// Coding tasks
model: 'deepseek/deepseek-chat'
// Multilingual
model: 'qwen/qwen-2.5-72b-instruct'
// Production (quality + safety)
model: 'anthropic/claude-3.5-sonnet',
fallbackEnabled: true // drops to FREE on outage
`
---
| Model | Cost | Speed | Quality | Best For |
| ------------------------- | ---- | --------- | ------- | ----------------------- |
| DeepSeek Chat | FREE | Fast | 8.8/10 | Coding, logic |
| Qwen 2.5 72B Instruct | FREE | Medium | 8.9/10 | Multilingual, reasoning |
| Llama 3.1 8B | FREE | Very Fast | 8.2/10 | Simple tasks |
| Claude 3.5 Sonnet | $3/M | Fast | 9.5/10 | Best overall |
| GPT-4o | $5/M | Fast | 9.4/10 | Complex tasks |
---
`ts`
for await (const chunk of client.streamMessage('Tell a 3-chapter story')) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
---
`ts
const client = new OpenRouterClient({
apiKey: process.env.OPENROUTER_API_KEY!,
budgets: { daily: 5, monthly: 100, alertThreshold: 0.8 },
});
client.on('budget:warning', (used, limit) => console.log(⚠️ ${used.toFixed(2)} / ${limit}));
const summary = client.getCostTracker().getSummary();
console.log(summary);
// → { totalCost: 0, totalRequests: 127, byModel: { ... } }
`
---
`ts
import express from 'express';
import { createExpressAdapter } from 'py-openrouter';
const app = express();
const adapter = createExpressAdapter(client);
app.post('/ai/chat', adapter.chatMiddleware());
app.post('/ai/stream', adapter.streamMiddleware());
app.get('/ai/costs', adapter.costsMiddleware());
app.listen(3000);
`
`ts`
fastify.register(createFastifyPlugin(client), { prefix: '/ai' });
`ts`
@Module({
providers: [{ provide: 'AI', useFactory: () => createNestJSService(client) }],
})
export class AiModule {}
---
`bash`
✅ TypeScript compilation: SUCCESS
✅ CJS build: 10 files
✅ ESM build: 10 files
✅ DTS build: 42 declaration files
✅ Default → deepseek/deepseek-chat (FREE)
✅ balanced → score 100.50
✅ cost → "FREE model: DeepSeek Chat"
✅ 8 examples working
---
- docs/FREE_MODE.md – new default behaviordocs/MODEL_SELECTION.md
-
-
-
-
---
`ts`
interface OpenRouterConfig {
apiKey: string;
baseURL?: string; // default: OpenRouter
appName?: string; // Shows in OpenRouter dashboard (requires app registration)
defaultModel?: string; // overridden by FREE default
timeout?: number; // 30s
maxRetries?: number; // 3
modelSelection?: {
strategy?: 'cost' | 'balanced' | 'performance' | 'capability';
fallbackEnabled?: boolean; // true
autoSelect?: boolean; // true
};
budgets?: {
daily?: number;
monthly?: number;
alertThreshold?: number; // 0.8
};
cache?: { enabled?: boolean; ttl?: number };
logging?: { level?: 'debug' | 'info' | 'warn' | 'error' };
}
---
- Chatbots – auto-FREE + paid fallback
- Code assistants – DeepSeek FREE
- Translation APIs – Qwen FREE
- Enterprise back-ends – Claude with FREE safety net
---
`ts`
// 3 lines → fully functional AI endpoint
const client = new OpenRouterClient({ apiKey: process.env.OPENROUTER_API_KEY! });
const ans = await client.sendMessage('Explain recursion in JS');
console.log(ans.choices[0].message.content);
---
MIT © Payaar Team
`bash`
git clone https://github.com/3bd0-shaban/payaar-core
pnpm install
pnpm test
See CONTRIBUTING.md
- npm: https://www.npmjs.com/package/py-openrouter
- GitHub: https://github.com/3bd0-shaban/payaar-core
- Issues: https://github.com/3bd0-shaban/payaar-core/issues
- OpenRouter FREE models: https://openrouter.ai/models?max_price=0
---
Start building AI for $0 today.
`ts``
await client.sendMessage('Your idea here');