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.
Recommendation: Start with google/gemini-2.5-flash-lite-preview-09-2025. 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.

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 and the length of each line. 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