Skip to content

2. API Key Setup Options

Jump to bottom
Jimmy Pautz edited this page Aug 26, 2026 · 6 revisions

API Key Setup & Entry Options

Setting up an API key gives the X-Ray plugin access to AI language models to analyze book text, track characters, build timelines, extract glossaries, and generate series summaries.

KOReader X-Ray provides 5 flexible ways to configure your API keys, designed specifically to eliminate tedious on-screen typing on E-Ink keyboards while offering strict privacy and offline options.

Quick Decision Guide

Method Best For E-Reader Typing? Cloud Server Involved? Speed
1. Phone / PC Cloud Relay (Recommended) All devices (Kindle, Kobo, Android, etc.) No Zero-Knowledge Relay 15 seconds
2. Local Wi-Fi (Offline LAN) Strict offline users (Android, Kobo, PocketBook) No 100% Offline LAN 20 seconds
3. xray_key.txt File Drop USB Cable / Calibre / File Manager No 100% Offline 30 seconds
4. xray_config.lua Config Power users & multi-device sync No 100% Offline 1 minute
5. On-Screen E-Reader Keyboard Quick manual entry / copy-paste Yes 100% Offline 1–2 minutes

Method 1: Phone / PC Cloud Relay (Recommended)

The easiest and fastest method. You scan a QR code with your phone or visit a webpage on your PC, paste your key in your web browser, and tap Send. Your e-reader receives, decrypts, and saves the key in real time.

[Phone/PC Browser] ──(AES/HMAC Encrypted Key)──► [Cloud Relay] ──► [E-Reader Decrypts & Saves]

Step-by-Step Instructions:

  1. On your e-reader, open any book.
  2. Go to Tools Menu (wrench) → X-Ray → Settings → AI Settings → API Keys & Providers → Set Key from Phone / PC ▸. (If this is your first time using X-Ray, simply select Option 1: Phone / PC from the welcome screen).
  3. A modal dialog will appear on your e-reader displaying a QR code, a short link (xray-setup.ultimatejimmy.workers.dev), and a 6-character Pairing Code (e.g. K9X2B4).
  4. On your phone or PC:
  5. On the web page:
    • Select your provider (Google Gemini, OpenAI, DeepSeek, Claude, or Custom API).
    • Paste your API key into the text field (use the integrated Paste button).
    • Tap Send Encrypted Key to E-Reader.
  6. Within 1–2 seconds, your e-reader will show a confirmation banner: [OK] API key for Google Gemini received and saved! and close the setup dialog automatically.

Note

Zero-Knowledge Privacy Guarantee: Cloud Relay uses client-side Web Crypto encryption. The random 256-bit encryption key is embedded inside the URL hash #secret (which web browsers never send to servers). The Cloudflare relay only sees scrambled ciphertext and cannot decrypt or read your API key.

Method 2: Local Wi-Fi (Offline LAN)

If you prefer not to use any external internet relay, you can send your key directly from your phone/PC to your e-reader over your home Wi-Fi network.

[Phone/PC Browser] ──(Direct LAN HTTP / Port 8088)──► [E-Reader Local Web Server]

Important

Supported Devices:

  • Supported: Android, Kobo, PocketBook, and Desktop/Emulators.
  • Kindle Devices (Not Supported): Amazon's Kindle OS firmware has a built-in firewall (iptables) that drops all unsolicited incoming network connections on non-standard ports. As a result, browser connections from your phone to the Kindle's local web server will time out. The plugin automatically detects Kindle devices and hides the Local Wi-Fi button. Kindle users should use Method 1: Cloud Relay (which uses outgoing polling permitted by Kindle OS) or Method 3: xray_key.txt file drop.

Step-by-Step Instructions:

  1. Ensure your e-reader and phone/PC are connected to the same Wi-Fi network.
  2. Launch the setup dialog on your e-reader (Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers → Set Key from Phone / PC).
  3. Tap the Local Wi-Fi (Offline LAN) button at the bottom of the dialog (available on supported devices).
  4. Your e-reader will start a temporary lightweight HTTP server and display:
    • A local QR code.
    • A direct IP link (e.g. http://192.168.1.45:8088).
  5. Scan the QR code or enter the http://... address in your phone or PC browser.
  6. Select your provider, paste your key, and tap Save to E-Reader.
  7. The key is transmitted directly over your local network. The local web server stops immediately upon receipt.

Method 3: xray_key.txt Text File Drop

Ideal when managing your device via USB cable, Calibre, or file transfer apps (like SSH, FTP, or Android file managers).

Step-by-Step Instructions:

  1. Connect your e-reader to your computer via USB.
  2. In the root KOReader folder (e.g. koreader/ on Kindle, .kobo/koreader/ on Kobo, or sdcard/koreader/ on Android), create a text file named xray_key.txt.
  3. Paste your API key into the file.

Supported File Formats:

Option A: Tagged Provider Lines (Configure multiple keys at once):

# My AI Keys for X-Ray
gemini = YourGeminiKeyHere
chatgpt = YourOpenAIKeyHere
deepseek = YourDeepSeekKeyHere
claude = YourClaudeKeyHere

# Optional Custom / OpenRouter configuration:
custom1_key = sk-or-YourOpenRouterKey
custom1_endpoint = https://openrouter.ai/api/v1/chat/completions
custom1_model = google/gemini-2.5-flash

Option B: Raw Key String (Auto-detected):

YourGeminiKeyHere...

(X-Ray automatically identifies key formats: AQ. or AIzaSy for Gemini, sk-proj- for OpenAI, sk-ant- for Claude, sk-or- for OpenRouter).

  1. Safely eject your e-reader and open KOReader.
  2. In KOReader, navigate to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers → Import from File (xray_key.txt).
  3. The plugin reads and saves your keys, then renames the file to xray_key.txt.imported for security so it is not processed repeatedly.

Method 4: xray_config.lua Configuration File

For developers, power users, and multi-device setups. Allows defining keys, custom endpoints, fallback models, and system prompts in Lua.

Step-by-Step Instructions:

  1. In your KOReader directory or plugins/xray.koplugin/, create or edit xray_config.lua.
  2. Define your configuration table:
return {
    -- AI Provider API Keys
    gemini_api_key = "YourGeminiKeyHere",
    chatgpt_api_key = "YourOpenAIKeyHere",
    deepseek_api_key = "YourDeepSeekKeyHere",
    claude_api_key = "YourClaudeKeyHere",

    -- Custom OpenAI-compatible or Local LLM endpoints
    custom1_api_key = "YourKey",
    custom1_endpoint = "https://openrouter.ai/api/v1/chat/completions",
    custom1_model = "google/gemini-2.5-flash",

    -- Default active provider ("gemini", "chatgpt", "deepseek", "claude", "custom1")
    default_provider = "gemini",

    -- Custom Cloudflare Relay URL (if self-hosting the Worker)
    cloud_setup_worker_url = "https://xray-setup.ultimatejimmy.workers.dev",
}
  1. Restart KOReader or launch X-Ray to load the configuration.

Tip

Keys set via xray_config.lua serve as global defaults. If you enter a key via the UI or Web Portal, the UI key will take precedence.

Method 5: Enter on E-Reader Keyboard

If you have a physical keyboard or don't mind typing on the E-Ink touch keyboard:

  1. Open any book in KOReader.
  2. Go to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers → Enter Key on E-Reader....
  3. Select your provider from the menu:
    • Google Gemini (Free / Recommended)
    • OpenAI ChatGPT
    • DeepSeek
    • Anthropic Claude
    • Custom / OpenRouter
  4. Type or paste your key into the text box and tap Save.

Where to Get Free & Paid API Keys

1. Google Gemini (Recommended — Free Tier Available)

  • Cost: Free (Generous free tier with 15 requests per minute, ample for book reading).
  • Key Format: Starts with AQ. or AIzaSy...
  • How to get it:
    1. Visit Google AI Studio.
    2. Sign in with any Google account.
    3. Click Create API Key and copy your key.

2. OpenAI ChatGPT

  • Cost: Paid (requires adding $5 credit in billing).
  • Key Format: Starts with sk-proj-... or sk-...
  • How to get it: Visit OpenAI Platform API Keys.

3. DeepSeek

  • Cost: Very low cost (pay-as-you-go, $0.14 to $0.28 per million tokens).
  • Key Format: Starts with sk-...
  • How to get it: Visit DeepSeek Open Platform.

4. Anthropic Claude

  • Cost: Paid (requires billing credit).
  • Key Format: Starts with sk-ant-...
  • How to get it: Visit Anthropic Console.

5. OpenRouter (Custom API)

  • Cost: Pay-as-you-go for 100+ AI models.
  • Key Format: Starts with sk-or-...
  • Endpoint: https://openrouter.ai/api/v1/chat/completions
  • How to get it: Visit OpenRouter Keys.

Security, Privacy & Key Management

Where Are Keys Stored?

  • When entered via the UI, Phone/PC portal, or text import, keys are stored in KOReader's private configuration file on your device: [koreader-dir]/settings/xray.lua.
  • They remain entirely on your device and are only transmitted directly to the respective AI provider's official API endpoint (e.g. generativelanguage.googleapis.com or api.openai.com) over TLS HTTPS during data fetching.

Clearing & Rotating Keys

  • Clear Single Provider Key: Navigate to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers → Clear [Provider] API Key.
  • Clear All Keys: Select Clear All Stored API Keys to reset all credentials at once.

Troubleshooting & FAQ

My phone says "API key sent", but my e-reader isn't updating.

  1. Ensure your e-reader is connected to Wi-Fi: Check that the Wi-Fi icon is active and internet is reachable on your device.
  2. Leave the QR code dialog open: The e-reader polls the relay while the setup dialog is visible on screen.
  3. Switch to Local Wi-Fi Mode: If your phone is on cellular data or an isolated network, tap Local Wi-Fi (Offline LAN) on the e-reader dialog to connect directly.

Can I have multiple provider keys configured simultaneously?

Yes. You can store keys for Gemini, OpenAI, DeepSeek, Claude, and OpenRouter at the same time. You can switch your active Primary AI and Secondary AI at any time in AI Settings → Model Selection.

What happens if I update the plugin?

All stored API keys, custom settings, and fetched book X-Ray databases are preserved across plugin updates.

Clone this wiki locally