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.

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.

  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:

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, and which one serves you decides what a translation costs. Provider routing below covers how Bazarr+ chooses.

Provider routing v2.7

Most OpenRouter models are served by more than one provider, at different prices and different speeds, for the same model and the same output. The provider that serves a request is what decides its cost. Settings > AI Translator > Provider Routing is where you say how that choice is made.

This only changes anything when a model has more than one provider. Around half of OpenRouter's catalogue is served by exactly one, and for those every option below does the same thing.

Every option below is carried out by AI Subtitle Translator, so the Needs column is the version of that service, not of Bazarr+.

SmartFast

SmartFast is what a new install uses. Rather than sorting on one axis, the translator loads the endpoints that actually serve your model and picks among them: it drops anything unhealthy or priced above its limits, discards the cost outliers, keeps the candidates within a tolerance of the fastest it has measured, and takes the cheapest of those. It then stays on that provider for the rest of the translation, so a prompt cache has a chance to be reused, and moves off it if the provider starts failing or slows down consistently.

The reason it is the default is measurable. In the September provider benchmarks, plain throughput routing repeatedly landed on endpoints priced around twice the cheapest that served the same model, with nothing on screen to say so. SmartFast gives up a little speed for that.

Custom providers

Custom is for when you already know which providers you will accept, whether that is for price, for privacy, for data retention policy, or because one of them has been unreliable for you.

Choosing it reveals a picker listing every endpoint that serves the model you selected, with its availability, its quoted input and output price per million tokens, and its recent median throughput where OpenRouter reports one. Pick from the list, or type an exact provider slug such as deepinfra or an endpoint slug such as parasail/fp8, and reorder them with the Up and Down controls. The translator tries them in the order you set.

Providers outside your list are excluded rather than deprioritised. That is the point of the mode, and it has a consequence worth being clear about: if none of your chosen providers can serve the model, the translation fails rather than quietly going somewhere you ruled out. The picker helps you avoid that by marking any slug the model's endpoint list does not contain as Does not serve this model. Change models and it re-checks, so it is worth a glance after switching.

A list of up to 20 slugs is allowed. Bazarr+ refuses to save Custom routing with nothing selected, since that configuration cannot translate anything.

Shortcuts typed into the model ID

Appending :nitro, :floor or :smartfast to a model ID works as a shorthand. Bazarr+ moves the shortcut into the Provider Routing selector when you leave the field and puts the plain model ID back, so the two can never disagree and the model details still resolve. Genuine model variants such as :free and :thinking name a different model rather than a way to route to the same one, and are left alone: author/model:free:nitro becomes author/model:free with the selector on the priority tier.

One exception. If the selector is already on Custom, a typed shortcut does not override it, because that would silently discard the provider list you built. The shortcut comes off the model ID and the page tells you the selection was kept.

OpenRouter ignores a suffix it does not recognise, so a typo such as :floorr fails silently rather than erroring.

Version requirements

Routing is carried out by AI Subtitle Translator, so some options need a recent enough one. The Needs column above lists them, and the behaviour when it is not met differs by option, deliberately:

• The shortcut options and OpenRouter default fall back. On a sidecar below 1.3.4, Bazarr+ sends the plain sort each of them stands for, fastest or cheapest, and logs a warning.
• SmartFast and Custom do not fall back. No plain sort stands for "weigh speed against price" or "only these providers", so rather than routing your translation some other way, Bazarr+ refuses and tells you which version is needed. Update the translator, or pick another option.

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.

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.

Next steps

• Install Provider Hub plugins if you want more subtitle sources before translating
• Getting Started if you have not installed Bazarr+ yet
• Migration from upstream if you are switching from stock Bazarr