Skip to content

Advanced Usage

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

Advanced Configuration

If you want to configure custom API endpoints, edit the raw configuration files, or integrate custom models, this page outlines the advanced setup options.

Manual Config Editing

While most settings are handled through the UI, you can manually enter your API keys or customize the default behaviour by editing xray_config.lua in the plugin folder (koreader/plugins/xray.koplugin/xray_config.lua).

Here is a template config file:

-- X-Ray API Configuration

return {
    -- Google Gemini API Key
    -- To get an API key: https://aistudio.google.com/
    gemini_api_key = "", 
    
    -- ChatGPT API Key 
    -- To get an API key: https://platform.openai.com/api-keys
    chatgpt_api_key = "",  

    -- DeepSeek API Key
    -- To get an API key: https://platform.deepseek.com/
    deepseek_api_key = "",

    -- Anthropic Claude API Key
    -- To get an API key: https://console.anthropic.com/
    claude_api_key = "",

    -- Custom API slot 1 (e.g., OpenRouter, any OpenAI-compatible endpoint)
    custom1_api_key  = "",   -- Your API key for this endpoint
    custom1_endpoint = "",   -- e.g., "https://openrouter.ai/api/v1/chat/completions"
    custom1_model    = "",   -- e.g., "google/gemini-2.5-pro"
    custom1_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)

    -- Custom API slot 2 (e.g., a local Ollama server)
    custom2_api_key  = "",
    custom2_endpoint = "",   -- e.g., "http://localhost:11434/v1/chat/completions"
    custom2_model    = "",   -- e.g., "llama3"
    custom2_format   = "",   -- optional: "openai" or "anthropic" (default: auto-detected from endpoint)
}

Note

Settings like model selection, language preferences, and spoiler modes are managed through the on-screen UI menu and stored in a separate settings.json file outside the plugin folder. This ensures your settings persist even if you uninstall and reinstall the plugin.

Custom API Providers

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

  • Configurable Endpoint: 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/headers accordingly. You can also explicitly set "openai" or "anthropic" in the customX_format config key.
  • Reasoning Models: If your custom model is a reasoning model (e.g., DeepSeek-R1), toggle Is Reasoning Model in the UI to allocate a larger token budget for extended thinking chains.
  • Provider-Specific Headers: The plugin automatically includes required attribution headers (like HTTP-Referer and X-Title for OpenRouter) and required version/authorization headers for Anthropic-compatible endpoints.

Related Pages

Clone this wiki locally