lowcoai-api 1.1.0__tar.gz

lowcoai_api-1.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules
+npm/engage/dist
+dist
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+
+# Dart / Flutter
+.dart_tool/
+pubspec.lock

lowcoai_api-1.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 1.1.0
+
+- First release, generated from Lowco API 1.1.0: every Phase 1 operation (PDF, render, OCR, Document AI, QR and barcodes) and resource (files, jobs, webhooks, templates, settings, usage, audit log).
+- File inputs from paths, bytes, streams, URLs, file ids and base64; multipart or references chosen per call.
+- `wait_for_result` and `jobs.wait` (Retry-After, timeout), `list_all` iterators, `LowcoApiError` with typed `reason`, retries on 429/503, `new_idempotency_key`, raw bytes with `accept`, webhook `verify_signature` and `construct_event`; standard library only.

lowcoai_api-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lowco AI
+
+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.

lowcoai_api-1.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: lowcoai-api
+Version: 1.1.0
+Summary: Official Python client for the Lowco API: PDF, render, OCR, Document AI, QR and barcodes, with jobs, file inputs, webhooks and typed errors.
+Project-URL: Repository, https://github.com/lowcoai/lowco-sdk
+Project-URL: Source, https://github.com/lowcoai/lowco-sdk/tree/main/python/api
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document-ai,gst,invoice,lowco,ocr,pdf,qr,sdk,upi
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lowcoai-api
+
+Official Python client for the **Lowco API**: PDF, render, OCR, Document AI, QR codes and barcodes, with jobs, file inputs, webhooks and typed errors. Generated from the API's OpenAPI document with hand-written helpers. Python 3.9+, standard library only.
+
+```bash
+pip install lowcoai-api
+```
+
+## Quick start
+
+```python
+from lowcoai.api import Files, LowcoApi
+
+lowco = LowcoApi()  # LOWCO_API_KEY: lc_test_… or lc_live_…
+
+qr = lowco.qr.generate(type="upi", pa="acme@okhdfcbank", pn="Acme Traders", am="1499.00", accept="image/png")
+open("qr.png", "wb").write(qr.bytes)
+
+answer = lowco.docai.invoice(file=Files.path("invoice.pdf"), mode="async")  # 202 with a job
+invoice = lowco.wait_for_result(answer)                                       # polls, honouring Retry-After
+print(invoice["invoice_number"]["value"], invoice["invoice_number"]["confidence"])
+```
+
+`examples/quickstart.py` is the full program; CI runs it against the test environment.
+
+## Operations
+
+`lowco.<service>.<operation>(**params)` for every operation: `pdf` (merge, split, arrange, compress, rotate, watermark, protect, unlock, to_images, from_images, info, extract_text, to_docx), `render` (html, template, docx, docx_template), `ocr` (text, handwriting), `docai` (classify, invoice, receipt, tables, extract), `qr` (generate, decode), `barcode` (generate, decode). Parameters are keyword-only and named like the API's fields; results are typed dicts (`PdfMergeResult`, …).
+
+Each returns an `Answer`: `data` when finished in the request, `job` when accepted as one (status 202), `bytes`/`content_type` when `accept` asked for the output's own type; plus `request_id`, `replayed` and `credits_used`. Every operation also takes `mode`, `accept`, `idempotency_key`, `request_id` and `timeout`.
+
+## Files
+
+`Files.path(p, password=…)`, `Files.bytes(b, filename=…)`, `Files.stream(fileobj)`, `Files.url(u)`, `Files.id("file_…")`, `Files.base64(s)`; bytes and binary file objects are accepted bare. Local inputs go as multipart parts, remote ones by reference; mixed calls upload the local ones first. `lowco.files.download(url)` fetches an output's signed link.
+
+## Jobs, pagination, errors
+
+```python
+job = lowco.jobs.wait("job_01J…", timeout=120)          # LowcoJobError if it failed, LowcoTimeoutError at the timeout
+for j in lowco.jobs.list_all(status="failed"): ...       # follows next_cursor
+
+try:
+    ...
+except LowcoApiError as e:
+    e.reason, e.status, e.param, e.details, e.request_id, e.doc_url, e.retryable, e.retry_after
+```
+
+`ERROR_REASONS` says when each reason is answered and what to do. GETs and calls with an `idempotency_key` (`new_idempotency_key()`) are retried on 429, 503 and network failures. A parameter named like a Python keyword takes a trailing underscore (`usage.get(from_="2026-10-01")`).
+
+## Webhooks
+
+```python
+from lowcoai.api import construct_event
+
+event = construct_event(raw_body, request.headers.get("Lowco-Signature"), secret)  # raises LowcoSignatureError
+```
+
+## Configuration
+
+`LowcoApi(api_key=None, *, base_url=None, timeout=60.0, max_retries=2)`; the key defaults to `LOWCO_API_KEY` and the base URL to `LOWCO_API_BASE_URL`, else `https://api.lowco.ai`. Tests: `python -m unittest discover -s tests`. Reference: https://docs.lowco.ai/api/

lowcoai_api-1.1.0/README.md

@@ -0,0 +1,60 @@
+# lowcoai-api
+
+Official Python client for the **Lowco API**: PDF, render, OCR, Document AI, QR codes and barcodes, with jobs, file inputs, webhooks and typed errors. Generated from the API's OpenAPI document with hand-written helpers. Python 3.9+, standard library only.
+
+```bash
+pip install lowcoai-api
+```
+
+## Quick start
+
+```python
+from lowcoai.api import Files, LowcoApi
+
+lowco = LowcoApi()  # LOWCO_API_KEY: lc_test_… or lc_live_…
+
+qr = lowco.qr.generate(type="upi", pa="acme@okhdfcbank", pn="Acme Traders", am="1499.00", accept="image/png")
+open("qr.png", "wb").write(qr.bytes)
+
+answer = lowco.docai.invoice(file=Files.path("invoice.pdf"), mode="async")  # 202 with a job
+invoice = lowco.wait_for_result(answer)                                       # polls, honouring Retry-After
+print(invoice["invoice_number"]["value"], invoice["invoice_number"]["confidence"])
+```
+
+`examples/quickstart.py` is the full program; CI runs it against the test environment.
+
+## Operations
+
+`lowco.<service>.<operation>(**params)` for every operation: `pdf` (merge, split, arrange, compress, rotate, watermark, protect, unlock, to_images, from_images, info, extract_text, to_docx), `render` (html, template, docx, docx_template), `ocr` (text, handwriting), `docai` (classify, invoice, receipt, tables, extract), `qr` (generate, decode), `barcode` (generate, decode). Parameters are keyword-only and named like the API's fields; results are typed dicts (`PdfMergeResult`, …).
+
+Each returns an `Answer`: `data` when finished in the request, `job` when accepted as one (status 202), `bytes`/`content_type` when `accept` asked for the output's own type; plus `request_id`, `replayed` and `credits_used`. Every operation also takes `mode`, `accept`, `idempotency_key`, `request_id` and `timeout`.
+
+## Files
+
+`Files.path(p, password=…)`, `Files.bytes(b, filename=…)`, `Files.stream(fileobj)`, `Files.url(u)`, `Files.id("file_…")`, `Files.base64(s)`; bytes and binary file objects are accepted bare. Local inputs go as multipart parts, remote ones by reference; mixed calls upload the local ones first. `lowco.files.download(url)` fetches an output's signed link.
+
+## Jobs, pagination, errors
+
+```python
+job = lowco.jobs.wait("job_01J…", timeout=120)          # LowcoJobError if it failed, LowcoTimeoutError at the timeout
+for j in lowco.jobs.list_all(status="failed"): ...       # follows next_cursor
+
+try:
+    ...
+except LowcoApiError as e:
+    e.reason, e.status, e.param, e.details, e.request_id, e.doc_url, e.retryable, e.retry_after
+```
+
+`ERROR_REASONS` says when each reason is answered and what to do. GETs and calls with an `idempotency_key` (`new_idempotency_key()`) are retried on 429, 503 and network failures. A parameter named like a Python keyword takes a trailing underscore (`usage.get(from_="2026-10-01")`).
+
+## Webhooks
+
+```python
+from lowcoai.api import construct_event
+
+event = construct_event(raw_body, request.headers.get("Lowco-Signature"), secret)  # raises LowcoSignatureError
+```
+
+## Configuration
+
+`LowcoApi(api_key=None, *, base_url=None, timeout=60.0, max_retries=2)`; the key defaults to `LOWCO_API_KEY` and the base URL to `LOWCO_API_BASE_URL`, else `https://api.lowco.ai`. Tests: `python -m unittest discover -s tests`. Reference: https://docs.lowco.ai/api/

lowcoai_api-1.1.0/examples/quickstart.py

@@ -0,0 +1,28 @@
+"""The Lowco API quickstart with lowcoai-api: a UPI QR code, then a GST
+invoice extracted as a job and waited for. Run with LOWCO_API_KEY set to a
+test key (lc_test_…) and invoice.pdf in the working directory."""
+
+import sys
+
+from lowcoai.api import Files, LowcoApi, LowcoApiError
+
+lowco = LowcoApi()  # reads LOWCO_API_KEY
+
+try:
+    # 1. A UPI payment QR code, as the PNG itself
+    qr = lowco.qr.generate(type="upi", pa="acme@okhdfcbank", pn="Acme Traders", am="1499.00",
+                           tn="INV-2026-0042", accept="image/png")
+    with open("qr.png", "wb") as f:
+        f.write(qr.bytes)
+    print(f"qr.png written ({len(qr.bytes)} bytes)")
+
+    # 2. A GST invoice, submitted as a job and waited for
+    answer = lowco.docai.invoice(file=Files.path("invoice.pdf"), mode="async")
+    print(f"job {answer.job['status']}")
+    invoice = lowco.wait_for_result(answer)
+    for name, f in {"invoice_number": invoice["invoice_number"], "seller_gstin": invoice["seller"]["gstin"],
+                    "total": invoice["total"]}.items():
+        print(f"{name}: {f['value']} (confidence {f['confidence']})")
+except LowcoApiError as e:
+    print(f"{e.reason}: {e.message} ({e.doc_url}, request {e.request_id})", file=sys.stderr)
+    sys.exit(1)

lowcoai_api-1.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lowcoai-api"
+version = "1.1.0"
+description = "Official Python client for the Lowco API: PDF, render, OCR, Document AI, QR and barcodes, with jobs, file inputs, webhooks and typed errors."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "typing-extensions>=4.7; python_version < '3.11'",
+]
+keywords = ["lowco", "pdf", "ocr", "document-ai", "invoice", "gst", "qr", "upi", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/lowcoai/lowco-sdk"
+Source = "https://github.com/lowcoai/lowco-sdk/tree/main/python/api"
+
+[project.optional-dependencies]
+dev = ["mypy>=1.10", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lowcoai"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+explicit_package_bases = true
+warn_return_any = false
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+extend-exclude = ["src/lowcoai/api/_generated.py"]

lowcoai_api-1.1.0/src/lowcoai/api/__init__.py

@@ -0,0 +1,47 @@
+"""Official Python client for the Lowco API: PDF, render, OCR, Document AI,
+QR and barcodes, with jobs, file inputs, webhooks and typed errors.
+
+    from lowcoai.api import Files, LowcoApi
+
+    lowco = LowcoApi()  # LOWCO_API_KEY
+    answer = lowco.docai.invoice(file=Files.path("invoice.pdf"), mode="async")
+    invoice = lowco.wait_for_result(answer)
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Optional, TypeVar
+
+from ._core import DEFAULT_BASE_URL, SDK_VERSION, Answer, Core, FileInput
+from ._errors import LowcoApiError, LowcoJobError, LowcoTimeoutError
+from ._files import FileRef, Files
+from ._generated import API_VERSION, ERROR_REASONS, ErrorReason, GeneratedClient
+from ._webhooks import SIGNATURE_HEADER, LowcoSignatureError, construct_event, verify_signature
+
+__all__ = [
+    "API_VERSION", "DEFAULT_BASE_URL", "ERROR_REASONS", "SDK_VERSION", "SIGNATURE_HEADER",
+    "Answer", "ErrorReason", "FileInput", "FileRef", "Files", "LowcoApi", "LowcoApiError", "LowcoJobError",
+    "LowcoSignatureError", "LowcoTimeoutError", "construct_event", "new_idempotency_key", "verify_signature",
+]
+__version__ = SDK_VERSION
+
+T = TypeVar("T")
+
+
+def new_idempotency_key() -> str:
+    """A new Idempotency-Key: store it with your record before calling, and reuse it on retries."""
+    return str(uuid.uuid4())
+
+
+class LowcoApi(GeneratedClient):
+    """The Lowco API client. ``api_key`` defaults to LOWCO_API_KEY and
+    ``base_url`` to LOWCO_API_BASE_URL, else https://api.lowco.ai."""
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 60.0,
+                 max_retries: int = 2) -> None:
+        super().__init__(Core(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries))
+
+    def wait_for_result(self, answer: Answer[T], *, timeout: float = 300.0, max_interval: float = 10.0) -> T:
+        """The result of an operation's answer: inline data, or the job's result once it finishes."""
+        return self._core.wait_for_result(answer, timeout=timeout, max_interval=max_interval)

lowcoai_api-1.1.0/src/lowcoai/api/_core.py

@@ -0,0 +1,343 @@
+"""The transport every generated method calls: auth, the envelope, typed
+errors, file inputs (multipart or by reference), job waiting, pagination and
+retries. Standard library only."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import IO, Any, Dict, Generic, Iterator, List, Mapping, Optional, Tuple, TypeVar, Union
+from urllib import error as urlerror
+from urllib import parse, request
+
+from ._errors import LowcoApiError, LowcoJobError, LowcoTimeoutError
+from ._files import FileRef, Files
+
+DEFAULT_BASE_URL = "https://api.lowco.ai"
+SDK_VERSION = "1.1.0"
+_TERMINAL = {"succeeded", "failed", "cancelled"}
+
+T = TypeVar("T")
+
+FileInput = Union[FileRef, bytes, bytearray, memoryview, IO[bytes]]
+"""A file input: build one with ``Files``, or pass bytes or a binary file object."""
+
+
+@dataclass
+class Answer(Generic[T]):
+    """An operation's answer: the result inline (200), a job (202), or the output file's bytes."""
+
+    status: int
+    data: Optional[T] = None
+    """The result, when the operation finished in the request."""
+    job: Optional[Dict[str, Any]] = None
+    """The job, when the operation was accepted as one (status 202)."""
+    bytes: Optional[bytes] = None
+    """The output file, when ``accept`` asked for its type."""
+    content_type: Optional[str] = None
+    request_id: Optional[str] = None
+    replayed: bool = False
+    """True when an Idempotency-Key replayed an earlier submission."""
+    credits_used: Optional[str] = None
+
+
+@dataclass
+class _Raw:
+    status: int
+    headers: Mapping[str, str]
+    body: Any = None
+    content: Optional[bytes] = None
+    content_type: str = ""
+    location: Optional[str] = None
+
+
+class _NoRedirect(request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+def _normalise(value: Any) -> FileRef:
+    if isinstance(value, FileRef):
+        return value
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return Files.bytes(bytes(value))
+    if hasattr(value, "read"):
+        return Files.stream(value)
+    raise LowcoApiError("A file input must be built with Files (path, bytes, stream, url, id, base64)", status=0, reason="invalid_param")
+
+
+def _multipart(fields: List[Tuple[str, str]], files: List[Tuple[str, str, str, bytes]]) -> Tuple[bytes, str]:
+    boundary = "lowco" + uuid.uuid4().hex
+    out = bytearray()
+    for name, value in fields:
+        out += f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n".encode()
+        out += value.encode() + b"\r\n"
+    for name, filename, mime, data in files:
+        safe = filename.replace('"', "_")
+        out += f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"; filename=\"{safe}\"\r\nContent-Type: {mime}\r\n\r\n".encode()
+        out += data + b"\r\n"
+    out += f"--{boundary}--\r\n".encode()
+    return bytes(out), f"multipart/form-data; boundary={boundary}"
+
+
+class Core:
+    """Sends requests and decodes answers."""
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 60.0, max_retries: int = 2) -> None:
+        key = api_key or os.environ.get("LOWCO_API_KEY")
+        if not key:
+            raise LowcoApiError("api_key is required (lc_live_… or lc_test_…): pass it or set LOWCO_API_KEY", status=0, reason="missing_key")
+        self._key = key
+        self.base_url = (base_url or os.environ.get("LOWCO_API_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._opener = request.build_opener()
+        self._no_redirect = request.build_opener(_NoRedirect)
+
+    def _url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        url = path if path.startswith("http") else self.base_url + path
+        q = {k: ("true" if v is True else "false" if v is False else v) for k, v in (query or {}).items() if v is not None}
+        if q:
+            url += ("&" if "?" in url else "?") + parse.urlencode(q)
+        return url
+
+    def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        body: Optional[bytes] = None,
+        headers: Optional[Dict[str, str]] = None,
+        auth: bool = True,
+        follow: bool = True,
+        request_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        retry_safe: Optional[bool] = None,
+    ) -> _Raw:
+        h = {"X-Client-User-Agent": f"lowcoai-api-python/{SDK_VERSION}", "Accept": "application/json"}
+        h.update(headers or {})
+        if auth:
+            h["Authorization"] = f"Bearer {self._key}"
+        if request_id:
+            h["X-Request-Id"] = request_id
+        if idempotency_key:
+            h["Idempotency-Key"] = idempotency_key
+        safe = (method == "GET" if retry_safe is None else retry_safe) or bool(idempotency_key)
+        attempt = 0
+        while True:
+            req = request.Request(url, data=body, method=method, headers=h)
+            opener = self._opener if follow else self._no_redirect
+            try:
+                with opener.open(req, timeout=timeout or self._timeout) as resp:
+                    return self._read(resp.status, resp.headers, resp.read())
+            except urlerror.HTTPError as e:
+                try:
+                    raw = self._read(e.code, e.headers, e.read() if e.fp else b"")
+                finally:
+                    e.close()
+                if 300 <= e.code < 400:
+                    return raw
+                err = self._error(raw)
+                if safe and attempt < self._max_retries and e.code in (429, 503):
+                    time.sleep(min(err.retry_after if err.retry_after is not None else 1, 30))
+                    attempt += 1
+                    continue
+                raise err from None
+            except (urlerror.URLError, TimeoutError, OSError) as e:
+                if safe and attempt < self._max_retries:
+                    time.sleep(0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                raise LowcoApiError(f"Network error: {e}", status=0, reason="service_unavailable", retryable=True) from e
+
+    def _read(self, status: int, headers: Any, content: bytes) -> _Raw:
+        ctype = headers.get("Content-Type", "") if headers else ""
+        hdrs = {k.lower(): v for k, v in headers.items()} if headers else {}
+        raw = _Raw(status=status, headers=hdrs, content_type=ctype, location=hdrs.get("location"))
+        if "json" in ctype:
+            try:
+                raw.body = json.loads(content.decode("utf-8")) if content else None
+            except ValueError:
+                raw.body = content.decode("utf-8", "replace")
+        else:
+            raw.content = content
+        return raw
+
+    def _error(self, raw: _Raw) -> LowcoApiError:
+        ra = raw.headers.get("retry-after")
+        retry_after = int(ra) if ra and ra.isdigit() else None
+        e = raw.body.get("error") if isinstance(raw.body, dict) else None
+        rid = (e or {}).get("request_id") or raw.headers.get("x-request-id")
+        if isinstance(e, dict):
+            return LowcoApiError(
+                str(e.get("message") or f"Request failed with status {raw.status}"),
+                status=raw.status, reason=str(e.get("reason") or "internal_error"), param=e.get("param"),
+                details=e.get("details"), request_id=rid, doc_url=e.get("doc_url"), retryable=e.get("retryable"),
+                retry_after=retry_after, payload=raw.body,
+            )
+        text = raw.body if isinstance(raw.body, str) else (raw.content or b"").decode("utf-8", "replace")
+        return LowcoApiError(text or f"Request failed with status {raw.status}", status=raw.status,
+                             reason="internal_error" if raw.status >= 500 else "invalid_param", request_id=rid,
+                             retry_after=retry_after, payload=raw.body if raw.body is not None else text)
+
+    @staticmethod
+    def _data(raw: _Raw) -> Any:
+        if not isinstance(raw.body, dict) or raw.body.get("status") != 1:
+            raise LowcoApiError("The API answered without a success envelope", status=raw.status, reason="internal_error", payload=raw.body)
+        return raw.body.get("data")
+
+    def call(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None, json: Any = None,
+             idempotency_key: Optional[str] = None, request_id: Optional[str] = None) -> Any:
+        body = None
+        headers: Dict[str, str] = {}
+        if json is not None:
+            body = _json_bytes(json)
+            headers["Content-Type"] = "application/json"
+        raw = self._send(method, self._url(path, query), body=body, headers=headers,
+                         idempotency_key=idempotency_key, request_id=request_id)
+        return self._data(raw)
+
+    def upload(self, path: str, file: FileInput, *, request_id: Optional[str] = None) -> Any:
+        ref = _normalise(file)
+        if not ref.is_local:
+            raise LowcoApiError("upload takes a local file (path, bytes or stream)", status=0, reason="invalid_param", param="file")
+        name, mime, data = ref.read()
+        fields = [("password", ref.password)] if ref.password else []
+        body, ctype = _multipart(fields, [("file", name, mime, data)])
+        return self._data(self._send("POST", self._url(path), body=body, headers={"Content-Type": ctype}, request_id=request_id))
+
+    def redirect(self, path: str, *, request_id: Optional[str] = None) -> str:
+        raw = self._send("GET", self._url(path), follow=False, request_id=request_id)
+        if not raw.location:
+            raise LowcoApiError("The API answered without a Location", status=raw.status, reason="internal_error")
+        return raw.location
+
+    def download(self, url: str) -> bytes:
+        raw = self._send("GET", url, auth=False, headers={"Accept": "*/*"})
+        if raw.content is not None:
+            return raw.content
+        return _json_bytes(raw.body)
+
+    def operation(self, path: str, params: Dict[str, Any], *, input_kind: str, extra: List[str],
+                  mode: Optional[str] = None, idempotency_key: Optional[str] = None, accept: Optional[str] = None,
+                  request_id: Optional[str] = None, timeout: Optional[float] = None) -> Answer[Any]:
+        rest = {k: v for k, v in params.items() if v is not None}
+        named: List[Tuple[str, FileRef]] = []
+        many: Optional[List[FileRef]] = None
+        if input_kind == "file":
+            if "file" not in rest:
+                raise LowcoApiError("file is required", status=0, reason="missing_param", param="file")
+            named.append(("file", _normalise(rest.pop("file"))))
+        elif input_kind == "files":
+            files = rest.pop("files", None)
+            if not files:
+                raise LowcoApiError("files is required", status=0, reason="missing_param", param="files")
+            many = [_normalise(f) for f in files]
+        for x in extra:
+            if x in rest:
+                named.append((x, _normalise(rest.pop(x))))
+        refs = [r for _, r in named] + (many or [])
+        local = sum(1 for r in refs if r.is_local)
+        if 0 < local < len(refs):
+            def up(r: FileRef) -> FileRef:
+                if not r.is_local:
+                    return r
+                stored = self.upload("/v1/files", r)
+                return Files.id(stored["file_id"], password=r.password)
+            named = [(f, up(r)) for f, r in named]
+            many = [up(r) for r in many] if many is not None else None
+        headers: Dict[str, str] = {}
+        if accept:
+            headers["Accept"] = accept
+        if local and local == len(refs):
+            fields: List[Tuple[str, str]] = []
+            parts: List[Tuple[str, str, str, bytes]] = []
+            for fname, r in named:
+                name, mime, data = r.read()
+                parts.append((fname, name, mime, data))
+                if fname == "file" and r.password:
+                    fields.append(("password", r.password))
+            for r in many or []:
+                name, mime, data = r.read()
+                parts.append(("files[]", name, mime, data))
+            if "callback_url" in rest:
+                fields.append(("callback_url", str(rest.pop("callback_url"))))
+            fields.append(("options", json.dumps(rest)))
+            body, ctype = _multipart(fields, parts)
+            headers["Content-Type"] = ctype
+        else:
+            payload = dict(rest)
+            for fname, r in named:
+                if fname == "file":
+                    payload.update(r.reference())
+                else:
+                    payload[fname] = r.reference()
+            if many is not None:
+                payload["files"] = [r.reference() for r in many]
+            body = _json_bytes(payload)
+            headers["Content-Type"] = "application/json"
+        raw = self._send("POST", self._url(path, {"mode": mode} if mode else None), body=body, headers=headers,
+                         idempotency_key=idempotency_key, request_id=request_id, timeout=timeout, retry_safe=False)
+        answer: Answer[Any] = Answer(status=raw.status, request_id=raw.headers.get("x-request-id"),
+                                     replayed=raw.headers.get("idempotent-replayed") == "true",
+                                     credits_used=raw.headers.get("x-lowco-credits-used"))
+        if raw.content is not None:
+            answer.bytes = raw.content
+            answer.content_type = raw.content_type
+        elif raw.status == 202:
+            answer.job = self._data(raw)
+        else:
+            answer.data = self._data(raw)
+        return answer
+
+    def paginate(self, path: str, query: Mapping[str, Any], *, request_id: Optional[str] = None) -> Iterator[Any]:
+        cursor: Optional[str] = None
+        while True:
+            page = self.call("GET", path, query={**query, "cursor": cursor}, request_id=request_id)
+            for item in page["items"]:
+                yield item
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    def wait_for_job(self, job_id: str, *, timeout: float = 300.0, max_interval: float = 10.0) -> Dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while True:
+            raw = self._send("GET", self._url(f"/v1/jobs/{parse.quote(job_id, safe='')}"))
+            job = self._data(raw)
+            if job["status"] in _TERMINAL:
+                if job["status"] == "succeeded":
+                    return job  # type: ignore[no-any-return]
+                e = job.get("error") or {}
+                raise LowcoJobError(
+                    e.get("message") or f"Job {job_id} was {job['status']}", job=job, status=e.get("code") or 409,
+                    reason=e.get("reason") or "invalid_state", param=e.get("param"), details=e.get("details"),
+                    doc_url=e.get("doc_url"), retryable=e.get("retryable"), request_id=raw.headers.get("x-request-id"),
+                )
+            ra = raw.headers.get("retry-after", "2")
+            interval = float(ra) if ra.replace(".", "", 1).isdigit() else 2.0
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise LowcoTimeoutError(job_id, timeout)
+            time.sleep(max(0.0, min(interval, max_interval, left)))
+
+    def wait_for_result(self, answer: Answer[T], *, timeout: float = 300.0, max_interval: float = 10.0) -> T:
+        if answer.data is not None:
+            return answer.data
+        if answer.job is not None:
+            job = self.wait_for_job(answer.job["job_id"], timeout=timeout, max_interval=max_interval)
+            return job["result"]  # type: ignore[no-any-return]
+        raise LowcoApiError("The answer carries bytes, not a result", status=answer.status, reason="invalid_param")
+
+
+def _json_bytes(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+
+def guess_mime(name: str) -> str:
+    return mimetypes.guess_type(name)[0] or "application/octet-stream"