API Keys#

Wyzie Subs requires an API key for all requests. A free tier covers most use cases; paid plans handle heavier usage.

Tiers#

Pro and top-ups don't expire. Prefer recurring? A $32/month subscription gives 6,000,000 requests/month (card only). See store.wyzie.io for full pricing and the dashboard.

Getting a Free Key#

Visit store.wyzie.io/redeem:

1. Solve a quick Cloudflare Turnstile captcha.
2. Enter an address from a major personal email provider (Gmail, Outlook/Hotmail, Yahoo, iCloud, AOL, Proton, and others). Disposable email domains are rejected.
3. Enter the 6-digit code we email you.
4. You receive an API key that looks like wyzie-abc123...

Each email address and each network can claim one free key; a second request returns 409. Lost your key? Use "Forgot key" on the dashboard to have it re-sent.

Upgrading to Pro#

Visit store.wyzie.io and check out with the same email you used for your free key. Your existing wyzie-... key is upgraded in place with 400K paid requests added on top. Prefer recurring? A $32/month subscription adds a 6,000,000-request monthly allowance (card only) instead.

If you check out with a brand new email (no prior key), a fresh wyzie-... key is generated and emailed to you.

Keep Your Key Off the Client#

Two safe ways to use the key from a client app:

1. Use Wyzie Worker: a free Cloudflare Worker proxy that holds your API key as the NITRO_API_TOKEN secret. Every call to it must send Authorization: Bearer <NITRO_WORKER_KEY>, a second secret you set, so route your client through your own backend and keep the worker key server-side as well.
2. Run your own proxy: any backend endpoint that appends the key before forwarding to sub.wyzie.io works. See the Intro page for a 10-line example.

If the key shows up in a network tab in DevTools, it is exposed. Assume it is public and rotate it from your dashboard.

Using Your Key#

Append &key=YOUR_KEY to every API request:

https://sub.wyzie.io/search?id=tt3659388&key=YOUR_KEY
https://sub.wyzie.io/search?id=286217&language=en&key=YOUR_KEY
https://sub.wyzie.io/search?id=tt0121955&season=1&episode=1&key=YOUR_KEY

NPM Package#

Pass key alongside your other search parameters:

import { searchSubtitles } from "wyzie-lib";
 
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
  key: "YOUR_KEY",
});

Or set it once globally with configure so every request includes it automatically:

import { configure, searchSubtitles } from "wyzie-lib";
 
configure({
  baseUrl: "https://sub.wyzie.io",
  key: "YOUR_KEY",
});
 
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
});

Hitting the Limit#

A search costs 1 request and each subtitle download costs 1 request, so searching once and downloading one file uses 2. AI translation costs 25 requests per call, and a Wyzie Synced sync 5.

• Free tier depleted -> searches and download links return 429 Daily request limit reached, with reset_at in the JSON and a Retry-After header. The daily cap of 1,000 requests resets at UTC midnight.
• Paid balance exhausted -> searches and download links return 402 with a top-up link in the JSON. Top up at store.wyzie.io/topup or enable auto top-up in your dashboard to refill automatically when your balance crosses a threshold you set.

Key on Hold#

Keys that send very high volume mostly from datacenter or hosting IPs are paused automatically. A paused key gets 403 Key on hold on every request, with a reinstate link (https://store.wyzie.io/verify) and a support link (https://store.wyzie.io/contact) in the JSON.

To reinstate the key right away, verify the website you use it on at store.wyzie.io/verify with a DNS TXT record or a meta tag. A key with a verified site is never auto-paused again, so busy sites can verify before they are ever paused.

No website, for example a backend service or an app? Contact support to get the key reinstated.

What Is in the Files#

• Ad filtering – every subtitle served through sub.wyzie.io has provider advertising cues stripped (OpenSubtitles banners, betting plugs, "watch free at ..." lines). SRT cues are renumbered so nothing skips. Every provider, OpenSubtitles included, is served through sub.wyzie.io so the filter applies to all of them.
• Free and dev keys get one short cue at the very start of each file (0–6 s) pointing at store.wyzie.io. Paid keys receive clean files with no cue.

FAQ#

I lost my key. Can I get a new one?

Can I use one key in multiple projects?

Will my key ever expire?

Is auto top-up safe?