Migration Guide

Add Your API Key in Minutes

You're receiving this because your requests are hitting Wyzie Subs without an API key. Keys are free grab one at sub.wyzie.io/redeem and adding one is super easy.

The key goes in as a query-param named key. Everything else about your existing calls stays the same.

Plain `fetch`

Append &key=YOUR_KEY to the URL. That's it.

before → after

- const url = `https://sub.wyzie.io/search?id=${id}&language=en`;
+ const url = `https://sub.wyzie.io/search?id=${id}&language=en&key=${API_KEY}`;

full example

const API_KEY = "your_key_here"; // store in env, not source

const subs = await fetch(
  `https://sub.wyzie.io/search?id=${tmdbId}&language=en&key=${API_KEY}`
).then(r => r.json());

If you build the URL with URLSearchParams just call .set("key", API_KEY) before stringifying.

URLSearchParams variant

const params = new URLSearchParams({ id: tmdbId, language: "en" });
params.set("key", API_KEY); // ← add this line

const subs = await fetch(`https://sub.wyzie.io/search?${params}`)
  .then(r => r.json());

wyzie-lib (NPM package)

Pass key as an extra param

before → after

- const data = await searchSubtitles({
-   tmdb_id: 286217,
-   language: ["en"],
- });
+ const data = await searchSubtitles({
+   tmdb_id: 286217,
+   language: ["en"],
+   key: API_KEY,           // ← add this line
+ });

Server-side proxy

Keep the key out of the browser entirely by forwarding requests through your own backend and injecting there.

node / express route

app.get("/subs", async (req, res) => {
  const params = new URLSearchParams(req.query);
  params.set("key", process.env.WYZIE_API_KEY); // injected server-side

  const upstream = await fetch(
    `https://sub.wyzie.io/search?${params}`
  );
  res.json(await upstream.json());
});

cloudflare worker (drop-in wyzie-worker)

# 1. clone
git clone https://github.com/wyzie/wyzie-worker

# 2. set the secret
npx wrangler secret put NITRO_API_TOKEN

# 3. deploy
pnpm build && npx wrangler deploy .output/server/index.mjs

# Done point your app at the worker URL.

Movie-site scrapers & provider plugins

Most scraper-based frontends (movie-web forks, sudo-flix, p-stream, etc.) hit the subtitle API inside a provider or scraper function. Find the file that constructs the sub.wyzie.io/search URL and add the key there.

typical scraper pattern before → after

// somewhere in providers/subtitles/*.ts
function buildSubUrl(id: string, lang: string) {
-  return `https://sub.wyzie.io/search?id=${id}&language=${lang}`;
+  const key = globalThis._importMeta_.env.VITE_WYZIE_KEY ?? process.env.WYZIE_KEY;
+  return `https://sub.wyzie.io/search?id=${id}&language=${lang}&key=${key}`;
}

If subtitles are fetched inside a useEffect or a React Query function, the same one-liner applies just tack on &key=… wherever the URL string is assembled.

★

Protecting your key

If your app runs in the browser, the key will be visible in network requests. For open-source or publicly deployed sites, use one of these strategies to keep it server-side only:

Option A

wyzie-worker (recommended)

Deploy the official wyzie-worker Cloudflare Worker. It stores your token as a secret and injects it automatically your frontend never sees the key.

deploy in 3 commands

git clone https://github.com/wyzie/wyzie-worker
npx wrangler secret put NITRO_API_TOKEN
pnpm build && npx wrangler deploy .output/server/index.mjs

Then point your app at the worker URL instead of sub.wyzie.io no key required in client code.

Option B

server-side proxy

Add a thin route to your existing backend that injects the key before forwarding to Wyzie Subs. The client calls your route, never the real API directly.

node / express

app.get("/subs", async (req, res) => {
  const params = new URLSearchParams(req.query);
  params.set("key", process.env.WYZIE_API_KEY);
  const data = await fetch(`https://sub.wyzie.io/search?${params}`).then(r => r.json());
  res.json(data);
});

★

Where to store the key

Never hard-code the key in source files that get committed. Pick the right place for your stack:

by environment

# Vite / Nuxt front-end
VITE_WYZIE_KEY=your_key        # .env (add .env to .gitignore)

# Node / Bun back-end
WYZIE_API_KEY=your_key         # .env, Railway, Render, etc.

# Cloudflare Workers
npx wrangler secret put NITRO_API_TOKEN

# Vercel
vercel env add WYZIE_API_KEY

Questions? Reach the docs at docs.wyzie.io or the API home at sub.wyzie.io.