Metadata-Version: 2.5
Name: wyzie-subs
Version: 0.12.1
Summary: Python client for the Wyzie Subs API (subtitle search, download, transcribe, fix, extract, Censored).
Project-URL: Documentation, https://docs.wyzie.io/subs/usage/clients
Project-URL: Homepage, https://wyzie.io
License-Expression: MIT
License-File: LICENSE
Keywords: srt,subtitles,transcribe,wyzie
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# wyzie-subs

Python client for the [Wyzie Subs API](https://docs.wyzie.io/subs/usage/clients): subtitle search, download, sync, transcribe, fix and extract, plus Wyzie Censored. Sync and async, one dependency (`httpx`), Python 3.9+.

## Install

```
pip install wyzie-subs
```

You need an API key. Get a free one at [sub.wyzie.io/redeem](https://sub.wyzie.io/redeem). You can make up to 3 keys per account in the [dashboard](https://dash.wyzie.io) (API Keys > Extra Keys); they all share one balance and one set of limits.

## Quick start

```python
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.

```python
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; `download` and `with_download_options` also take `censor=True` and `censor_level` (masked downloads, free).

| Method | Example |
|---|---|
| `search(id, season, episode, language, format, hi, source, release, filename, origin, video, hash, sort, machine, 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")` |
| `sync_own_subtitle(subtitle, speech, covered=None, format=None)` | Wyzie Synced for your own SRT, VTT or ASS text (Pro, 60 requests only on success): `wyzie.sync_own_subtitle(srt_text, [[129.1, 131.2], [131.4, 133.6]])["content"]` is the retimed text; also `offset`, `fps`, `confidence`, `inSync`, `format`, `tried` (a `SyncOwnResult`). `format` srt, vtt or ass (default: the input's). No match is a `WyzieError` 422 |
| `transcribe(media, format="srt", language, speakers, sounds, translate, cache, webhook, poll_interval, on_job)` | `wyzie.transcribe("talk.mp3", format="json").json` returns a `TranscribeResult`; long jobs are polled |
| `transcribe_url(url, ..., dry_run=False, idempotency_key=None)` | `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, on_job)` | `wyzie.fix("movie.mkv", subtitle=srt_text, language="en")` returns a `FixResult` |
| `cancel_transcribe(id)` / `cancel_fix(id)` | `DELETE /transcribe/{id}`, `DELETE /fix/{id}`: `wyzie.cancel_transcribe(job["jobId"])` returns a `CancelResult` (see below) |
| `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()` |
| `censor(media, language, mode, sound, lists, words, pad_ms, cache, webhook, wait=True, level, allow, music, profile, review, audio_track, ranges_file, imdb, tmdb, idempotency_key)` | `wyzie.censor("ep.mp4", mode="bleep")["media"]` waits for the job, returns a `CensorJob` |
| `censor_url(url, ..., dry_run=False)` | `wyzie.censor_url("https://example.com/v.mp4", dry_run=True)["estimateRequests"]` |
| `get_censor_job(id)` / `wait_censor(id)` | `wyzie.wait_censor(job["id"])` polls until done, never posts again |
| `censor_mask(words or cues, duration, mode, sound, lists, add, pad_ms, level, allow, format, profile, language, sdh_cues, imdb, tmdb)` | Censored Live: `wyzie.censor_mask(cues=[{"start": 0, "end": 2, "text": "..."}])["ranges"]`; `format="edl"` or `"skp"` returns a filter file |
| `censor_filter(id, format)` / `censor_subtitle(id, format, marks, style)` | Free with the job's key: `wyzie.censor_filter(job["id"], format="edl")`, `wyzie.censor_subtitle(job["id"], marks=True)` (text) |
| `censor_edit_hits(id, keep, drop, add)` / `censor_render(id)` | A `review=True` job's hit list: `wyzie.censor_edit_hits(job["id"], drop=["h2"])`, then `wyzie.censor_render(job["id"])` (free) |
| `censor_transcript(id)` | A `review=True` job's words `{i, w, s, e, hit?}` for a transcript editor: `wyzie.censor_transcript(job["id"])`; bleep by place with `add=[{"word": i}]` (free) |
| `censor_batch(items, webhook, dry_run=False, **options)` / `get_censor_batch(id)` | Up to 20 links: `wyzie.censor_batch([{"url": "https://example.com/1.mp4"}], mode="bleep")["id"]`, then `wyzie.get_censor_batch(b["id"])["items"]` (free) |
| `censor_settings()` | `wyzie.censor_settings()["level"]` (a level or "custom"), `["available"]["levels"]` |
| `download_media(link)` | `wyzie.download_media(job["media"])` returns the file as `bytes`; an expired link is asked again once, then `LinkExpiredError` |

`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`).

## Censored

```python
# Bleep strong profanity and slurs (Pro: 95 requests a started minute, charged up front)
job = wyzie.censor("episode.mp4", mode="bleep", lists=["profanity_strong", "slurs"], words=["darn"])
print(job["count"], job["ranges"][:1])          # times, category and the word masked ("f***")
open("clean.mp4", "wb").write(wyzie.download_media(job["media"]))  # link valid 15 minutes, 20 downloads

# A link: price it first (free), start it, poll later
est = wyzie.censor_url("https://example.com/talk.mp4", dry_run=True)
started = wyzie.censor_url("https://example.com/talk.mp4", mode="mute", wait=False)
done = wyzie.wait_censor(started["id"])

# Free with the job's key: a filter file a player mutes from (the original file untouched), and a clean subtitle.
# edl is Kodi, MPlayer and mpv (save it as <video name>.edl), skp is VideoSkip, json (default) is {count, ranges}.
# The subtitle masks the words ("f***"); marks=True adds a [bleep] caption over each range. 409 while the job
# runs; censor_subtitle is a 404 for jobs from before transcripts were kept.
open("episode.edl", "w").write(wyzie.censor_filter(done["id"], format="edl"))
open("episode.clean.srt", "w").write(wyzie.censor_subtitle(done["id"], marks=True))

# Strictness instead of lists: lenient, moderate (default), strict (also damn, hell, crap) or super_strict
# (also gosh, darn, heck and insults). "rape" also catches raped, raping, rapes and rapist; "=word" is that
# word only. allow adds to the account's Never Censor list. level and lists together raise ValueError.
strict = wyzie.censor("episode.mp4", level="strict", words=["rape", "=ass"], allow=["hell"])

from wyzie_subs import CENSOR_LEVELS, level_of
level_of(["profanity_severe", "slurs"])  # "lenient"; any other set is "custom"

# Audience presets: kids (= super_strict), teen (damn, hell, crap and "oh my god" stay), family (damn, hell
# and "oh my god" stay). Half lists: mild_damn_hell, mild_crude (of profanity_mild), blasphemy_exclamations,
# blasphemy_curses (of blasphemy); a half reports its parent's category.
teen = wyzie.censor("episode.mp4", level="teen")

# Loud music mode: also listen to the voices with the music taken out, for words music hides (160 more a
# minute), and split two voices talking at once to hear the quieter one (125 more a minute): 380 a minute in
# all, up front. The 160 comes back when the gaps between words are quiet or the pass fails (75 back when the
# separation is cached, 85 when its recognition is): job["music"] is used, not_needed or failed. Of the 125,
# 85 comes back for each minute with no overlap sent to recognition, all 125 when the pass fails:
# job["overlap"] is used, not_needed or failed. None keeps the account's setting. A blocked word also blocks
# the forms AI finds for it (English, free). A word a recogniser often mishears ("pitch meeting" heard as
# a swear) is left alone when the words around it give the real word away; your blocked words always count.
loud = wyzie.censor("episode.mp4", music=True)

# Censored review: stop at the hit list, change it, then render it (free)
r = wyzie.censor("episode.mp4", review=True, profile="Kids")
print(r["status"], r["hits"])  # review [{id, word: "f***", start, end, category, confidence, keep}]
wyzie.censor_edit_hits(r["id"], drop=["h2"], add=[{"start": 12.5, "end": 13}])
wyzie.censor_render(r["id"])
rendered = wyzie.wait_censor(r["id"])

# Censored batch: up to 20 links, shared options, each item its own job
items = [{"url": "https://example.com/ep1.mp4"}, {"url": "https://example.com/ep2.mp4", "mode": "mute"}]
quote = wyzie.censor_batch(items, mode="bleep", dry_run=True)  # free
batch = wyzie.censor_batch(items, mode="bleep", webhook="https://example.com/hook")
progress = wyzie.get_censor_batch(batch["id"])  # status running | done | stopped; items[i] status, id, media
```

Censored jobs are Pro and charged up front for the whole job, refunded if it fails on our side. Jobs are polled every `poll_interval` seconds (default 5), 1.5x longer each time up to `max_poll_interval` (default 30). A file up to 100 MB is read into memory and sent in one request, as with `transcribe`; a larger one goes in chunks from disk (below), or send a link to `censor_url`.

`review=True` (`review=1`) is charged as any job but stops once the words are matched: the job answers status `"review"` with `hits` (`word` masked; `confidence` 1 heard in the mix, 0.6 only in the `music=True` voices stem), kept until `expiresAt` (24 hours; the rendered file an hour); the wait stops there. `censor_edit_hits(id, keep, drop, add)` changes the list (at most 500 added ranges; 409 outside review) and `censor_render(id)` renders it once, free (a failed render goes back to review with `error`). `profile="Kids"` uses a named profile from dash.wyzie.io Censored (any case): its lists replace the account's, its words and allow add to them; an unknown name is a 400, nothing charged. `censor_settings()["profiles"]` lists them (word counts, never the words). 23 languages have their own preset lists (`censor_settings()["available"]["languages"]`; pt-BR uses pt, zh-TW uses zh; others use the English lists): jobs pick them from `language` or the detected language, and `censor_mask(..., language="es")` from the language you send. Download links from `search` already carry `lang=`, so `censor=1` on them masks with that language's lists. `download(..., censor=True, censor_level="strict")` (`censor=1`, `level=`) masks matched words in any download, first letter kept (`f***`), free; the answer's `X-Censor` header is `on`, `off` or `ignored`.

`censor_batch(items, webhook, dry_run, **options)` posts to `/censor/batch`: 1 to 20 links (uploads can't be batched), each item its own `POST /censor/url` job at the same price, charged when it starts, two at a time a key; an item's own options win over the shared ones. The first refused charge (402) stops the batch (`stopped: "no_balance"`): that item and the rest end `skipped_no_balance`, uncharged. A failed item is refunded by its own job; an unsupported link fails uncharged. `webhook` gets one `batch.done` call. `dry_run=True` prices each item (media over 4 hours: `supported: False`). `get_censor_batch(id)` is free, only for the key that started it, kept 24 hours.

### Censored: audio tracks, checks before any charge, links, header auth

```python
from wyzie_subs import LinkExpiredError, WyzieError

# Censor the French track (a number works too: 0 is the first, the default); every other track is kept
try:
    job = wyzie.censor_url("https://example.com/film.mkv", audio_track="fr")
except WyzieError as e:
    print(e.reason, e.charged)  # "audio_track_not_found", False (also drm, no_audio, silent, music_only, too_long...)
print(job["audio_track"], job.get("dropped"), job.get("warnings"))  # 1, ["audio 2 (dts, fre)"], ["surround: 5.1 mixed down"]

try:
    data = wyzie.download_media(job["media"])  # a stale link is asked again once with the key
except LinkExpiredError:
    data = wyzie.download_media(wyzie.get_censor_job(job["id"])["media"])  # file kept an hour
```

`audio_track` (on `censor`, `censor_url` and `censor_batch` items or options) picks the audio track to censor: its number (0 is the first and the default) or its language code (`"fr"`, `"fre"`). The output keeps every audio and subtitle track and the chapters; only the chosen track is censored. An mp4 leaves out codecs it can't hold, listed in the result's `dropped` (`"audio 2 (dts, fre)"`); `audio_track` on the result is the track censored. An unknown track on `censor` is a 400 with `reason` `"audio_track_not_found"`, nothing charged; on `censor_url` it is found when the file is fetched and the job fails with the charge given back.

Files are checked before any charge. A refusal is a 400, 413 or 422 `WyzieError` with `reason` (`PROBE_REFUSALS`: unreadable, drm, no_audio, unsupported_audio_codec, bad_duration, too_long, bad_audio, too_many_streams, silent, music_only, audio_track_not_found) and `charged` False. The 202 and the result may carry `warnings`, each `"name: text"` (`JOB_WARNINGS`: multiple_audio_tracks, surround, variable_frame_rate, quiet_audio, dropped_tracks).

Result links (`media`) last 15 minutes and 20 full downloads; the file is kept an hour. Past that a link answers 403 with `error` "link_expired" or 429 with `error` "link_exhausted" (also the header `X-Wyzie-Link: expired|exhausted`), and `refresh` / `X-Wyzie-Refresh`: the job URL that gives a fresh link. The client matches on those, never on the message text. `download_media` then asks the job (the `refresh` URL when it is on the client's own API host, since the key goes there; else the link's own `GET /censor/{id}`) for a fresh link and tries once more; still refused (or no key on the client) raises `LinkExpiredError`, a `WyzieError` with `link_state` ("expired" or "exhausted") and `refresh`. A failed refresh (the job gone after its hour, the key refused) raises that refresh's `WyzieError`. Download soon after the job is done.

Every Censored and upload call, and every poll and cancel of a Transcribe or Fix job, sends the key as `Authorization: Bearer <key>`, never in the URL or body. Other routes (search, download, the transcribe start...) still take `?key=`.

### Censored: transcript editing, caption sound cues, subtitle styles

```python
# A review=True job's words: bleep any word by its place, or a run of words
rv = wyzie.censor_url("https://example.com/talk.mp4", review=True)
t = wyzie.censor_transcript(rv["id"])  # {id, state, count, words: [{i, w, s, e, hit?}]}
wyzie.censor_edit_hits(rv["id"], add=[{"word": 12}, {"from": 40, "to": 42}])
wyzie.censor_render(rv["id"])

# Censored Live: also mute what the captions announce ("[screaming]", "[gunfire]")
live = wyzie.censor_mask(cues=[{"start": 3, "end": 5, "text": "[screaming]"}], sdh_cues=["screaming"])  # or True for all

# The clean transcript: [bleep] in place of the word, as plain text
txt = wyzie.censor_subtitle(job["id"], format="txt", style="bleep")
```

`censor_transcript(id)` answers a review job's words: `i` (its place), `w`, `s` and `e` (seconds) and `hit` (the hit id) on a word a hit covers, which comes masked. Only the key that started the job, only while it is in review; free. A review is kept 24 hours (the rendered file an hour). `censor_edit_hits` `add` takes `{start, end}` seconds, `{word: i}` or `{from: i, to: j}` (word places, inclusive); a bad place is a 400.

`censor_mask(..., sdh_cues=True)` (or a list of `SDH_CUE_KINDS`: gunfire, screaming, moaning, explicit_music) also answers the spans the captions themselves announce in brackets as ranges of category `"sdh_cues"`: `word` is the masked annotation, `mask` places it. Off by default; a bad kind is a 400, nothing charged.

`censor_subtitle(id, format, style, marks)`: `format` srt (default), vtt or txt (plain text, one cue a line); `style` stars (default, "f***") or bleep ("[bleep]" / "[muted]" in place of the word).

### Censored: your own ranges, per-title words, safe retries, the ledger

```python
from pathlib import Path

# Silence the ranges of an EDL, a VideoSkip .skp or a censor_filter JSON: no speech recognition, render price only
job = wyzie.censor_url("https://example.com/film.mp4", ranges_file=Path("film.edl"))

# Name the title: the words you never want muted for it (dash.wyzie.io, Censored, per title) are added to allow
job = wyzie.censor_url("https://example.com/film.mp4", imdb="tt0111161")  # or tmdb=603

# Safe to retry: the same idempotency_key gives back the first answer, never a second job or charge
job = wyzie.censor_url("https://example.com/ep1.mp4", idempotency_key="ep1-strict", wait=False)
print(wyzie.last_replayed)  # True when the API answered from the key

print(wyzie.get_censor_job(job["id"])["ledger"])  # {"charged": 95, "refunded": 0, "net": 95, "reason": None}
```

`ranges_file` on `censor` (sent as a multipart field next to the file) and `censor_url` takes an EDL, a VideoSkip .skp or the JSON `censor_filter` answers (the same files it exports; up to 2 MB and 20000 ranges): text, bytes or a `pathlib.Path`. Its ranges are silenced with no speech recognition, priced as a render only (10 a started minute). It can't be combined with `music` or `review`: a 400 "Invalid ranges_file", as is a broken line (the error names it); nothing charged.

`imdb` ("tt0111161") or `tmdb` (603) on `censor`, `censor_url` and `censor_mask` names the title. The account keeps per-title Never Censor words (up to 100 titles, 50 words each), set in dash.wyzie.io under Censored or through the account's media prefs (`censor.titles`). A request that names the title adds that title's words to its `allow`. A bad id is a 400 "imdb is an IMDb id like tt0111161, tmdb is a TMDB number like 603".

`censor` and `censor_url` send an `Idempotency-Key` header on every call: your `idempotency_key` (1 to 100 letters, digits and `_ . : -`), else a random one made for that call. The same key from the same API key again replays the first answer (`last_replayed` is True) with no second job and no second charge; a repeat while the first still runs is a 409 (retry after 5 s). Answers are kept 24 hours, and an error frees the key. The API also takes these POSTs without a key, but the client always sends one, dry runs too, always a fresh one (a quote never shares a key with the real call). The client retries these POSTs by itself (network errors, 5xx, a 429 with a short `Retry-After`, a 409 after its `Retry-After`; up to `retries` more times, 2 by default) with the same key and the same bytes, so a retry never starts a second job. A key sent again with a different request is a 422 `WyzieError` with `is_idempotency_key_reused` True (reason `idempotency_key_reused`), nothing charged: use a new key.

`get_censor_job` carries `ledger`: `{charged, refunded, net, reason}`, where `reason` is why the job failed, "refund pending: ..." while a refund is retried, or None.

### Censored: files over 100 MB (resumable upload)

One request carries at most 100 MB. `censor`, `transcribe`, `fix` and `extract` send a larger file (a path, or a seekable binary file) in chunks by themselves (`POST /upload`, 8 MB chunks, SHA-256 checked) and start the job with its `upload_id`; the price is the same. The file is read a chunk at a time, never whole into memory. Use `upload_large` yourself to resume after a restart:

```python
job = wyzie.censor("movie.mkv", level="strict")  # over 100 MB: chunked upload, then the job

# Resume after a crash: save the id, pass it back; only the missing bytes are sent.
uid = wyzie.upload_large("movie.mkv", upload_id=saved, on_upload_id=save, on_progress=lambda got, size: print(got, size))
```

A wrong offset, a cut-off chunk or a dropped connection carries on from what the server has. A file that changed while it was sent is a 422 `WyzieError` with `is_hash_mismatch` (the upload is deleted: send it again); one that got shorter, or an upload whose `received` does not move for 3 rounds, stops with a `WyzieError` at once. `delete_upload(id)` drops an unused one; an upload is used up once a job starts with it and deleted after 6 idle hours. Paid keys; at most 3 unfinished uploads a key. `Wyzie(key, large_upload_bytes=...)` moves the switch point. A file object that can't seek has no known size, so it always goes in one request. With chunks, `ranges_file` (censor) goes as JSON text with the job start (5 MB); `transcribe`, `fix` and `extract` send every option in the query, and `fix` then takes the subtitle as `url` or `id` only (a subtitle file raises ValueError). `transcribe` and `fix` also send an `Idempotency-Key` (`idempotency_key=`, else random per call) and are retried with it, as `censor`. `sync_own_subtitle` sends speech segments, not a media file, so /sync's `upload_id` is not used here.

## 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). Censored adds `err.is_product_off` (403 `PRODUCT_OFF`: the product is off for the account, turn it on in dash.wyzie.io), `err.is_payment_required` (402) and `err.is_blocked_site` (422: the site blocks server fetching, use the browser extension there); nothing is charged in any of these.

A part of the API that is not open yet answers 404 `{"error": "feature_unavailable", ...}` and raises `FeatureUnavailableError` (a `WyzieError`), nothing charged. A plain 404 stays a `WyzieError`.

```python
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`.

Every scraped result carries `rank` (`{"score": 0-100, "reasons": [...]}`: 100 minus penalties such as `image_format`, `extra_file` (a song, trailer or sign-language part filed under the title), `sdh`, `machine_translated`, `language_variant`, `unreliable_source`) and results come in rank order. `sort="quality"` keeps rank order with `video` / `hash` too (they otherwise put the best release match first); `sort="downloads"` lists the most downloaded first.

Every result has `machine`: `True` for a machine-made file (a source's machine translation, or one of our AI rows, which also have `ai: True`). `machine="exclude"` leaves those out before paging (`search_batch` takes it per item or as a default); when only machine-made files matched, `search` gives `[]`. Default `"include"`, no extra cost.

```python
human = wyzie.search("tt0816692", language="fr", machine="exclude")
```

Transcribe costs 85 a started minute; `speakers=True` is 88 a minute plus 3 a file in any language (no `language` needed; a 503 before any charge when speaker labels are unavailable). A recognition cache hit costs 1 a minute of recognition (4 with speakers), the rest refunded.

GETs, and `cancel_transcribe` / `cancel_fix` (a repeat cancel answers the same), are retried on network errors, 5xx and short 429s (`Retry-After` of 10 s or less) with backoff. POSTs (batch, extract and the other billed calls) are never retried, because they are billed, except `censor`, `censor_url`, `transcribe`, `transcribe_url` and `fix`: their `Idempotency-Key` makes a retry safe.

## Cancel a running job

`transcribe` and `fix` pass the job id to `on_job` when the work runs as a job; `transcribe_url` returns it as `jobId`. Pass it to `cancel_transcribe` or `cancel_fix`:

```python
job = wyzie.transcribe_url("https://example.com/ep.mp3", idempotency_key="order-42")
res = wyzie.cancel_transcribe(job["jobId"])  # {"id", "status": "cancelled", "refunded", "charged", "refundPending"?}
```

Before recognition starts everything is refunded. During recognition the started minutes already recognised stay charged (85 each, plus a finished fallback proxy fetch) and the rest is refunded. Cancelling again answers the same; `refundPending` means the refund hasn't landed yet, so cancel again later. Polling a cancelled job raises `WyzieError` 410 with `is_cancelled` True. A job that already ended, or whose recognition finished, raises a 409 with `is_nothing_to_cancel` True and `cancel_status` `"done"`, `"failed"` or `"finishing"` (for `"finishing"`, keep polling: the result is on its way). Another key's job is a 404. Batch jobs can't be cancelled. `transcribe_url` sends an `Idempotency-Key` (yours, or a random one), so a retry after a lost answer gets the first 202 back with no second charge.

## Repeat downloads

A repeat `download` of the same subtitle (same link path, season and episode) by the same key within 6 hours of its paid download, with options it hasn't been served with yet in that window (`sdh`, `clean`, `plain`, `to`, `shift`, encoding, format), is free: `last_cost` is 0. Options already served in the window cost 1 again, and at most 20 repeats per subtitle are free in a window. 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, with `share=` and link `t=` tokens, and from `repr`; Censored and upload calls send it in the `Authorization` header), but a URL you build yourself with the key in it is yours to protect.

## More

Client guide: https://docs.wyzie.io/subs/usage/clients

## Links

[Docs](https://docs.wyzie.io) · [Support](https://sub.wyzie.io/contact) · [Status](https://sub.wyzie.io/status) · [News](https://sub.wyzie.io/news) · [Terms](https://sub.wyzie.io/legal/terms) · [Privacy](https://sub.wyzie.io/legal/privacy)

API help: support@wyzie.io. Business: hello@wyzie.io.
