Skip to content

README.md

Latest commit

 

History

History
127 lines (95 loc) · 9.49 KB

README.md

File metadata and controls

127 lines (95 loc) · 9.49 KB
Raw

OpenRouter Responses Pipe for Open WebUI — Documentation

This documentation set covers installation, configuration, operations, and security for the Open WebUI pipe that targets the OpenRouter Responses API.

Who this is for

Everyday users

Use these docs if you want to install the pipe, select OpenRouter models in Open WebUI, and troubleshoot common errors.

Enterprise admins / operators

Use these docs if you run Open WebUI for multiple users and need secure configuration, deployment guidance, operational controls, and incident-ready logging.

Contributors

Use these docs if you are modifying the pipe, working on tests, or extending the integrations.

Quick start (install and use)

Prerequisites

  • Open WebUI 0.9.1 or later (the pipe declares this requirement in its manifest header).
  • An OpenRouter API key, provided either via the OPENROUTER_API_KEY environment variable or via the pipe’s valve configuration.

Install (Open WebUI UI)

  1. In Open WebUI, go to Admin → Functions → New Function.

  2. Import one of the bundled pipe files and paste a URL:

    Readable bundle (audits or troubleshooting):

    https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe/releases/latest/download/open_webui_openrouter_pipe_bundled.py

    Compressed bundle (routine installs; smaller payload, faster upload, same runtime behavior):

    https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe/releases/latest/download/open_webui_openrouter_pipe_bundled_compressed.py

  3. Save and enable the function.

Dependencies

Open WebUI installs the Python dependencies declared in the function header (requirements:). This pipe declares (at least) aiohttp, cryptography, fastapi, httpx, lz4, pydantic, pydantic_core, sqlalchemy, tenacity, and pyzipper, plus cairosvg and Pillow (used to import OpenRouter model icons into Open WebUI as PNG data URLs).

Configure

  • Open WebUI Valves are the configuration surface for this pipe. At minimum, configure the OpenRouter API key (or set OPENROUTER_API_KEY in the Open WebUI environment).
  • For the authoritative list of valves (including verified defaults), see: Valves & Configuration Atlas.

Use

After enabling the function, Open WebUI will expose OpenRouter models (imported from OpenRouter’s model catalog) in the model selector. Choose a model and chat normally.

Optional: model metadata sync (icons + capabilities)

This pipe can automatically sync Open WebUI model metadata for the OpenRouter models it exposes:

  • UPDATE_MODEL_IMAGES controls whether model profile images are downloaded and stored in Open WebUI.
  • UPDATE_MODEL_DESCRIPTIONS controls whether model descriptions are synced from the OpenRouter catalog.
  • UPDATE_MODEL_CAPABILITIES controls whether model capability checkboxes are synced.

See: OpenRouter Integrations & Telemetry.

Optional: model variants and presets

This pipe supports OpenRouter model variants (:nitro, :free, :exacto, etc.) and user-defined presets. Configure VARIANT_MODELS to expose these as separate model selector entries.

See: Model Variants & Presets.

Common troubleshooting

Models do not appear / no OpenRouter options

  • Confirm the function is enabled in Admin → Functions.
  • Confirm the pipe is configured with a valid API key (valve or OPENROUTER_API_KEY environment variable).
  • If your deployment blocks outbound internet access, ensure it can reach the OpenRouter API endpoint configured by BASE_URL.
    • The model list is populated by refreshing the OpenRouter catalog; when the refresh fails and no cached catalog exists, Open WebUI will show no models until connectivity and credentials are fixed.

Authentication errors (401/403) or “invalid API key”

  • Validate the configured key and confirm it is being provided where you expect (valves vs environment variables).
  • If you run Open WebUI behind a proxy/gateway, verify BASE_URL points to your gateway and that the gateway is correctly forwarding auth headers.

Remote files or images fail to load

Requests fail under load

Where to go next

Start here (most users and admins)

  • Valves & Configuration Atlas — authoritative configuration reference (defaults verified against code/tests).
  • Error Handling & User Experience — what users see, how errors are structured, and how to troubleshoot.
  • OpenRouter Direct Uploads (bypass OWUI RAG) — forward chat uploads to OpenRouter as direct files/audio/video with per-chat toggles and safety gates.
  • OpenRouter Image Generation — native image-output models (Sourceful, FLUX, Seedream, Gemini Image, GPT-5 Image), seven filters (generic plus the Gemini, Sourceful/Riverflow, Recraft, and Grok families), per-model knobs, and the inline rendering pipeline.
  • OpenRouter Video Generation — async video models, per-model filters, streaming storage, and resume behavior.
  • Video Intent Classifier — task-model-driven cross-turn context for video generation. A small classifier runs before each video request, reads the chat history, and decides what visual reference to wire into the request. Covers the frame_plan schema, intent disclosure block, frame extraction at arbitrary timestamps, the modify-fallback flow (when a model can't honor input_reference), 11 admin valves, and 4 per-model filter UserValves.
  • OpenRouter Provider Routing — control which infrastructure providers serve your requests with per-model filters, ORDER dropdowns, and compliance options (ZDR, fallbacks).
  • OpenRouter Integrations & Telemetry — identifiers, metadata, optional telemetry exports, and OpenRouter-facing headers.
  • OpenRouter Server Tools — Web Search, Web Fetch, Datetime, and Image Generation server tools: configuration, companion filters, and data flow.
  • Web Search: OWUI vs OpenRouter — the distinction between Open WebUI native web search and OpenRouter web search, suppression behavior, and when to use which.
  • Model Variants & Presets — create virtual model entries for OpenRouter variants (:nitro, :exacto, etc.) and user-defined presets (@preset/your-preset) to expose specialized routing options in the model selector.

Extending the pipe (developers)

  • Plugin System (developer guide) — hook-based framework for extending the pipe; covers the plugin lifecycle, hooks, valve contributions, and the ENABLE_PLUGIN_SYSTEM master switch.
  • Pipe Dashboard plugin — built-in showcase plugin: live dashboard over OWUI's Socket.IO channel, plus chat commands.

Security and compliance guidance (admins)

Operations and performance (admins/operators)

Deep technical references (contributors)