OpenRouter and BYOK - ONA.UNO Docs

ONA.UNO uses a “Bring Your Own Key” (BYOK) model for cloud AI features. This means you create your own account with an AI provider and use your own API key — ONA.UNO doesn’t bundle AI services into its price or act as a middleman.

This document explains how it works and why we chose this approach.

---

What is OpenRouter?

OpenRouter is a unified API service that provides access to AI models from multiple providers — Google (Gemini), Alibaba (Qwen), xAI (Grok), and many others — through a single account and API key.

Instead of creating separate accounts with Google, Alibaba, and xAI, you create one OpenRouter account and access all their models through one interface with one balance.

Why ONA.UNO Uses OpenRouter

Access to multiple providers. ONA.UNO uses different models for different tasks: Qwen for embeddings, Gemini for pipeline processing, and your choice of Gemini or Grok for chat. OpenRouter lets you access all of these with a single API key.

Near-cost pricing. OpenRouter charges close to what the underlying providers charge, with minimal markup. You’re paying for actual AI compute, not a reseller premium.

No vendor lock-in. If a better model becomes available from a new provider, OpenRouter typically adds support quickly. ONA.UNO can offer new models without requiring you to create new accounts.

Proven reliability. OpenRouter handles millions of API requests and provides consistent uptime. It’s a mature service used by many applications.

---

What is BYOK?

BYOK stands for “Bring Your Own Key.” It sounds technical, but the concept is simple: instead of ONA.UNO charging you for AI usage, you create your own account with an AI service and pay them directly.

Think of it like this: ONA.UNO is the kitchen, but you bring your own ingredients. The AI provider (accessed through OpenRouter) supplies the ingredients — ONA.UNO just does the cooking.

How It Works in Practice

1. You create a free account at OpenRouter (takes 2 minutes)
2. You add some credit — as little as $5 to start
3. You copy your API key into ONA.UNO’s settings
4. Done. ONA.UNO can now use cloud AI features.

That’s the entire setup. No subscription forms, no recurring billing to manage, no cancellation hassles.

What You’re Actually Paying For

When ONA.UNO processes your content with cloud AI, it sends requests to AI providers like Google (Gemini) or Alibaba (Qwen). These providers charge tiny amounts per request — fractions of a cent for most operations.

With BYOK, you pay:

• The actual AI cost — what Google, Alibaba, or xAI charges for processing
• A small routing fee — OpenRouter adds a minimal surcharge for providing unified access

That’s it. No markup from ONA.UNO, no “AI credits” with inflated pricing, no mystery fees.

Complete Cost Visibility

You always know exactly what you’re spending:

In ONA.UNO: The status bar shows your current monthly spending and the cost of your last request — updated in real time. No surprises at the end of the month.

In OpenRouter: Your dashboard shows precise, up-to-the-second spending for each API key. You can see exactly which requests cost what.

No Risk of Overspending

Worried about runaway costs? You’re fully protected:

• Set a spending limit on your API key. Once reached, the key stops working — period. You decide the maximum, and it’s a hard cap.
• Credits don’t auto-renew by default. When your balance runs out, requests simply fail. You add more credits when you’re ready.
• No surprise charges. Unless you explicitly enable auto-recharge (which is off by default), nothing happens automatically.

You’re always in control.

Is This Complicated?

No. Creating an OpenRouter account takes a few minutes. The API key is just a string of characters you copy once and paste into ONA.UNO’s settings.

---

Why BYOK?

Given that BYOK requires a small setup step, why did we choose this approach?

Transparency

You see exactly what AI processing costs. There’s no markup hidden in ONA.UNO’s price, no “AI credits” with unclear value. When you spend $1 on OpenRouter, you get $1 worth of AI processing at published rates.

No Recurring Fees

Many apps charge monthly subscriptions that assume heavy AI usage. If you use the app lightly one month, you still pay the full subscription. With BYOK, you pay only for what you use. Take a month off? Pay nothing.

Your Relationship, Your Data

Your API requests go directly from your Mac to OpenRouter to the AI provider. ONA.UNO doesn’t proxy your requests through our servers. We don’t see your content, your usage patterns, or your costs. Your relationship is directly with OpenRouter and the AI providers.

Flexibility

You can use the same OpenRouter account with other applications. Your credits aren’t locked to ONA.UNO — they work anywhere OpenRouter is supported.

---

Getting Started with OpenRouter

1. Create an Account

Visit openrouter.ai and create an account. You can sign up with email or use Google/GitHub authentication.

2. Add Credits

Navigate to your account settings and add credits. The minimum is $5 USD. Credits are added to your balance immediately and never expire.

Payment methods include credit cards and cryptocurrency. OpenRouter doesn’t store your payment details — they use Stripe for processing.

3. Generate an API Key

In your OpenRouter dashboard, go to Keys and create a new API key. Give it a descriptive name like “ONA.UNO” so you can identify it later.

Important: You can set a spending limit when creating the key. This is a hard cap — once reached, the key stops working until you raise the limit. This prevents any possibility of runaway costs.

4. Add the Key to ONA.UNO

In ONA.UNO, go to Settings → AI → Remote Models and paste your API key. ONA.UNO will validate it and show your current balance.

That’s it. ONA.UNO can now use cloud AI features.

---

Cost Structure

Pay-As-You-Go

OpenRouter is purely pay-as-you-go. There’s no subscription, no monthly minimum, no recurring charges. Add credits when you need them, use them over time.

Credits Never Expire

Unlike some services that expire unused credits, OpenRouter credits remain in your account indefinitely. Add $20 and use it over six months — no problem.

Per-Token Pricing

AI costs are measured in tokens (roughly 4 characters or 0.75 words). Each model has published input and output token prices. Embeddings are charged per token processed. Chat responses are charged for both the context (input) and the response (output).

You don’t need to understand token math — just know that longer content costs more to process, and the prices are published and predictable.

---

Real-World Costs

Here’s what typical ONA.UNO usage actually costs:

Initial Library Processing

When you first add sources to ONA.UNO, every item needs embeddings (for search) plus summaries, titles, and tags. This is the largest one-time cost.

Library Size	Estimated Cost
10,000 items	$3–4
25,000 items	$8–10

The actual cost depends on content length — a library of short notes costs less than one full of long documents.

Ongoing Daily Use

After initial processing, costs come from:

• New items: $0.04–0.06 per 100 items
• Chat conversations: $0.01–0.15 per conversation, depending on length
• Full summaries: $0.003–0.006 per summary

Rough estimate: Active daily use (adding 30–50 items, regular chat and summaries) runs $2–5 per month.

Inactive Periods

If you don’t use ONA.UNO’s cloud features, you pay nothing. Your credits sit in your account until you need them.

For detailed cost breakdowns, see LLM Cost (OpenRouter).

---

Spending Limits

OpenRouter provides robust cost control through API key limits.

Setting a Limit

When you create an API key (or edit an existing one), you can set a credit limit. This is the maximum amount that key can spend — ever, across all time.

For example, set a $10 limit. Once total spending reaches $10, the key stops working. You’ll need to either add more credits and raise the limit, or create a new key.

Why This Matters

Spending limits give you complete control:

• No surprise bills. If you set a $20 limit, you cannot spend more than $20.
• Budget enforcement. Set a limit that matches your comfort level.
• Peace of mind. Even if something goes wrong (a bug, unexpected usage), spending stops at your limit.

Recommended Approach

Start with a conservative limit ($10–20) while you learn your usage patterns. After a month, you’ll have a sense of what ONA.UNO costs for your workflow. Adjust the limit accordingly.

---

Model Selection in ONA.UNO

ONA.UNO uses specific models for different tasks:

Pipeline Processing (Automatic)

Task	Model	Notes
Embeddings	Qwen3 Embedding 8B	Creates semantic vectors for search
Summaries	Gemini 2.5 Flash Lite	Generates bullet-point summaries
Titles	Gemini 2.5 Flash Lite	Creates descriptive titles
Tags	Gemini 2.5 Flash Lite	Suggests relevant tags

These models are selected for their balance of quality, speed, and cost. You don’t choose them — ONA.UNO uses them automatically.

Chat and Full Summaries (Your Choice)

For interactive features, you choose between model families:

Google Gemini 2.5 Flash

• Excellent reasoning and fast responses
• Large context window
• Available in Balanced (faster) and High (deeper reasoning) variants

Grok 4.1 Fast

• Massive context capacity (up to 2 million tokens)
• Good for conversations spanning many documents
• Available in Balanced and High variants

Switch between models anytime in the chat interface. Different models suit different tasks — experiment to find what works for your questions.

For a deeper dive into how ONA.UNO’s AI pipeline works — including why specific models were chosen and how they work together — see Leveraging AI.

---

Mixed Mode and API Keys

If you use Mixed mode, the pipeline stages (embeddings, summaries, titles, tags) run locally on your Mac — no API key needed for those operations.

However, chat and full summaries require an API key even in Mixed mode. These features use cloud models because local models can’t deliver acceptable quality for interactive conversations and comprehensive summaries.

Also, AI → Consolidate AI Tags… requires an OpenRouter API key in both Mixed and Online modes, because clustering uses a remote model.

You can use Mixed mode without an API key to explore ONA.UNO’s timeline and search. But to unlock chat and summaries, you’ll need an OpenRouter account.

---

Troubleshooting

When something goes wrong, ONA.UNO shows an error with an HTTP status code from OpenRouter. Here’s what the common codes mean:

Status 401 — Authentication Failed

Your API key isn’t working.

• Check that you copied the entire key (they’re long strings)
• Ensure there are no extra spaces before or after the key
• Verify the key is active in your OpenRouter dashboard

Status 402 — Payment Required

Your OpenRouter balance is empty or your key has hit its spending limit.

• Add more credits at openrouter.ai
• Or raise the spending limit on your API key

Status 429 — Rate Limited

OpenRouter or the underlying provider is temporarily limiting requests. This usually resolves within minutes. If it persists, check OpenRouter’s status page.

Status 500/502/503 — Server Error

OpenRouter or the AI provider is having issues. Wait a few minutes and try again. Check OpenRouter’s status page for outage information.

”OpenRouter API key missing”

ONA.UNO’s status bar shows this when no API key is configured. Go to Settings → AI → Remote Models and add your key.

One Feature Works But Another Doesn’t

Different features use different models. If chat works but pipeline processing doesn’t (or vice versa):

• A specific model may be temporarily unavailable — check OpenRouter’s status page
• Try switching chat models to see if the issue is model-specific

---

Privacy Considerations

When you use cloud AI features:

1. Your content travels from your Mac → OpenRouter → AI Provider (Google, Alibaba, or xAI)
2. OpenRouter routes the request but doesn’t store your content beyond processing
3. The AI provider processes your content according to their privacy policy
4. ONA.UNO never sees your content — the connection is direct from your Mac

For detailed information about data handling, see Privacy FAQ.

---

Summary

Aspect	Details
What is BYOK	You create your own OpenRouter account and API key
Why BYOK	Transparency, no subscriptions, direct relationship with provider
Minimum to start	$5 USD (credits never expire)
Typical costs	~$3 to process 10,000 items; $2–5/month ongoing
Cost control	Set hard spending limits on API keys
Required for	Online mode (all features), Mixed mode (chat, full summaries, and AI tag consolidation)

Questions not covered here? Check the other FAQ topics or contact us.