Directly Fetching Wyzie Subs#

If you have decided against using the NPM package, then let's get started. I will only be going over API parameters and data returned by the API. How you request the API is entirely up to you.

Example#

{
  "id": "1955024019",
  "url": "https://sub.wyzie.io/c/198e0c4d/id/1955024019?format=srt&encoding=UTF-8&tok=...",
  "flagUrl": "https://flagsapi.com/US/flat/24.png",
  "format": "srt",
  "encoding": "UTF-8",
  "display": "English",
  "language": "en",
  "media": "The Martian",
  "isHearingImpaired": false,
  "source": "charlie",
  "release": "The.Martian.2015.1080p.WEB-DL",
  "releases": ["The.Martian.2015.1080p.WEB-DL"],
  "fileName": "the.martian.2015.1080p.web-dl.srt",
  "downloadCount": 48213,
  "origin": "WEB-DL",
  "matchedRelease": "The.Martian.2015.1080p.WEB-DL",
  "matchedFilter": "martian",
  "ai": false
}

Parameters#

Data Returned#

Downloading Subtitles#

Every url in a /search response points to https://sub.wyzie.io/c/... and carries a tok query parameter. tok is encrypted, so it does not reveal your API key, and it stays valid for 60 days. Each link has its own tok that opens only that file, so use the URL as-is (adding download options is fine). A search costs 1 request and each download costs 1 more, billed to the key that ran the search. When that key cannot pay for a download, the link is refused:

Download Options#

Add these to a download URL to change what it returns. They work on every download, cached or not, and cost nothing extra (except dual, below). The X-Subtitle-Transforms response header lists what was applied, with counts.

Options combine, e.g. &to=vtt&sdh=strip&offset=-1.5. Links already carry format, encoding, id and (for episodes) season and episode: leave those as they are. autoUnzip=false returns an archive as-is.

One-Call Download#

With an API key, GET /download returns the subtitle file itself in one call: it searches with your key and the same parameters as /search (language defaults to en), picks the best match and serves it. That costs 2 requests, the same as a search plus a download. Download options such as to and offset apply to the file.

curl -o subtitle.vtt "https://sub.wyzie.io/download?id=tt0111161&language=en&to=vtt&key=YOUR_KEY"

The best match is the first search result, preferring SRT, WebVTT and ASS files unless you set format, and files without hearing-impaired text unless you set hi=true. Narrow it with release, filename, source or origin. The X-Subtitle-Release, X-Subtitle-Source, X-Subtitle-Language and X-Subtitle-Url response headers say which file was picked. Errors are the same as for /search and download links.

Pagination and Headers#

Every /search response includes an X-Total-Count header with the total number of results. When you pass limit, it also includes:

• X-Page: the page returned.
• X-Per-Page: the limit in effect.
• X-Total-Pages: the total number of pages.

Responses also carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Treat them as approximate: usage is settled with billing in short batches, so they can trail your real usage slightly.

Errors#

Errors are returned as JSON with the matching HTTP status:

{
  "code": 401,
  "message": "API key required",
  "details": "Include a valid API key as the `key` query parameter. Claim a free key at https://store.wyzie.io/redeem",
  "notice": "https://sub.wyzie.io/notice"
}