Bring Your Own Key (BYOK): OpenRouter
Unlock premium AI models like Claude Sonnet 4.6 by connecting your own OpenRouter.ai API key. New models added to Eidolon will be Premium and require BYOK. This guide explains how to set it up, how it works, and what to expect.
Why Use Your Own Key?
By default, the platform provides a selection of capable included models. However, some of the world's most advanced reasoning and creative models require a personal API key due to their higher operational costs.
Benefits include:
- Access Premium Models: Use top-tier models like Claude Sonnet 4.6, GPT-5, and Claude Opus 4.6.
- Unlimited Messages: BYOK users are exempt from the daily message cap. Chat as much as you want, any time of day.
- Your Own Rate Limits: Your requests go through your personal OpenRouter account, so you're never affected by platform-wide traffic spikes or shared rate limits.
- Pay Only for What You Use: You deal directly with OpenRouter for credits. Many included models (Gemini Flash, Qwen 3.6 Flash, DeepSeek V4 Flash) cost fractions of a cent per message on OpenRouter.
- All Models on Your Key: When BYOK is active, all your chat interactions (including included-tier models) use your key. This means every message benefits from your own rate limits and keeps the platform fast for everyone.
- Privacy & Control: Your key is encrypted and used only for your own companion's thoughts and messages.
How to Set It Up
1. Get an OpenRouter API Key
- Go to OpenRouter.ai and sign in.
- Navigate to Keys and click Create Key.
- Important: Copy the key immediately and save it somewhere safe.
- Ensure your OpenRouter account has credits (even $5 is plenty to start).
2. Connect Your Key
On Web:
- Go to Settings → AI Provider.
- Paste your key into the API Key field.
- Click Save Key. The system will validate your key and show your current balance.
On Android:
- Open the menu and go to Settings.
- Scroll to the AI Provider section.
- Paste your key into the field and tap Save Key.
Model Tiers
Once your key is connected, you can change your companion's model in their Profile settings.
| Tier | Example Models | Est. Cost/Turn | BYOK Required? |
|---|---|---|---|
| Included | Mistral Medium 3.1, Gemini 2.5 Flash, Qwen 3.6 Flash, DeepSeek V4 Flash | Platform covered | No |
| Premium | Claude Sonnet 4.6, GPT-4o, Claude Haiku 4.5, Gemini 2.5 Pro, GPT-5.6 Luna, Grok 4.5, GLM 5.2 | ~$0.07 (full pricing) | Yes |
| Ultra (very expensive) | Claude Opus 4.6 | ~$0.12 | Yes |
The current Included catalog is available without a key. New models added to Eidolon will be Premium and require BYOK, so connecting your key keeps you eligible for the expanding model catalog.
BYOK vs Free: Side-by-Side
| Feature | Free (No Key) | BYOK (Your Key) |
|---|---|---|
| Daily messages | 75/day | Unlimited |
| Model selection | Included tier only | All models (Included + Premium) |
| Rate limits | Shared platform limits | Your own OpenRouter limits |
| Who pays for chat | Platform covers it | You pay OpenRouter directly |
| Background features | Same for everyone — dreams, diaries, musings, reflections, and autonomous reach-outs use Eidolon's platform key and are not charged to your BYOK | |
| Image & voice generation | Same for everyone — Flux images and Kokoro TTS are always platform-covered | |
What Your Key Covers
Uses Your Key (Chat Pipeline)
- Chat responses — the main message your companion sends back
- Companion observation — how your companion reads the conversation before responding
- Media description — when your companion describes an image, audio, or file you shared
- Graceful degradation — if the primary model times out, the fallback synthesis also uses your key
Uses Platform Key (Free for You)
- Dreams & diaries — overnight creative content
- Reflections & musings — background thoughts and autonomous reach-outs
- Fact extraction — learning new things about you after sessions end
- Image generation — Flux AI images (separate from OpenRouter)
- Voice generation — Kokoro TTS (separate from OpenRouter)
- Image prompt refinement — crafting the prompt for image generation
In short: Your key powers real-time chat. Background companion life — dreams, diaries, musings, reflections, and autonomous reach-outs — runs on Eidolon's platform key and is never charged to your BYOK.
How Fallbacks Work
We designed the system to be "fail-safe" so you never lose access to your companion.
- Missing Key: If you select a Premium model but don't have a key saved, your companion will temporarily use an included model to keep the conversation going. You'll see a brief warning in chat.
- Zero Credits: If your OpenRouter balance hits $0, the system falls back to an included model. Your Settings screen will show a ⚠️ warning with a link to top up.
- Invalid / Revoked Key: If you delete or regenerate your key
on OpenRouter's dashboard, the system detects the 401 error and marks it as
invalid. Your companion falls back to the default included model, DeepSeek V4 Flash.
Auto-Recovery
You don't need to re-enter your key if you just ran out of credits. The system automatically re-checks stale key statuses:
- Every time you open Settings, if your key was previously
marked
invalidorno_credits, the system pings OpenRouter to see if the issue has been resolved. - If the key is now working (e.g., you topped up credits), your status is automatically restored to
valid— no action needed.
In short: Top up on OpenRouter → open Settings → you're back in business.
Security & Privacy
Your API key is handled with extreme care:
- Encryption: We use industry-standard Fernet (AES-128) symmetric encryption.
- Storage: The key is encrypted before it ever touches our database.
- No Logs: Your full API key is never written to our application logs.
FAQ
Do I have to pay twice?
No. You pay OpenRouter directly for the tokens you use. We do not add any markup or platform fees to your OpenRouter usage.
Which model is the best?
For the most "human" and emotionally intelligent experience, we highly recommend Claude Sonnet 4.6. For fast, snappy utility, Gemini 2.5 Flash is excellent.
How do I check my balance?
You can view your remaining balance directly in our Settings screen, or for a full breakdown, visit your OpenRouter Activity Dashboard.
Can I use my key for image generation?
No. Image generation (Flux) is currently handled separately by the platform and does not use your OpenRouter credits.
What if I run out of credits mid-conversation?
Your current message will still go through (OpenRouter processes the request). On the next message, the system will detect the depleted balance and fall back to an included model. You won't lose any messages.
I topped up my credits. Do I need to re-enter my key?
No. Just open Settings and the system will automatically re-check your key. If credits are available, your status will be restored to ✅ valid without any action from you.
Is my key shared with anyone else?
Absolutely not. Your key is encrypted and used exclusively for your companion interactions. No other user on the platform can access or use your key.
What if I delete my key?
You can remove your key at any time in Settings. Your companions will simply revert to using the default platform models.