tldw-client 0.2.6__tar.gz

tldw_client-0.2.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tldw.sh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tldw_client-0.2.6/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: tldw-client
+Version: 0.2.6
+Summary: Dependency-free tldw.sh asynchronous analysis client
+Requires-Python: >=3.10
+License-Expression: MIT
+License-File: LICENSE
+Keywords: tldw,video,analysis,agents,mcp,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://tldw.sh
+Project-URL: Documentation, https://tldw.sh/docs
+Description-Content-Type: text/markdown
+
+# tldw.sh Python client
+
+A synchronous Python 3.10+ client with no runtime dependencies.
+
+```sh
+python -m pip install tldw-client
+```
+
+You can instead install the versioned wheel from your operator's `/agents` page.
+Download it, verify it against the SHA-256 checksum shown on that page, then
+install the verified local file:
+
+```sh
+curl -fsSLo tldw_client-0.2.6-py3-none-any.whl \
+  'https://YOUR_APP_ORIGIN/downloads/tldw_client-0.2.6-py3-none-any.whl' &&
+  echo 'SHA256_FROM_YOUR_AGENTS_PAGE  tldw_client-0.2.6-py3-none-any.whl' | shasum -a 256 -c - &&
+  python -m pip install ./tldw_client-0.2.6-py3-none-any.whl
+```
+
+The package is imported as `tldw_client`. Only `tldw-client` on PyPI and your
+operator's verified download are this client; similarly named projects are not.
+
+Use your deployment's API origin and a scoped **tldw API key**, never a model
+provider key. Signup and one-time human verification happen in the web app.
+REST, MCP and plugins share 100 monthly Free caption/text credits, Hobby/Pro
+limits and purchased credits. Polling does not create another analysis or reset your allowance.
+
+```python
+import os
+from tldw_client import TldwClient, TldwTimeoutError
+
+client = TldwClient(
+    api_url=os.environ["TLDW_API_URL"], token=os.environ["TLDW_API_TOKEN"]
+)
+receipt = client.submit_analysis(
+    "https://youtu.be/VIDEO_ID",
+    instructions="Extract the argument and flag weak evidence.",
+    idempotency_key="my-persisted-request-001",
+)
+print({"job_id": receipt["job_id"]})  # Persist before waiting.
+try:
+    job = client.wait_for_job(receipt["job_id"], timeout_seconds=180)
+    result = client.get_summary(job["summary_id"])
+    print(result["content"])
+except TldwTimeoutError as error:
+    print({"job_id": error.job_id, "status": "resume-polling-later"})
+```
+
+`analyze(media, instructions=..., idempotency_key=..., timeout_seconds=180)`
+combines submission, polling and result retrieval, returning a dictionary with
+`receipt`, `job` and `summary`. A failure after acceptance retains `job_id` and
+`receipt`; unknown submission errors retain `idempotency_key`. Reuse that key
+with exactly the same source/instructions after an uncertain network outcome.
+
+Other methods:
+
+- `get_job(job_id)`, `get_summary(summary_id)`, `get_usage()` (`account:read`).
+- `compare_tiktoks(urls, instructions=..., idempotency_key=...)` returns an
+  accepted comparison view. Persist its `id` before waiting.
+- `get_comparison(id)`, `wait_for_comparison(id, timeout_seconds=180)` return
+  the unwrapped comparison view. Completed output needs `summaries:read`.
+
+Polling accepts `on_progress(resource)` and `poll_interval_seconds` (default
+1.5, minimum 0.25). It honors larger server polling hints and Retry-After.
+Waits have a finite one-hour maximum; each HTTP operation has a separate
+30-second budget, configurable through `request_timeout_seconds` (maximum 120).
+Pass a `threading.Event` as `cancel_event` to cooperatively stop waiting. The
+current bounded HTTP read can finish before cancellation is observed. Stopping
+a wait never sends a job cancellation; accepted work remains on the server.
+
+`TldwError` exposes `code`, `status`, `request_id`, `retry_after_seconds` and
+durable IDs where known. `TldwJobError` marks failed/canceled work. The SDK never
+follows server-supplied URLs or redirects, ignores environment proxies, validates
+resource UUIDs and limits API responses to 8 MiB. Transient retries preserve the
+same serialized body and idempotency key. Scope, signup and trial denials require
+caller action and are not automatically resubmitted.
+
+Credentials must come from your secret manager or private environment, never a
+prompt, checked-in file or command argument. The client does not print keys.
+Anonymous mode requires explicit loopback development access:
+`TldwClient(api_url="http://localhost:8000", allow_anonymous=True)`. It grants no
+admin access. Production uses HTTPS and a scoped key.
+
+For maintainers, `python build_wheel.py dist` creates the wheel offline using
+only the standard library. The PEP 517 backend supports both source distributions
+and wheels with no build dependencies. A standard build frontend can run
+`python -m build` to build the source archive and rebuild its wheel in isolation.
+Run `python -m unittest discover -s tests` from this source directory to check
+transport, polling, billing-safe retries and packaging. Releases are published
+from `main` by the monorepo's manual release workflow through PyPI trusted
+publishing; a successful local build publishes nothing.
+
+## Extract original source without generated analysis
+
+```python
+receipt = client.submit_transcript(
+    "https://youtu.be/VIDEO_ID",
+    transcription="never",
+    max_credits="30.00",
+    idempotency_key="original-source-001",
+)
+print(receipt["job_id"])  # Persist before waiting.
+job = client.wait_for_job(receipt["job_id"])
+original = client.get_saved_transcript_page(job["transcript_id"], limit=100)
+# Follow original["next_offset"] for more source content.
+```
+
+`submit_transcript` posts to `POST /v1/transcripts` and always returns a durable
+accepted receipt. It never requests a summary or invokes an LLM. Completed
+transcript jobs have `output_mode="transcript"`, a `transcript_id`, and no
+`summary_id`. `extract_transcript(media, ...)` combines submission, polling and
+a full source read, returning `receipt`, `job` and `transcript`; timeout and
+source-permission errors retain the accepted receipt and job ID.
+
+Use `submit_transcript(upload_id=...)` for your parsed subtitle upload.
+`preferred_caption_languages` selects original captions. Spending/ASR controls
+and `refresh_source` are supported, but analysis instructions are not.
+Submission needs `jobs:write`, polling `jobs:read`, and source reads
+`summaries:read`; no account-read scope is needed. New transcript-only jobs
+retain normal credit rates and ASR consent/caps. If you already have a saved
+transcript ID, read it directly: saved-source reads start no processing job,
+invoke no LLM and charge no processing credits.
+
+## Summary and transcript are separate reads
+
+After the job completes, use its `summary_id` to retrieve generated output and
+original source independently. Both calls require `summaries:read` and account
+ownership. Neither starts another analysis, transcription or processing-credit
+charge. The summary response includes transcript metadata, not the full source.
+
+```python
+summary = client.get_summary(job["summary_id"])
+transcript = client.get_transcript(job["summary_id"])
+print(summary["content"]["answer"])
+original_text = (
+    "\n".join(segment["text"] for segment in transcript["segments"])
+    if transcript["timed"]
+    else transcript["text"]
+)
+print(original_text)
+```
+
+REST uses `GET /v1/summaries/{id}` and `GET /v1/summaries/{id}/transcript`.
+MCP uses `get_summary` and paginated `get_transcript`. Timed YouTube/TikTok
+sources expose `segments`; text/X sources expose `blocks` and `text`. X video
+caption blocks retain `start_s` / `end_s` alongside separate untimed post context.
+The saved source stays in its original language when requesting a translated summary.
+
+## Saved transcription inbox
+
+`list_transcripts` returns the latest 50 distinct sources requested by your account,
+including sources saved before an analysis failed. It reads metadata only and does
+not mark anything read. All library, source and read-state calls require `summaries:read`.
+
+```python
+page = client.list_transcripts(limit=50, unread_only=True)
+for item in page["items"]:
+    print(item["id"], item["video"]["title"], item["last_requested_at"])
+    source = client.get_saved_transcript_page(item["id"], offset=0, limit=100)
+    # Follow source["next_offset"] for additional content. Mark only when ready.
+    client.mark_transcript_read(item["id"], read=True)
+```
+
+Pass `cursor=page["next_cursor"]` with the same filters for older entries. `since`
+is inclusive and `until` exclusive, using ISO 8601 timestamps against
+`last_requested_at`. `read=False` marks a source unread again. Reading source
+content through REST/MCP/SDK never implicitly changes its read state.
+Use `get_saved_transcript_metadata(id)` to read one source’s title, dates and
+unread status directly, including sources outside the current catalog page. This
+GET does not load the transcript body or start a processing job.
+
+X posts, X video captions and articles reuse an owned source snapshot for 24 hours.
+Use `submit_analysis(..., refresh_source=True)` to retrieve current source content.
+YouTube/TikTok keep reusing saved transcripts; another brief does not redownload
+audio or repeat transcription when a usable source already exists.
+
+## X video captions and output language
+
+Pass an X post URL directly. Default `scope=auto` detects one attached video and
+analyzes its available captions plus separately labeled post context when the
+deployment enables X video extraction. You do not need a subtitle URL or a
+separate provider key. Use `{"type":"x","url":"YOUR_X_POST_URL","scope":"post"}`
+only for post text alone; thread scope does not recursively analyze its videos.
+
+```python
+receipt = client.submit_analysis(
+    "https://x.com/hamptonism/status/2071631335836225751",
+    instructions="Summarize the spoken content in Spanish. Keep it concise and avoid repetition.",
+    transcription="never",
+    idempotency_key="x-video-spanish-001",
+)
+print({"job_id": receipt["job_id"]})  # Persist before waiting.
+job = client.wait_for_job(
+    receipt["job_id"],
+    on_progress=lambda state: print(
+        {"status": state["status"], "progress": state["progress"]}
+    ),
+)
+result = client.get_summary(job["summary_id"])
+print(result["content"]["answer"])
+```
+
+The response is a durable job receipt. Save its ID before waiting; a timeout does
+not cancel the job. Use a fresh stable key for a different brief or language and
+reuse the exact body/key after an uncertain submission. Without instructions,
+the service produces a concise summary. A translated summary is generated text
+inside the same schema-3 result, not dubbed audio, a translated video or an SRT
+translation; the original captions remain saved separately.
+
+Captioned X videos use actual video duration at 1 credit/minute under normal
+rounding (128.197 seconds = 2.2 credits), not the post's reading time. Missing
+captions fail explicitly with no customer processing charge; X audio
+transcription and visual analysis are not enabled, even with `if_needed`.
+
+## Credit controls
+
+Captions, text and existing cached transcripts cost **1 credit per source minute**.
+Fresh audio transcription costs **3 credits per source minute** and requires an
+eligible paid plan or server-confirmed billing exemption, plus explicit `transcription: "if_needed"` (Python:
+`transcription="if_needed"`). The default `never` fails with a clear error when
+new transcription would be necessary. Supplying `forceAsr: true` /
+`force_asr=True` also requires that explicit permission.
+
+Use `maxCredits: "30.00"` in JavaScript or `max_credits="30.00"` in Python to cap
+a job. The server validates affordability before new transcription. The cap is
+positive, at most 1,000,000 credits, and has at most two decimal places. It is
+required for ordinary paid accounts when `transcription` is `if_needed`. Preserve
+these controls in the same idempotent request body on retries. Jobs expose
+`credits.estimated`, `reserved`, `final`, the billing class/rate and real source
+duration; polling does not create another processing charge.
+
+For `compareTikToks` / `compare_tiktoks`, the cap covers all distinct supplied
+clips: each receives an equal share rounded down to 0.01 credit. Unused shares
+are not redistributed. Comparison aggregation adds no customer processing credits.
+Source minutes round up to 0.1 minute with a 0.5-minute minimum before the rate
+multiplier. Raw text uses estimated reading minutes.
+
+Free includes 100 credits per month for captions/text, Hobby costs USD20/month
+with 1,000 credits, and Pro costs USD99/month with 5,000 credits. Included
+allowance is used first, then purchased credits, which do not expire. Reading
+account usage does not buy credits or change plans.
+
+Server-confirmed billing exemption: the authenticated server decides whether an account is exempt. Exempt accounts may omit a credit ceiling and do not incur customer-credit charges; explicit transcription permission and resource/provider limits still apply. Ordinary paid accounts allowing fresh transcription must supply a ceiling or receive `TRANSCRIPTION_NOT_ALLOWED` (HTTP 422); `MAX_CREDITS_EXCEEDED` (HTTP 422) means a supplied ceiling is invalid or below the required charge. Clients validate supplied values, then pass requests through without fetching extra account scopes or inferring privileges from names, roles, or key prefixes.

tldw_client-0.2.6/README.md

@@ -0,0 +1,243 @@
+# tldw.sh Python client
+
+A synchronous Python 3.10+ client with no runtime dependencies.
+
+```sh
+python -m pip install tldw-client
+```
+
+You can instead install the versioned wheel from your operator's `/agents` page.
+Download it, verify it against the SHA-256 checksum shown on that page, then
+install the verified local file:
+
+```sh
+curl -fsSLo tldw_client-0.2.6-py3-none-any.whl \
+  'https://YOUR_APP_ORIGIN/downloads/tldw_client-0.2.6-py3-none-any.whl' &&
+  echo 'SHA256_FROM_YOUR_AGENTS_PAGE  tldw_client-0.2.6-py3-none-any.whl' | shasum -a 256 -c - &&
+  python -m pip install ./tldw_client-0.2.6-py3-none-any.whl
+```
+
+The package is imported as `tldw_client`. Only `tldw-client` on PyPI and your
+operator's verified download are this client; similarly named projects are not.
+
+Use your deployment's API origin and a scoped **tldw API key**, never a model
+provider key. Signup and one-time human verification happen in the web app.
+REST, MCP and plugins share 100 monthly Free caption/text credits, Hobby/Pro
+limits and purchased credits. Polling does not create another analysis or reset your allowance.
+
+```python
+import os
+from tldw_client import TldwClient, TldwTimeoutError
+
+client = TldwClient(
+    api_url=os.environ["TLDW_API_URL"], token=os.environ["TLDW_API_TOKEN"]
+)
+receipt = client.submit_analysis(
+    "https://youtu.be/VIDEO_ID",
+    instructions="Extract the argument and flag weak evidence.",
+    idempotency_key="my-persisted-request-001",
+)
+print({"job_id": receipt["job_id"]})  # Persist before waiting.
+try:
+    job = client.wait_for_job(receipt["job_id"], timeout_seconds=180)
+    result = client.get_summary(job["summary_id"])
+    print(result["content"])
+except TldwTimeoutError as error:
+    print({"job_id": error.job_id, "status": "resume-polling-later"})
+```
+
+`analyze(media, instructions=..., idempotency_key=..., timeout_seconds=180)`
+combines submission, polling and result retrieval, returning a dictionary with
+`receipt`, `job` and `summary`. A failure after acceptance retains `job_id` and
+`receipt`; unknown submission errors retain `idempotency_key`. Reuse that key
+with exactly the same source/instructions after an uncertain network outcome.
+
+Other methods:
+
+- `get_job(job_id)`, `get_summary(summary_id)`, `get_usage()` (`account:read`).
+- `compare_tiktoks(urls, instructions=..., idempotency_key=...)` returns an
+  accepted comparison view. Persist its `id` before waiting.
+- `get_comparison(id)`, `wait_for_comparison(id, timeout_seconds=180)` return
+  the unwrapped comparison view. Completed output needs `summaries:read`.
+
+Polling accepts `on_progress(resource)` and `poll_interval_seconds` (default
+1.5, minimum 0.25). It honors larger server polling hints and Retry-After.
+Waits have a finite one-hour maximum; each HTTP operation has a separate
+30-second budget, configurable through `request_timeout_seconds` (maximum 120).
+Pass a `threading.Event` as `cancel_event` to cooperatively stop waiting. The
+current bounded HTTP read can finish before cancellation is observed. Stopping
+a wait never sends a job cancellation; accepted work remains on the server.
+
+`TldwError` exposes `code`, `status`, `request_id`, `retry_after_seconds` and
+durable IDs where known. `TldwJobError` marks failed/canceled work. The SDK never
+follows server-supplied URLs or redirects, ignores environment proxies, validates
+resource UUIDs and limits API responses to 8 MiB. Transient retries preserve the
+same serialized body and idempotency key. Scope, signup and trial denials require
+caller action and are not automatically resubmitted.
+
+Credentials must come from your secret manager or private environment, never a
+prompt, checked-in file or command argument. The client does not print keys.
+Anonymous mode requires explicit loopback development access:
+`TldwClient(api_url="http://localhost:8000", allow_anonymous=True)`. It grants no
+admin access. Production uses HTTPS and a scoped key.
+
+For maintainers, `python build_wheel.py dist` creates the wheel offline using
+only the standard library. The PEP 517 backend supports both source distributions
+and wheels with no build dependencies. A standard build frontend can run
+`python -m build` to build the source archive and rebuild its wheel in isolation.
+Run `python -m unittest discover -s tests` from this source directory to check
+transport, polling, billing-safe retries and packaging. Releases are published
+from `main` by the monorepo's manual release workflow through PyPI trusted
+publishing; a successful local build publishes nothing.
+
+## Extract original source without generated analysis
+
+```python
+receipt = client.submit_transcript(
+    "https://youtu.be/VIDEO_ID",
+    transcription="never",
+    max_credits="30.00",
+    idempotency_key="original-source-001",
+)
+print(receipt["job_id"])  # Persist before waiting.
+job = client.wait_for_job(receipt["job_id"])
+original = client.get_saved_transcript_page(job["transcript_id"], limit=100)
+# Follow original["next_offset"] for more source content.
+```
+
+`submit_transcript` posts to `POST /v1/transcripts` and always returns a durable
+accepted receipt. It never requests a summary or invokes an LLM. Completed
+transcript jobs have `output_mode="transcript"`, a `transcript_id`, and no
+`summary_id`. `extract_transcript(media, ...)` combines submission, polling and
+a full source read, returning `receipt`, `job` and `transcript`; timeout and
+source-permission errors retain the accepted receipt and job ID.
+
+Use `submit_transcript(upload_id=...)` for your parsed subtitle upload.
+`preferred_caption_languages` selects original captions. Spending/ASR controls
+and `refresh_source` are supported, but analysis instructions are not.
+Submission needs `jobs:write`, polling `jobs:read`, and source reads
+`summaries:read`; no account-read scope is needed. New transcript-only jobs
+retain normal credit rates and ASR consent/caps. If you already have a saved
+transcript ID, read it directly: saved-source reads start no processing job,
+invoke no LLM and charge no processing credits.
+
+## Summary and transcript are separate reads
+
+After the job completes, use its `summary_id` to retrieve generated output and
+original source independently. Both calls require `summaries:read` and account
+ownership. Neither starts another analysis, transcription or processing-credit
+charge. The summary response includes transcript metadata, not the full source.
+
+```python
+summary = client.get_summary(job["summary_id"])
+transcript = client.get_transcript(job["summary_id"])
+print(summary["content"]["answer"])
+original_text = (
+    "\n".join(segment["text"] for segment in transcript["segments"])
+    if transcript["timed"]
+    else transcript["text"]
+)
+print(original_text)
+```
+
+REST uses `GET /v1/summaries/{id}` and `GET /v1/summaries/{id}/transcript`.
+MCP uses `get_summary` and paginated `get_transcript`. Timed YouTube/TikTok
+sources expose `segments`; text/X sources expose `blocks` and `text`. X video
+caption blocks retain `start_s` / `end_s` alongside separate untimed post context.
+The saved source stays in its original language when requesting a translated summary.
+
+## Saved transcription inbox
+
+`list_transcripts` returns the latest 50 distinct sources requested by your account,
+including sources saved before an analysis failed. It reads metadata only and does
+not mark anything read. All library, source and read-state calls require `summaries:read`.
+
+```python
+page = client.list_transcripts(limit=50, unread_only=True)
+for item in page["items"]:
+    print(item["id"], item["video"]["title"], item["last_requested_at"])
+    source = client.get_saved_transcript_page(item["id"], offset=0, limit=100)
+    # Follow source["next_offset"] for additional content. Mark only when ready.
+    client.mark_transcript_read(item["id"], read=True)
+```
+
+Pass `cursor=page["next_cursor"]` with the same filters for older entries. `since`
+is inclusive and `until` exclusive, using ISO 8601 timestamps against
+`last_requested_at`. `read=False` marks a source unread again. Reading source
+content through REST/MCP/SDK never implicitly changes its read state.
+Use `get_saved_transcript_metadata(id)` to read one source’s title, dates and
+unread status directly, including sources outside the current catalog page. This
+GET does not load the transcript body or start a processing job.
+
+X posts, X video captions and articles reuse an owned source snapshot for 24 hours.
+Use `submit_analysis(..., refresh_source=True)` to retrieve current source content.
+YouTube/TikTok keep reusing saved transcripts; another brief does not redownload
+audio or repeat transcription when a usable source already exists.
+
+## X video captions and output language
+
+Pass an X post URL directly. Default `scope=auto` detects one attached video and
+analyzes its available captions plus separately labeled post context when the
+deployment enables X video extraction. You do not need a subtitle URL or a
+separate provider key. Use `{"type":"x","url":"YOUR_X_POST_URL","scope":"post"}`
+only for post text alone; thread scope does not recursively analyze its videos.
+
+```python
+receipt = client.submit_analysis(
+    "https://x.com/hamptonism/status/2071631335836225751",
+    instructions="Summarize the spoken content in Spanish. Keep it concise and avoid repetition.",
+    transcription="never",
+    idempotency_key="x-video-spanish-001",
+)
+print({"job_id": receipt["job_id"]})  # Persist before waiting.
+job = client.wait_for_job(
+    receipt["job_id"],
+    on_progress=lambda state: print(
+        {"status": state["status"], "progress": state["progress"]}
+    ),
+)
+result = client.get_summary(job["summary_id"])
+print(result["content"]["answer"])
+```
+
+The response is a durable job receipt. Save its ID before waiting; a timeout does
+not cancel the job. Use a fresh stable key for a different brief or language and
+reuse the exact body/key after an uncertain submission. Without instructions,
+the service produces a concise summary. A translated summary is generated text
+inside the same schema-3 result, not dubbed audio, a translated video or an SRT
+translation; the original captions remain saved separately.
+
+Captioned X videos use actual video duration at 1 credit/minute under normal
+rounding (128.197 seconds = 2.2 credits), not the post's reading time. Missing
+captions fail explicitly with no customer processing charge; X audio
+transcription and visual analysis are not enabled, even with `if_needed`.
+
+## Credit controls
+
+Captions, text and existing cached transcripts cost **1 credit per source minute**.
+Fresh audio transcription costs **3 credits per source minute** and requires an
+eligible paid plan or server-confirmed billing exemption, plus explicit `transcription: "if_needed"` (Python:
+`transcription="if_needed"`). The default `never` fails with a clear error when
+new transcription would be necessary. Supplying `forceAsr: true` /
+`force_asr=True` also requires that explicit permission.
+
+Use `maxCredits: "30.00"` in JavaScript or `max_credits="30.00"` in Python to cap
+a job. The server validates affordability before new transcription. The cap is
+positive, at most 1,000,000 credits, and has at most two decimal places. It is
+required for ordinary paid accounts when `transcription` is `if_needed`. Preserve
+these controls in the same idempotent request body on retries. Jobs expose
+`credits.estimated`, `reserved`, `final`, the billing class/rate and real source
+duration; polling does not create another processing charge.
+
+For `compareTikToks` / `compare_tiktoks`, the cap covers all distinct supplied
+clips: each receives an equal share rounded down to 0.01 credit. Unused shares
+are not redistributed. Comparison aggregation adds no customer processing credits.
+Source minutes round up to 0.1 minute with a 0.5-minute minimum before the rate
+multiplier. Raw text uses estimated reading minutes.
+
+Free includes 100 credits per month for captions/text, Hobby costs USD20/month
+with 1,000 credits, and Pro costs USD99/month with 5,000 credits. Included
+allowance is used first, then purchased credits, which do not expire. Reading
+account usage does not buy credits or change plans.
+
+Server-confirmed billing exemption: the authenticated server decides whether an account is exempt. Exempt accounts may omit a credit ceiling and do not incur customer-credit charges; explicit transcription permission and resource/provider limits still apply. Ordinary paid accounts allowing fresh transcription must supply a ceiling or receive `TRANSCRIPTION_NOT_ALLOWED` (HTTP 422); `MAX_CREDITS_EXCEEDED` (HTTP 422) means a supplied ceiling is invalid or below the required charge. Clients validate supplied values, then pass requests through without fetching extra account scopes or inferring privileges from names, roles, or key prefixes.