Skip to content

1. Get Started

Jump to bottom
Jimmy Pautz edited this page Jun 30, 2026 · 14 revisions

Here's how to install the plugin and get everything set up.

1. Installation

  1. Grab the latest release and extract the zip file.
  2. Copy the xray.koplugin folder into your KOReader plugins directory.
    • Linux/Android: ~/.config/koreader/plugins/
    • Kindle/Kobo: mnt/us/koreader/plugins/ (or wherever your plugins folder is)
  3. Restart KOReader.

2. Get an API Key

The plugin needs an API key to process the book's text. Google Gemini is generally the best option since their free tier gives you plenty of requests.

Google Gemini (Recommended)

  1. Go to Google AI Studio.
  2. Sign in and click "Create API Key".
  3. Copy the key.

OpenAI ChatGPT

If you prefer ChatGPT:

  1. Go to your OpenAI Dashboard.
  2. Generate a new secret key. (Keep in mind you'll need a funded OpenAI account for this).

DeepSeek

  1. Sign up at the DeepSeek Platform.
  2. Create an API key in the "API Keys" section.

Anthropic Claude

  1. Create an account at the Anthropic Console.
  2. Generate a new key in the "API Keys" section.

Custom / OpenRouter

  1. For OpenRouter, grab a key at openrouter.ai.
  2. For other services, ensure they are OpenAI-compatible and you have their Base URL and Model ID ready.

3. Setup in KOReader

  1. Open any book in KOReader.
  2. Go to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers.
  3. Select your provider and paste your key. For Custom Providers, you'll also need to enter the Base URL and Model ID.
  4. You can also pick your primary model under AI Settings. gemini-3.5-flash or gpt-5.4-mini are solid defaults.

Note

You can also paste your API key in the config file: xray_config.lua. For more information on the config file, see Advanced Usage.

4. Fetching Data

The plugin can automatically fetch data in the background as you read. However, you can also trigger a full fetch manually:

  1. With a book open, navigate to Tools Menu → X-Ray → Fetch X-Ray Data.
  2. Give it about 30 to 60 seconds to run.
  3. A summary will pop up when it's done. Everything is now saved locally, so you don't need an internet connection to use X-Ray for this book again.

See the Fetching Data page for a full breakdown of how manual fetching and automatic background fetching work.

Next, check out the Core Content & Features to see what you can do.

Clone this wiki locally