AI Subtitle Translation#

Wyzie can translate any subtitle into 80+ languages on the fly. The translated SRT is streamed back in order as batches finish, so the first cues arrive quickly instead of after the whole file is done. The complete translation is cached for 30 days, so later requests for the same title, episode, and target language are served from the cache.

Two Ways to Use It#

1. Pick a Language From a Search Response#

For Pro keys, every /search response also includes AI translation rows with "ai": true and a url that points at /translate: one per supported language, or only the languages in your language= filter. Free keys never get these rows. Treat the AI rows like any other subtitle row in your UI: when the user clicks one, fetch the URL.

{
  "id": "ai-es",
  "url": "https://sub.wyzie.io/translate?id=tt3659388&tk=...&target=Spanish",
  "format": "srt",
  "encoding": "UTF-8",
  "display": "Spanish",
  "language": "es",
  "source": "ai",
  "ai": true
}

The tk param is an encrypted token made from the API key you passed to /search. It does not reveal your key, stays valid for 60 days, and lets the translate endpoint authorise the request for that title only (a download link's tok does not work here). You do not need to compute it yourself; just use the URL as-is.

If you want to hide the AI rows from your UI, filter them out:

const real = results.filter((r) => !r.ai);

2. Call /translate Directly#

GET https://sub.wyzie.io/translate?id=tt3659388&target=Spanish&key=YOUR_KEY

The response body is an SRT file streamed as text/plain; charset=utf-8. Useful response headers:

• X-Cache: HIT-REDIS if served from cache, MISS if generated fresh.
• X-Source-Language: language of the subtitle the translator used as input.
• X-Target-Language: echo of your target param.
• X-Source-Provider: which scraper supplied the source subtitle.

How It Works#

1. Wyzie searches the normal sources for a text subtitle, preferring an English SRT when available. VTT, ASS, SSA, and SUB files are converted to SRT first.

2. The SRT is split into batches of up to about 3,800 characters and translated with Google Translate, 4 batches at a time.

3. Output is streamed back in SRT order as batches finish, so the first cues arrive quickly. Players that accept a streaming SRT body can start showing the first lines before the rest are done.

4. The complete translation is cached in Redis for 30 days, keyed by id, season, episode, and target.

Supported Target Languages#

80+ languages including all major European, Asian, African, and Middle Eastern languages. Pass a name from the list (Spanish, Portuguese (Brazil)) or its code (es, pt-BR). For Pro keys, the full list is also returned as ai: true rows in any /search response without a language= filter, which is the canonical source of truth.

The full list is also available as JSON at GET /languages: { code, name } pairs, free and with no key needed. With wyzie-lib, call getLanguages().

Limitations#

• AI translation needs a text subtitle to start from. VTT, ASS, SSA, and SUB sources are converted to SRT first; if no text subtitle exists, the call returns 404 No subtitle found and the 25 requests are refunded.
• Translation quality depends on the source subtitle. A poorly-timed or mistyped source produces a poorly-timed or mistyped translation.
• Some users may want to opt out of AI rows entirely. Filter on ai === false in your client.
• Translations are billed on cache hits too. Whether freshly generated or served from the 30-day cache, each /translate call costs 25 requests. Only calls that fail before any output are refunded.

Example#

curl "https://sub.wyzie.io/translate?id=tt3659388&target=Japanese&key=YOUR_KEY"

Same as a normal SRT download. Drop the body into any player that accepts SRT files.