Bazarr+

AI Translation Setup

What is OpenRouter

OpenRouter is a unified API gateway that gives you access to language models from OpenAI, Anthropic, Google, Meta, Mistral, and many others through a single API key. Instead of managing separate accounts with each provider, you use one key and pick whichever model fits your needs.

Bazarr+ uses OpenRouter through a companion service called AI Subtitle Translator. This service handles the translation prompts, subtitle parsing, and batch processing. You just provide the API key and choose a model.

Getting an API key

  1. Go to openrouter.ai/keys and create an account (or sign in with Google/GitHub).
  2. Click Create Key. Give it a name like "bazarr" so you can identify it later.
  3. Copy the key. It starts with sk-or-. You will paste this into Bazarr+ under Settings > AI Translator.
Free tiers available. Several models on OpenRouter have free usage tiers with generous limits. You can start translating without spending anything. Check the free models list for current options.

Configuring the translator service

Add the AI Subtitle Translator container to your docker-compose.yml. If you used the install script and chose to enable AI translation, this is already done.

docker-compose.yml (add to existing file) 
  ai-subtitle-translator:
    image: ghcr.io/lavx/ai-subtitle-translator:latest
    container_name: ai-subtitle-translator
    restart: unless-stopped
    ports:
      - 8765:8765
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8765/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Then restart your stack:

Shell 
docker compose up -d

Bazarr+ auto-detects the translator service when it is running on the same Docker network. The OpenRouter API key is configured inside Bazarr+ under Settings > AI Translator, not as a container environment variable.

Choosing a model

Go to Settings > AI Translator in Bazarr+. You will see a model selector with all available models from OpenRouter. Some things to consider:

  • Quality vs. speed. Larger models (Claude Opus 4.6, GPT-4.1) produce better translations but cost more. Mid-range models (Gemini 2.5 Flash, Claude Sonnet 4.5) hit a good balance. Lightweight models (Gemini 2.5 Flash Lite, Claude Haiku 4.5) are fast and cheap.
  • Free models. OpenRouter offers free tiers for select models (look for the "free" badge). Great for testing the workflow or large batches where perfect quality is not critical.
  • Context window. Subtitle files can be large. Models with bigger context windows (200k+ tokens) handle full-length movies in fewer chunks, producing more consistent translations.
  • Provider routing. Most models are served by several OpenRouter providers at different prices and speeds. The Provider Routing selector picks between them: Fastest (the default) takes the highest-throughput provider, Cheapest the lowest price. The :nitro and :floor variants also make OpenRouter's priority and flex tiers eligible, and OpenRouter default leaves their load balancing on. Typing :floor or :nitro straight after a model ID works too: Bazarr+ moves the shortcut into the selector and leaves the plain model ID in the field, so the two can never disagree and the model details still load. Routing only changes anything when a model is served by more than one provider, and around half of OpenRouter's catalogue is served by exactly one. OpenRouter ignores a suffix it does not recognise, so a typo such as :floorr fails silently rather than erroring. The two shortcut options and OpenRouter default need AI Subtitle Translator 1.3.4 or newer; on an older sidecar Bazarr+ sends the plain sort each of them stands for (fastest or cheapest) and logs a warning.
Recommendation: Start with google/gemini-2.5-flash-lite. It handles subtitle translation well and costs fractions of a cent per episode. Switch to Claude Sonnet 4.5 if you need higher quality for difficult content.

Batch translation from Missing pages

The Missing pages (Episodes and Movies) show episodes and films that are missing subtitles in your configured languages. With AI translation, you can handle these in bulk:

  1. Go to Missing > Episodes or Missing > Movies.
  2. Select the items you want to translate using the checkboxes (or use "Select All").
  3. Click Mass Translate in the batch action toolbar.
  4. Choose the source language (the existing subtitle language) and target language.
  5. Confirm. Bazarr+ queues the translation jobs and processes them in the background.

You can monitor progress in the editor's translate panel or in Settings > AI Translator, which shows active jobs, their status, and any errors.

Using the editor's AI translate feature

For individual files where you want more control, open a subtitle in the built-in editor. The editor has a dedicated AI translation panel where you can:

  • Translate the entire file at once
  • Review the translation count and apply to the editor cues, then edit as needed

This is useful for spot-checking quality or handling files that need special attention, like subtitles with heavy slang or technical terminology.

Translate from an embedded track v2.4

As of v2.4 you can translate directly from an embedded (in-container) subtitle track, without exporting it first. In the subtitle table, an embedded track shows a 100% source score and a translate-only action. Choosing it extracts the text stream with ffmpeg and runs the configured translator against it.

Text tracks only. Embedded translation works on text-based tracks. Bitmap tracks (PGS, VobSub) carry no extractable text and are rejected with a clear error. For how embedded tracks are scored and recorded in history, see Subtitle processing.

Cost estimates

Translation costs depend entirely on the model and subtitle length. Here are rough estimates for a typical 90-minute movie (~1,500 subtitle lines):

  • Free models (free-tier Gemini, Llama, Qwen): $0.00
  • Budget models (Gemini 2.5 Flash Lite, Claude Haiku 4.5): ~$0.001 to $0.01
  • Mid-range models (Gemini 2.5 Flash, Claude Sonnet 4.5): ~$0.02 to $0.10
  • Premium models (Claude Opus 4.6, GPT-4.1): ~$0.15 to $0.50

These are ballpark figures. Actual costs vary with subtitle density, the length of each line, and the provider that serves the request: the same model can cost twice as much from a fast provider as from the cheapest one, so switch Provider Routing to Cheapest when price matters more than speed. OpenRouter shows your usage and spending on their dashboard in real time.

Watch your spending. Batch-translating hundreds of episodes with a premium model can add up. Set a spending limit on your OpenRouter account if you want a safety net. The setting is under Account > Credits on their site.

Next steps