useknockout 0.0.1__tar.gz

useknockout-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+.venv/
+venv/
+env/
+.python-version
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Demo outputs
+out-*.png
+out-*.jpg
+demo-*.png
+demo-*.jpg

useknockout-0.0.1/LICENSE

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

useknockout-0.0.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: useknockout
+Version: 0.0.1
+Summary: Python SDK for useknockout — state-of-the-art background removal API.
+Project-URL: Homepage, https://useknockout.com
+Project-URL: Documentation, https://github.com/useknockout/python
+Project-URL: Repository, https://github.com/useknockout/python
+Project-URL: Issues, https://github.com/useknockout/python/issues
+Author: useknockout
+License: MIT
+License-File: LICENSE
+Keywords: ai,background-removal,birefnet,image-processing,remove-background,useknockout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🥊 useknockout
+
+**State-of-the-art background removal API — Python SDK.**
+
+[![PyPI](https://img.shields.io/pypi/v/useknockout.svg)](https://pypi.org/project/useknockout/)
+[![Python](https://img.shields.io/pypi/pyversions/useknockout.svg)](https://pypi.org/project/useknockout/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[Website](https://useknockout.com) ·
+[API repo](https://github.com/useknockout/api) ·
+[Node SDK](https://github.com/useknockout/node) ·
+[React SDK](https://github.com/useknockout/react) ·
+[CLI](https://github.com/useknockout/cli)
+
+<img src="https://raw.githubusercontent.com/useknockout/api/main/docs/banner.png" width="800" alt="useknockout — background removal API for developers" />
+
+*Background removal, 40× cheaper than remove.bg. MIT licensed. Self-hostable.*
+
+</div>
+
+---
+
+## Install
+
+```bash
+pip install useknockout
+```
+
+## Quickstart
+
+```python
+from useknockout import Knockout
+
+client = Knockout()  # uses public beta token by default
+png = client.remove("photo.jpg")
+
+with open("out.png", "wb") as f:
+    f.write(png)
+```
+
+That's it. Free during the public beta.
+
+## Async
+
+```python
+import asyncio
+from useknockout import AsyncKnockout
+
+async def main():
+    async with AsyncKnockout() as client:
+        png = await client.remove("photo.jpg")
+        open("out.png", "wb").write(png)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The client falls back through three sources in order:
+
+1. The `token=` argument
+2. The `KNOCKOUT_TOKEN` environment variable
+3. The public beta token (free, rate-limited, in the README of the API repo)
+
+Get your own token by emailing `troy@useknockout.com` (paid tier launches at $0.005/image — 40× cheaper than remove.bg).
+
+## All endpoints
+
+```python
+from useknockout import Knockout
+
+c = Knockout()
+
+# Remove background
+c.remove("photo.jpg")                                  # returns PNG bytes
+c.remove_url("https://example.com/photo.jpg")
+c.remove_batch(["a.jpg", "b.jpg", "c.jpg"])            # up to 10
+c.remove_batch_url(["https://...", "https://..."])
+
+# Replace background
+c.replace_background("photo.jpg", bg_color="#000000")
+c.replace_background("photo.jpg", bg_url="https://example.com/bg.jpg")
+
+# Mask only
+c.mask("photo.jpg")                                    # returns grayscale PNG
+
+# Crop to subject
+c.smart_crop("photo.jpg", padding=24)
+
+# Effects
+c.shadow("photo.jpg", shadow_blur=14, shadow_opacity=0.45)
+c.sticker("photo.jpg", stroke_width=20)                # WhatsApp-style
+c.outline("photo.jpg", outline_color="#000000", outline_width=4)
+
+# Presets
+c.studio_shot("photo.jpg", aspect="1:1", shadow=True)  # e-commerce
+c.headshot("photo.jpg", bg_color="#FFFFFF")            # LinkedIn 4:5 portrait
+c.headshot("photo.jpg", bg_blur=True, blur_radius=24)  # blurred original bg
+
+# Marketing
+c.compare("photo.jpg")                                 # before/after side-by-side
+
+# UX helpers
+c.preview("photo.jpg", max_dim=512)                    # ~80ms warm
+c.estimate("remove", width=1024, height=1024)          # predict latency + cost
+
+# Telemetry
+c.health()
+c.stats()                                              # public usage counter
+```
+
+Every method that returns an image returns raw bytes. Pipe to `open(path, "wb").write(...)`, `BytesIO`, `PIL.Image.open(BytesIO(...))`, `numpy`, S3 — anywhere bytes go.
+
+## Errors
+
+All errors inherit from `KnockoutError`:
+
+```python
+from useknockout import Knockout
+from useknockout.errors import (
+    AuthError,           # 401 / 403
+    BadRequestError,     # 400
+    PayloadTooLargeError,# 413 (>25 MB)
+    RateLimitError,      # 429
+    ServerError,         # 5xx
+    KnockoutError,       # base class / network errors
+)
+
+try:
+    png = client.remove("photo.jpg")
+except AuthError:
+    ...  # bad token
+except RateLimitError:
+    ...  # back off
+except KnockoutError as e:
+    print(f"{e.code} ({e.status}): {e.message}")
+```
+
+## Self-host
+
+The API is open source and runs on Modal. Deploy your own copy:
+
+```bash
+git clone https://github.com/useknockout/api
+cd api
+modal deploy main.py
+```
+
+Then point the SDK at your deployment:
+
+```python
+client = Knockout(token="your-token", base_url="https://your-deploy.modal.run")
+```
+
+## License
+
+MIT. Use it however you want.

useknockout-0.0.1/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# 🥊 useknockout
+
+**State-of-the-art background removal API — Python SDK.**
+
+[![PyPI](https://img.shields.io/pypi/v/useknockout.svg)](https://pypi.org/project/useknockout/)
+[![Python](https://img.shields.io/pypi/pyversions/useknockout.svg)](https://pypi.org/project/useknockout/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[Website](https://useknockout.com) ·
+[API repo](https://github.com/useknockout/api) ·
+[Node SDK](https://github.com/useknockout/node) ·
+[React SDK](https://github.com/useknockout/react) ·
+[CLI](https://github.com/useknockout/cli)
+
+<img src="https://raw.githubusercontent.com/useknockout/api/main/docs/banner.png" width="800" alt="useknockout — background removal API for developers" />
+
+*Background removal, 40× cheaper than remove.bg. MIT licensed. Self-hostable.*
+
+</div>
+
+---
+
+## Install
+
+```bash
+pip install useknockout
+```
+
+## Quickstart
+
+```python
+from useknockout import Knockout
+
+client = Knockout()  # uses public beta token by default
+png = client.remove("photo.jpg")
+
+with open("out.png", "wb") as f:
+    f.write(png)
+```
+
+That's it. Free during the public beta.
+
+## Async
+
+```python
+import asyncio
+from useknockout import AsyncKnockout
+
+async def main():
+    async with AsyncKnockout() as client:
+        png = await client.remove("photo.jpg")
+        open("out.png", "wb").write(png)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The client falls back through three sources in order:
+
+1. The `token=` argument
+2. The `KNOCKOUT_TOKEN` environment variable
+3. The public beta token (free, rate-limited, in the README of the API repo)
+
+Get your own token by emailing `troy@useknockout.com` (paid tier launches at $0.005/image — 40× cheaper than remove.bg).
+
+## All endpoints
+
+```python
+from useknockout import Knockout
+
+c = Knockout()
+
+# Remove background
+c.remove("photo.jpg")                                  # returns PNG bytes
+c.remove_url("https://example.com/photo.jpg")
+c.remove_batch(["a.jpg", "b.jpg", "c.jpg"])            # up to 10
+c.remove_batch_url(["https://...", "https://..."])
+
+# Replace background
+c.replace_background("photo.jpg", bg_color="#000000")
+c.replace_background("photo.jpg", bg_url="https://example.com/bg.jpg")
+
+# Mask only
+c.mask("photo.jpg")                                    # returns grayscale PNG
+
+# Crop to subject
+c.smart_crop("photo.jpg", padding=24)
+
+# Effects
+c.shadow("photo.jpg", shadow_blur=14, shadow_opacity=0.45)
+c.sticker("photo.jpg", stroke_width=20)                # WhatsApp-style
+c.outline("photo.jpg", outline_color="#000000", outline_width=4)
+
+# Presets
+c.studio_shot("photo.jpg", aspect="1:1", shadow=True)  # e-commerce
+c.headshot("photo.jpg", bg_color="#FFFFFF")            # LinkedIn 4:5 portrait
+c.headshot("photo.jpg", bg_blur=True, blur_radius=24)  # blurred original bg
+
+# Marketing
+c.compare("photo.jpg")                                 # before/after side-by-side
+
+# UX helpers
+c.preview("photo.jpg", max_dim=512)                    # ~80ms warm
+c.estimate("remove", width=1024, height=1024)          # predict latency + cost
+
+# Telemetry
+c.health()
+c.stats()                                              # public usage counter
+```
+
+Every method that returns an image returns raw bytes. Pipe to `open(path, "wb").write(...)`, `BytesIO`, `PIL.Image.open(BytesIO(...))`, `numpy`, S3 — anywhere bytes go.
+
+## Errors
+
+All errors inherit from `KnockoutError`:
+
+```python
+from useknockout import Knockout
+from useknockout.errors import (
+    AuthError,           # 401 / 403
+    BadRequestError,     # 400
+    PayloadTooLargeError,# 413 (>25 MB)
+    RateLimitError,      # 429
+    ServerError,         # 5xx
+    KnockoutError,       # base class / network errors
+)
+
+try:
+    png = client.remove("photo.jpg")
+except AuthError:
+    ...  # bad token
+except RateLimitError:
+    ...  # back off
+except KnockoutError as e:
+    print(f"{e.code} ({e.status}): {e.message}")
+```
+
+## Self-host
+
+The API is open source and runs on Modal. Deploy your own copy:
+
+```bash
+git clone https://github.com/useknockout/api
+cd api
+modal deploy main.py
+```
+
+Then point the SDK at your deployment:
+
+```python
+client = Knockout(token="your-token", base_url="https://your-deploy.modal.run")
+```
+
+## License
+
+MIT. Use it however you want.

useknockout-0.0.1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "useknockout"
+version = "0.0.1"
+description = "Python SDK for useknockout — state-of-the-art background removal API."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "useknockout" }]
+keywords = [
+    "background-removal",
+    "remove-background",
+    "birefnet",
+    "ai",
+    "image-processing",
+    "useknockout",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6.0",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://useknockout.com"
+Documentation = "https://github.com/useknockout/python"
+Repository = "https://github.com/useknockout/python"
+Issues = "https://github.com/useknockout/python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/useknockout"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]

useknockout-0.0.1/src/useknockout/__init__.py

@@ -0,0 +1,47 @@
+"""
+useknockout — state-of-the-art background removal API.
+
+Quickstart:
+
+    from useknockout import Knockout
+
+    client = Knockout(token="kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f")
+    png_bytes = client.remove("photo.jpg")
+    open("out.png", "wb").write(png_bytes)
+
+Async:
+
+    import asyncio
+    from useknockout import AsyncKnockout
+
+    async def main():
+        async with AsyncKnockout(token="...") as client:
+            png = await client.remove("photo.jpg")
+            open("out.png", "wb").write(png)
+
+    asyncio.run(main())
+"""
+
+from useknockout._version import __version__
+from useknockout.client import Knockout
+from useknockout.async_client import AsyncKnockout
+from useknockout.errors import (
+    KnockoutError,
+    AuthError,
+    BadRequestError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "__version__",
+    "Knockout",
+    "AsyncKnockout",
+    "KnockoutError",
+    "AuthError",
+    "BadRequestError",
+    "PayloadTooLargeError",
+    "RateLimitError",
+    "ServerError",
+]

useknockout-0.0.1/src/useknockout/_helpers.py

@@ -0,0 +1,73 @@
+"""Internal helpers shared by sync + async clients."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+FileInput = Union[str, Path, bytes, bytearray]
+"""Anything the SDK accepts as image input.
+
+- ``str`` / ``Path``: filesystem path to read.
+- ``bytes`` / ``bytearray``: raw image bytes.
+"""
+
+
+def _to_bytes_and_name(file: FileInput, default_name: str = "image") -> Tuple[bytes, str]:
+    """Normalize a FileInput to (bytes, filename) for httpx multipart."""
+    if isinstance(file, (bytes, bytearray)):
+        return bytes(file), default_name
+    if isinstance(file, (str, Path)):
+        path = Path(file)
+        return path.read_bytes(), path.name
+    raise TypeError(f"file must be path | bytes, got {type(file).__name__}")
+
+
+def _multipart_files(
+    file: FileInput,
+    extra_files: Optional[List[FileInput]] = None,
+) -> List[Tuple[str, Tuple[str, bytes, str]]]:
+    """Build httpx-style files= argument for one or many uploads."""
+    files: List[Tuple[str, Tuple[str, bytes, str]]] = []
+    data, name = _to_bytes_and_name(file)
+    files.append(("file", (name, data, "application/octet-stream")))
+    if extra_files:
+        for f in extra_files:
+            d, n = _to_bytes_and_name(f)
+            files.append(("files", (n, d, "application/octet-stream")))
+    return files
+
+
+def _multipart_batch(files_in: List[FileInput]) -> List[Tuple[str, Tuple[str, bytes, str]]]:
+    """Build files= for /remove-batch (field name ``files``, repeated)."""
+    out: List[Tuple[str, Tuple[str, bytes, str]]] = []
+    for i, f in enumerate(files_in):
+        data, name = _to_bytes_and_name(f, default_name=f"image-{i}")
+        out.append(("files", (name, data, "application/octet-stream")))
+    return out
+
+
+def _form(data: Dict[str, Any]) -> Dict[str, str]:
+    """Drop None values, stringify the rest, for httpx data= multipart fields."""
+    out: Dict[str, str] = {}
+    for k, v in data.items():
+        if v is None:
+            continue
+        if isinstance(v, bool):
+            out[k] = "true" if v else "false"
+        else:
+            out[k] = str(v)
+    return out
+
+
+def _resolve_token(token: Optional[str]) -> Optional[str]:
+    """Resolve token from arg or KNOCKOUT_TOKEN env var."""
+    if token:
+        return token
+    env = os.environ.get("KNOCKOUT_TOKEN", "").strip()
+    return env or None
+
+
+DEFAULT_BASE_URL = "https://useknockout--api.modal.run"
+PUBLIC_BETA_TOKEN = "kno_public_beta_4d7e9f1a3c5b2e8d6a9f7c1b3e5d8a2f"

useknockout-0.0.1/src/useknockout/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

useknockout-0.0.1/src/useknockout/async_client.py

@@ -0,0 +1,325 @@
+"""Asynchronous client for the useknockout API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from useknockout._helpers import (
+    DEFAULT_BASE_URL,
+    PUBLIC_BETA_TOKEN,
+    FileInput,
+    _form,
+    _multipart_batch,
+    _multipart_files,
+    _resolve_token,
+)
+from useknockout._version import __version__
+from useknockout.errors import KnockoutError, raise_for_status
+
+
+class AsyncKnockout:
+    """
+    Asynchronous client for the useknockout background-removal API.
+
+    Use as an async context manager to ensure the underlying httpx client closes:
+
+        async with AsyncKnockout() as client:
+            png = await client.remove("photo.jpg")
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ) -> None:
+        self.token = _resolve_token(token) or PUBLIC_BETA_TOKEN
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "User-Agent": f"useknockout-python/{__version__}",
+            },
+        )
+
+    async def __aenter__(self) -> "AsyncKnockout":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        files=None,
+        data=None,
+        json=None,
+    ) -> bytes:
+        try:
+            r = await self._http.request(method, path, files=files, data=data, json=json)
+        except httpx.RequestError as e:
+            raise KnockoutError(f"network error: {e}", code="unknown") from e
+        if r.status_code >= 400:
+            raise_for_status(r.status_code, r.content)
+        return r.content
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        files=None,
+        data=None,
+        json=None,
+    ) -> Any:
+        try:
+            r = await self._http.request(method, path, files=files, data=data, json=json)
+        except httpx.RequestError as e:
+            raise KnockoutError(f"network error: {e}", code="unknown") from e
+        if r.status_code >= 400:
+            raise_for_status(r.status_code, r.content)
+        try:
+            return r.json()
+        except ValueError as e:
+            raise KnockoutError(f"invalid JSON response: {e}", code="server") from e
+
+    async def health(self) -> Dict[str, Any]:
+        return await self._request_json("GET", "/health")
+
+    async def stats(self) -> Dict[str, Any]:
+        return await self._request_json("GET", "/stats")
+
+    async def remove(self, file: FileInput, *, format: str = "png") -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/remove",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    async def remove_url(self, url: str, *, format: str = "png") -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/remove-url",
+            json={"url": url, "format": format},
+        )
+
+    async def replace_background(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_url: Optional[str] = None,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/replace-bg",
+            files=_multipart_files(file),
+            data=_form({"bg_color": bg_color, "bg_url": bg_url, "format": format}),
+        )
+
+    async def remove_batch(
+        self,
+        files: List[FileInput],
+        *,
+        format: str = "png",
+    ) -> Dict[str, Any]:
+        if len(files) > 10:
+            raise ValueError("max 10 files per batch")
+        return await self._request_json(
+            "POST",
+            "/remove-batch",
+            files=_multipart_batch(files),
+            data=_form({"format": format}),
+        )
+
+    async def remove_batch_url(self, urls: List[str], *, format: str = "png") -> Dict[str, Any]:
+        if len(urls) > 10:
+            raise ValueError("max 10 urls per batch")
+        return await self._request_json(
+            "POST",
+            "/remove-batch-url",
+            json={"urls": urls, "format": format},
+        )
+
+    async def mask(self, file: FileInput, *, format: str = "png") -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/mask",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    async def smart_crop(
+        self,
+        file: FileInput,
+        *,
+        padding: int = 24,
+        transparent: bool = True,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/smart-crop",
+            files=_multipart_files(file),
+            data=_form({"padding": padding, "transparent": transparent, "format": format}),
+        )
+
+    async def shadow(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_url: Optional[str] = None,
+        shadow_color: str = "#000000",
+        shadow_offset_x: int = 8,
+        shadow_offset_y: int = 12,
+        shadow_blur: int = 14,
+        shadow_opacity: float = 0.45,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/shadow",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "bg_url": bg_url,
+                    "shadow_color": shadow_color,
+                    "shadow_offset_x": shadow_offset_x,
+                    "shadow_offset_y": shadow_offset_y,
+                    "shadow_blur": shadow_blur,
+                    "shadow_opacity": shadow_opacity,
+                    "format": format,
+                }
+            ),
+        )
+
+    async def sticker(
+        self,
+        file: FileInput,
+        *,
+        stroke_color: str = "#FFFFFF",
+        stroke_width: int = 20,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/sticker",
+            files=_multipart_files(file),
+            data=_form(
+                {"stroke_color": stroke_color, "stroke_width": stroke_width, "format": format}
+            ),
+        )
+
+    async def outline(
+        self,
+        file: FileInput,
+        *,
+        outline_color: str = "#000000",
+        outline_width: int = 4,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/outline",
+            files=_multipart_files(file),
+            data=_form(
+                {"outline_color": outline_color, "outline_width": outline_width, "format": format}
+            ),
+        )
+
+    async def studio_shot(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        aspect: str = "1:1",
+        padding: int = 48,
+        shadow: bool = True,
+        format: str = "jpg",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/studio-shot",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "aspect": aspect,
+                    "padding": padding,
+                    "shadow": shadow,
+                    "format": format,
+                }
+            ),
+        )
+
+    async def compare(self, file: FileInput, *, format: str = "png") -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/compare",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    async def headshot(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_blur: bool = False,
+        blur_radius: int = 20,
+        aspect: str = "4:5",
+        padding: int = 64,
+        head_top_ratio: float = 0.18,
+        format: str = "jpg",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/headshot",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "bg_blur": bg_blur,
+                    "blur_radius": blur_radius,
+                    "aspect": aspect,
+                    "padding": padding,
+                    "head_top_ratio": head_top_ratio,
+                    "format": format,
+                }
+            ),
+        )
+
+    async def preview(
+        self,
+        file: FileInput,
+        *,
+        max_dim: int = 512,
+        format: str = "png",
+    ) -> bytes:
+        return await self._request_bytes(
+            "POST",
+            "/preview",
+            files=_multipart_files(file),
+            data=_form({"max_dim": max_dim, "format": format}),
+        )
+
+    async def estimate(self, endpoint: str, width: int, height: int) -> Dict[str, Any]:
+        return await self._request_json(
+            "POST",
+            "/estimate",
+            json={"endpoint": endpoint, "width": width, "height": height},
+        )

useknockout-0.0.1/src/useknockout/client.py

@@ -0,0 +1,354 @@
+"""Synchronous client for the useknockout API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from useknockout._helpers import (
+    DEFAULT_BASE_URL,
+    PUBLIC_BETA_TOKEN,
+    FileInput,
+    _form,
+    _multipart_batch,
+    _multipart_files,
+    _resolve_token,
+)
+from useknockout._version import __version__
+from useknockout.errors import KnockoutError, raise_for_status
+
+
+class Knockout:
+    """
+    Synchronous client for the useknockout background-removal API.
+
+    Args:
+        token: API token. Falls back to ``KNOCKOUT_TOKEN`` env var, then to the
+            public beta token.
+        base_url: API base URL (override for self-hosted deployments).
+        timeout: Per-request timeout in seconds.
+
+    Example:
+        >>> client = Knockout()  # uses public beta token by default
+        >>> png = client.remove("photo.jpg")
+        >>> open("out.png", "wb").write(png)
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ) -> None:
+        self.token = _resolve_token(token) or PUBLIC_BETA_TOKEN
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "User-Agent": f"useknockout-python/{__version__}",
+            },
+        )
+
+    # ---- lifecycle ----
+
+    def __enter__(self) -> "Knockout":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ---- low-level transport ----
+
+    def _request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        files=None,
+        data=None,
+        json=None,
+    ) -> bytes:
+        try:
+            r = self._http.request(method, path, files=files, data=data, json=json)
+        except httpx.RequestError as e:
+            raise KnockoutError(f"network error: {e}", code="unknown") from e
+        if r.status_code >= 400:
+            raise_for_status(r.status_code, r.content)
+        return r.content
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        files=None,
+        data=None,
+        json=None,
+    ) -> Any:
+        try:
+            r = self._http.request(method, path, files=files, data=data, json=json)
+        except httpx.RequestError as e:
+            raise KnockoutError(f"network error: {e}", code="unknown") from e
+        if r.status_code >= 400:
+            raise_for_status(r.status_code, r.content)
+        try:
+            return r.json()
+        except ValueError as e:
+            raise KnockoutError(f"invalid JSON response: {e}", code="server") from e
+
+    # ---- public API ----
+
+    def health(self) -> Dict[str, Any]:
+        """GET /health — service status + model info."""
+        return self._request_json("GET", "/health")
+
+    def stats(self) -> Dict[str, Any]:
+        """GET /stats — public usage counter (total + today + last 7 days)."""
+        return self._request_json("GET", "/stats")
+
+    def remove(self, file: FileInput, *, format: str = "png") -> bytes:
+        """POST /remove — remove background, return transparent PNG/WebP bytes."""
+        return self._request_bytes(
+            "POST",
+            "/remove",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    def remove_url(self, url: str, *, format: str = "png") -> bytes:
+        """POST /remove-url — fetch remote image, return transparent PNG/WebP."""
+        return self._request_bytes(
+            "POST",
+            "/remove-url",
+            json={"url": url, "format": format},
+        )
+
+    def replace_background(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_url: Optional[str] = None,
+        format: str = "png",
+    ) -> bytes:
+        """POST /replace-bg — composite subject onto solid color or remote bg image."""
+        return self._request_bytes(
+            "POST",
+            "/replace-bg",
+            files=_multipart_files(file),
+            data=_form({"bg_color": bg_color, "bg_url": bg_url, "format": format}),
+        )
+
+    def remove_batch(
+        self,
+        files: List[FileInput],
+        *,
+        format: str = "png",
+    ) -> Dict[str, Any]:
+        """POST /remove-batch — up to 10 multipart uploads in one call."""
+        if len(files) > 10:
+            raise ValueError("max 10 files per batch")
+        return self._request_json(
+            "POST",
+            "/remove-batch",
+            files=_multipart_batch(files),
+            data=_form({"format": format}),
+        )
+
+    def remove_batch_url(self, urls: List[str], *, format: str = "png") -> Dict[str, Any]:
+        """POST /remove-batch-url — up to 10 remote URLs in one call."""
+        if len(urls) > 10:
+            raise ValueError("max 10 urls per batch")
+        return self._request_json(
+            "POST",
+            "/remove-batch-url",
+            json={"urls": urls, "format": format},
+        )
+
+    def mask(self, file: FileInput, *, format: str = "png") -> bytes:
+        """POST /mask — return alpha mask only (grayscale)."""
+        return self._request_bytes(
+            "POST",
+            "/mask",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    def smart_crop(
+        self,
+        file: FileInput,
+        *,
+        padding: int = 24,
+        transparent: bool = True,
+        format: str = "png",
+    ) -> bytes:
+        """POST /smart-crop — crop to subject bbox + padding."""
+        return self._request_bytes(
+            "POST",
+            "/smart-crop",
+            files=_multipart_files(file),
+            data=_form({"padding": padding, "transparent": transparent, "format": format}),
+        )
+
+    def shadow(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_url: Optional[str] = None,
+        shadow_color: str = "#000000",
+        shadow_offset_x: int = 8,
+        shadow_offset_y: int = 12,
+        shadow_blur: int = 14,
+        shadow_opacity: float = 0.45,
+        format: str = "png",
+    ) -> bytes:
+        """POST /shadow — subject on bg with configurable drop shadow."""
+        return self._request_bytes(
+            "POST",
+            "/shadow",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "bg_url": bg_url,
+                    "shadow_color": shadow_color,
+                    "shadow_offset_x": shadow_offset_x,
+                    "shadow_offset_y": shadow_offset_y,
+                    "shadow_blur": shadow_blur,
+                    "shadow_opacity": shadow_opacity,
+                    "format": format,
+                }
+            ),
+        )
+
+    def sticker(
+        self,
+        file: FileInput,
+        *,
+        stroke_color: str = "#FFFFFF",
+        stroke_width: int = 20,
+        format: str = "png",
+    ) -> bytes:
+        """POST /sticker — subject + thick outline on transparent bg."""
+        return self._request_bytes(
+            "POST",
+            "/sticker",
+            files=_multipart_files(file),
+            data=_form(
+                {"stroke_color": stroke_color, "stroke_width": stroke_width, "format": format}
+            ),
+        )
+
+    def outline(
+        self,
+        file: FileInput,
+        *,
+        outline_color: str = "#000000",
+        outline_width: int = 4,
+        format: str = "png",
+    ) -> bytes:
+        """POST /outline — subject + thin outline on transparent bg."""
+        return self._request_bytes(
+            "POST",
+            "/outline",
+            files=_multipart_files(file),
+            data=_form(
+                {"outline_color": outline_color, "outline_width": outline_width, "format": format}
+            ),
+        )
+
+    def studio_shot(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        aspect: str = "1:1",
+        padding: int = 48,
+        shadow: bool = True,
+        format: str = "jpg",
+    ) -> bytes:
+        """POST /studio-shot — e-commerce preset (cutout + crop + center + shadow)."""
+        return self._request_bytes(
+            "POST",
+            "/studio-shot",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "aspect": aspect,
+                    "padding": padding,
+                    "shadow": shadow,
+                    "format": format,
+                }
+            ),
+        )
+
+    def compare(self, file: FileInput, *, format: str = "png") -> bytes:
+        """POST /compare — side-by-side before/after image."""
+        return self._request_bytes(
+            "POST",
+            "/compare",
+            files=_multipart_files(file),
+            data=_form({"format": format}),
+        )
+
+    def headshot(
+        self,
+        file: FileInput,
+        *,
+        bg_color: str = "#FFFFFF",
+        bg_blur: bool = False,
+        blur_radius: int = 20,
+        aspect: str = "4:5",
+        padding: int = 64,
+        head_top_ratio: float = 0.18,
+        format: str = "jpg",
+    ) -> bytes:
+        """POST /headshot — LinkedIn-ready portrait preset."""
+        return self._request_bytes(
+            "POST",
+            "/headshot",
+            files=_multipart_files(file),
+            data=_form(
+                {
+                    "bg_color": bg_color,
+                    "bg_blur": bg_blur,
+                    "blur_radius": blur_radius,
+                    "aspect": aspect,
+                    "padding": padding,
+                    "head_top_ratio": head_top_ratio,
+                    "format": format,
+                }
+            ),
+        )
+
+    def preview(
+        self,
+        file: FileInput,
+        *,
+        max_dim: int = 512,
+        format: str = "png",
+    ) -> bytes:
+        """POST /preview — fast low-res preview (~80ms warm)."""
+        return self._request_bytes(
+            "POST",
+            "/preview",
+            files=_multipart_files(file),
+            data=_form({"max_dim": max_dim, "format": format}),
+        )
+
+    def estimate(self, endpoint: str, width: int, height: int) -> Dict[str, Any]:
+        """POST /estimate — predict latency + cost without processing."""
+        return self._request_json(
+            "POST",
+            "/estimate",
+            json={"endpoint": endpoint, "width": width, "height": height},
+        )

useknockout-0.0.1/src/useknockout/errors.py

@@ -0,0 +1,81 @@
+"""Typed errors raised by the useknockout SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class KnockoutError(Exception):
+    """
+    Base error raised by the useknockout SDK.
+
+    Attributes:
+        status: HTTP status code (or None for transport errors).
+        code: Short machine-readable error category.
+        message: Human-readable message.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: str = "unknown",
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class AuthError(KnockoutError):
+    """401 / 403 — token missing or invalid."""
+
+    def __init__(self, message: str, *, status: int) -> None:
+        super().__init__(message, status=status, code="auth")
+
+
+class BadRequestError(KnockoutError):
+    """400 — bad input (invalid format, missing fields, etc.)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status=400, code="bad_request")
+
+
+class PayloadTooLargeError(KnockoutError):
+    """413 — image exceeds size limit."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status=413, code="payload_too_large")
+
+
+class RateLimitError(KnockoutError):
+    """429 — rate limit exceeded."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status=429, code="rate_limit")
+
+
+class ServerError(KnockoutError):
+    """5xx — server-side failure."""
+
+    def __init__(self, message: str, status: int) -> None:
+        super().__init__(message, status=status, code="server")
+
+
+def raise_for_status(status: int, body: bytes) -> None:
+    """Map an HTTP error status to the appropriate KnockoutError subclass."""
+    text = body.decode("utf-8", errors="replace") if body else ""
+    detail = text or f"HTTP {status}"
+
+    if status == 401 or status == 403:
+        raise AuthError(detail, status=status)
+    if status == 400:
+        raise BadRequestError(detail)
+    if status == 413:
+        raise PayloadTooLargeError(detail)
+    if status == 429:
+        raise RateLimitError(detail)
+    if 500 <= status < 600:
+        raise ServerError(detail, status=status)
+    raise KnockoutError(detail, status=status, code="unknown")