wyzie-subs
Python client for the Wyzie Subs API: subtitle search, download, transcribe, fix and extract. Sync and async, one dependency (httpx), Python 3.9+.
Install
pip install wyzie-subs
Quick start
from wyzie_subs import Wyzie
wyzie = Wyzie("YOUR_KEY")
results = wyzie.search("tt0111161", language="en")
srt = wyzie.download(results[0], to="vtt", shift="-1.5")
print(wyzie.last_cost, wyzie.last_balance) # from X-Wyzie-Cost / X-Wyzie-Balance
Async: AsyncWyzie has the same methods; await each call.
from wyzie_subs import AsyncWyzie
async with AsyncWyzie("YOUR_KEY") as wyzie:
best = await wyzie.search_best("tt0111161", language="en")
Constructor: Wyzie(key, base_url="https://sub.wyzie.io", timeout=15.0, retries=2).
Methods
All return plain dicts and lists unless noted. Download options (to, offset, shift, fps, plain, sdh, clean, dual, lines, maxlines, mindur) work wherever they are listed.
| Method | Example |
|---|---|
search(id, season, episode, language, format, hi, source, release, filename, origin, video, hash, sort, limit, page, refresh) |
wyzie.search("tt0903747", season=1, episode=1, language="es") returns [] when nothing matches |
search_best(...) |
wyzie.search_best("tt0111161") returns one dict, or None on a 404 |
search_batch(items, best=False, **defaults) |
wyzie.search_batch(["tt0111161", 286217], language="en") |
download(url_or_result, **download_options) |
wyzie.download(results[0], to="srt", lines=42) returns text (JSON format too) |
download_best(id, **search_and_download_options) |
wyzie.download_best("tt0111161", language="en", to="vtt") |
with_download_options(url, **options) |
wyzie.with_download_options(results[0], to="vtt", shift="+2s") returns a URL, no request |
sources(key=True) |
wyzie.sources() |
languages() |
wyzie.languages() |
status(days=0) |
wyzie.status(days=7) |
quote(q, language, limit) |
wyzie.quote("may the force be with you") |
transcribe(media, format="srt", language, speakers, sounds, translate, cache, webhook, poll_interval) |
wyzie.transcribe("talk.mp3", format="json").json returns a TranscribeResult; long jobs are polled |
transcribe_url(url, ..., dry_run=False) |
job = wyzie.transcribe_url("https://example.com/ep.mp3") returns the 202 body |
get_transcribe(id, format="srt") |
wyzie.get_transcribe(job["jobId"]) returns a result, or None while running |
fix(media, subtitle, url, id, season, episode, language, format, retime, cache, webhook) |
wyzie.fix("movie.mkv", subtitle=srt_text, language="en") returns a FixResult |
extract(media, list_tracks, track, language, all_tracks, **download_options) |
wyzie.extract("subs.mks", list_tracks=True) gives a dict, one track a str, all_tracks=True zip bytes |
usage(days=30) |
wyzie.usage()["balance"] |
set_usage_webhook(url) |
wyzie.set_usage_webhook("https://example.com/balance") |
clear_usage_webhook() |
wyzie.clear_usage_webhook() |
media is bytes, a path, or a binary file object. Cloudflare caps a request body near 100 MB: for a big film send only the subtitle tracks (ffmpeg -i movie.mkv -map 0:s -c copy subs.mks).
Errors
Any non-2xx answer raises WyzieError with status, message, details, body (the full JSON error, including extras like topup or reset_at) and retry_after. Use err.is_rate_limited (429) and err.is_auth_error (401/403).
from wyzie_subs import WyzieError
try:
wyzie.search("tt0111161")
except WyzieError as err:
if err.is_rate_limited:
print("retry in", err.retry_after)
"No subtitles found" and "No matching release found" are not errors: search gives [], search_best gives None.
GETs are retried on network errors, 5xx and short 429s (Retry-After of 10 s or less) with backoff. POSTs (batch, transcribe, fix, extract) are never retried, because they are billed. Other network failures raise the underlying httpx exception.
Key safety
Use your API key on a server only. Do not ship it in a browser, mobile app or public repo; use a browser-safe wyzie-pub- key for front-end code. The client never logs or prints the key (it is redacted from httpx request logs and from repr), but a URL you build yourself with the key in it is yours to protect.
More
Metadata
Release files for wyzie-subs 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wyzie_subs-0.1.0.tar.gz | 15.7 kB | Without provenance | Details for wyzie_subs-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wyzie_subs-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for wyzie_subs-0.1.0-py3-none-any.whl |
Total release size: 30.3 kB
Release files / wyzie_subs-0.1.0.tar.gz
| Download URL | wyzie_subs-0.1.0.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aa2df751844177908cb4e0d7668d2ad82f5edce83c8904f1459b56c6222b8135
|
|
BLAKE2b-256 checksum How to use checksums |
6e9c19cd7f9d7fa28c15e3cd55faea2318a6f4efbcb138ac11ac2330ce4af88c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / wyzie_subs-0.1.0-py3-none-any.whl
| Download URL | wyzie_subs-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a6a84424655742d7fdcfb30259f6d2d23c1ff17e6768d161a0b4c6f453ea7c1c
|
|
BLAKE2b-256 checksum How to use checksums |
ada0847846e3c472613d3c92095dc3900f98c7cda30457ecdf57fbe3e864a541
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for wyzie-subs 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.