Skip to main content

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

Docs: https://docs.wyzie.io/subs/usage/clients

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)

Source distribution for wyzie-subs 0.1.0
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)

Table of built distributions (wheels) for wyzie-subs 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page