Skip to content

5. AI Providers & Models

Jump to bottom
Jimmy Pautz edited this page Jun 30, 2026 · 1 revision

The plugin gives you a few options for the AI backend. You can swap between them based on what works best for you.

Providers

Google Gemini

This is the default and generally the best choice for most people:

  • It has a generous free tier that is more than enough for regular reading.
  • Models like gemini-3.5-flash (default primary) and gemini-3.1-flash-lite (default secondary) are extremely fast and capable.
  • It can handle a huge amount of context at once, which is great for long books.
  • Reasoning: Gemini 2.5+ models support internal reasoning levels.

OpenAI ChatGPT

If you already use the OpenAI API, you can plug in your key here:

  • You can use high-performance models like gpt-5.5, gpt-5.4-mini, and gpt-5.4-nano.
  • Note: gpt-4o and gpt-4o-mini are now considered legacy/deprecated and are available via the "Custom Model" option.
  • Just keep in mind that you need an API key with actual prepaid credits—a standard ChatGPT Plus subscription doesn't cover API usage.

DeepSeek

DeepSeek offers powerful open-weight reasoning models that are very cost-effective:

  • Use deepseek-v4-flash for standard fast requests, or deepseek-v4-pro for complex extraction.
  • You must create an API key at DeepSeek's platform.

Anthropic Claude

Claude models are excellent for literary analysis and complex character extraction:

  • Claude 4.6 Sonnet (claude-sonnet-4-6) and Claude 4.5 Haiku (claude-haiku-4-5) are the current supported versions.
  • Claude natively supports structured JSON outputs and sophisticated extended thinking.

Custom API Providers

For advanced users, you can configure up to two custom API providers (e.g., OpenRouter, openmodel.ai, LiteLLM, or self-hosted models) supporting either OpenAI or Anthropic payload formats.

  • Configurable Base URL: Set your own endpoint (e.g., https://openrouter.ai/api/v1/chat/completions or https://api.openmodel.ai/v1/messages).
  • Auto-Format Detection: The plugin automatically detects Anthropic-compatible endpoints (if the URL contains /v1/messages or /messages) and formats the request body and headers accordingly. You can also explicitly specify the format in the config file.
  • Model Selection: Manually specify any model ID supported by your provider.
  • Is Reasoning Model: Toggle this if your custom model is a reasoning model (e.g., DeepSeek-R1) to allocate a larger token budget for extended thinking chains.
  • Provider-Specific Headers: Automatically includes required attribution headers (like HTTP-Referer and X-Title) for OpenRouter, and required version/authorization headers for Anthropic-compatible endpoints.

AI Model Reasoning Effort

For supported reasoning models, you can configure the "Reasoning Effort" in AI Settings to control internal 'thinking' time.

  • Unset: No specific instruction sent; the model uses its internal defaults.
  • Low: Fast, economical extraction for simple books.
  • Medium: Balanced depth for most standard narratives.
  • High: Detailed analysis for complex character webs.

Applies to: GPT-5.x (o1/o3/gpt-5), Claude (sonnet/opus/haiku), and Gemini 2.5+.

Note: DeepSeek V4 reasons inherently — this setting has no effect on it.

Primary and Secondary Models

Sometimes API requests fail, usually because of rate limits or temporary network issues. To handle this, the plugin lets you set a primary and secondary model.

If your primary model (like claude-sonnet-4-6) fails, it'll automatically try the secondary model (like gemini-2.5-flash) before giving up.

Unified API Keys Menu

You can manage your API keys for all providers in one place! Go to Tools Menu → X-Ray → Settings → AI Settings → API Keys & Providers.

The menu allows you to choose between:

  1. Config Key: Reading directly from your xray_config.lua file.
  2. UI Key: A key entered directly in the KOReader interface (overrides the config file).

This allows for easy switching between different keys or testing new providers without editing files manually.

Dealing with Limits

If you ever see a 429 Quota Exceeded error, it just means you've hit your provider's rate limit. Wait a minute or two and try again. If you're using Gemini's free tier, you should easily be able to process a few books a day without hitting hard caps.

For more information on the config file, see Advanced Usage.

Clone this wiki locally