gemini-logo-remover 0.1.0__tar.gz

gemini_logo_remover-0.1.0/LICENSE

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

gemini_logo_remover-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: gemini-logo-remover
+Version: 0.1.0
+Summary: Remove the Gemini watermark from images with one function call, using the Gemini Logo Remover API.
+License: MIT
+Project-URL: Homepage, https://app.gemini-logo-remover.workers.dev
+Project-URL: Documentation, https://app.gemini-logo-remover.workers.dev/developers
+Keywords: gemini,watermark,logo,remover,image,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: Pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# gemini-logo-remover
+
+Remove the Gemini watermark from images with one function call.
+
+```bash
+pip install gemini-logo-remover
+```
+
+```python
+from gemini_logo_remover import remove_logo
+
+remove_logo("gemini-image.png", "clean.png")
+```
+
+## How it works
+
+The watermark only sits in the bottom-right corner. This package cuts out that corner
+(at most 480×480 px), sends **only that small piece** to the Gemini Logo Remover API,
+and pastes the cleaned corner back into your original image on your machine.
+
+- Uploads are tiny (a few hundred KB), so it is fast.
+- Every pixel outside the corner is returned exactly as it was — the server never
+  re-compresses your picture.
+- The removal itself runs on the hosted API (a Cloudflare Worker), not on your computer.
+  Your images are not stored; only the corner crop is sent.
+
+The server reverses the watermark's alpha blend (lossless) and falls back to AI inpainting
+only for what that cannot explain.
+
+## Usage
+
+### One image
+
+```python
+from gemini_logo_remover import remove_logo
+
+result = remove_logo("in.png", "out.png")        # saves out.png
+print(result.method, result.clean, result.warnings)
+
+# no file written, work with the Pillow image instead
+result = remove_logo("in.png")
+result.image.show()
+result.save("later.jpg")                          # .jpg -> JPEG, otherwise PNG
+```
+
+`image` can be a path, `bytes`, an open binary file, or a `PIL.Image`.
+
+`Result` fields: `image`, `method` (`alpha`, `inpaint`, `alpha+inpaint`, `none`),
+`detected`, `slot`, `confidence`, `clean`, `warnings`, `output_path`.
+
+### Many images, in parallel
+
+```python
+from gemini_logo_remover import remove_logo_many
+
+items = remove_logo_many(["a.png", "b.png", "c.jpg"], "cleaned/", workers=3)
+for item in items:
+    print(item.source, "ok" if item.ok else f"failed: {item.error}")
+```
+
+One bad file never stops the others; failures are returned in the list. Keep `workers`
+at 3 or less on the free hosted API.
+
+### Command line
+
+```bash
+gemini-logo-remover photo.png                     # writes photo_clean.png next to it
+gemini-logo-remover *.png -o cleaned/ --workers 3
+gemini-logo-remover photo.png --mode alpha        # lossless only
+python -m gemini_logo_remover photo.png           # same thing
+```
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `auto` | `auto`: reverse the watermark, inpaint only what is left. `alpha`: lossless only, never inpaints (image unchanged + a warning if it cannot). `inpaint`: skip alpha. |
+| `sparkle` | `False` | Also inpaint the small V3 slot. Unverified; can damage text near the corner. |
+| `api_url` | hosted API | Your own server. Or set `GEMINI_LOGO_REMOVER_API_URL`. |
+| `api_key` | none | If the server requires a key. Or set `GEMINI_LOGO_REMOVER_API_KEY`. |
+| `retries` | `3` | Extra attempts on 429 / 5xx / network errors / cut-off replies. |
+| `timeout` | `180` | Seconds per request. |
+
+### Errors
+
+- `InvalidImageError` — the input is not a readable image.
+- `ApiError` — the API rejected the request or kept failing. Has `.status` and `.code`.
+- `GeminiLogoRemoverError` — base class of both.
+
+## Limits
+
+The hosted API runs on a free tier. Expect to process a few images at a time, not
+thousands. Point `api_url` at your own deployment of the server for heavy use.
+
+## Development and publishing
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+
+python -m build                      # creates dist/*.whl and dist/*.tar.gz
+twine check dist/*
+twine upload --repository testpypi dist/*   # try it on TestPyPI first
+twine upload dist/*                         # publish to PyPI
+```
+
+Uploading needs a PyPI account and an API token (pypi.org → Account settings → API tokens);
+use `__token__` as the username and the token as the password. Bump `version` in
+`pyproject.toml` (and `__version__`) for every release — PyPI never lets you re-upload the
+same version.

gemini_logo_remover-0.1.0/README.md

@@ -0,0 +1,111 @@
+# gemini-logo-remover
+
+Remove the Gemini watermark from images with one function call.
+
+```bash
+pip install gemini-logo-remover
+```
+
+```python
+from gemini_logo_remover import remove_logo
+
+remove_logo("gemini-image.png", "clean.png")
+```
+
+## How it works
+
+The watermark only sits in the bottom-right corner. This package cuts out that corner
+(at most 480×480 px), sends **only that small piece** to the Gemini Logo Remover API,
+and pastes the cleaned corner back into your original image on your machine.
+
+- Uploads are tiny (a few hundred KB), so it is fast.
+- Every pixel outside the corner is returned exactly as it was — the server never
+  re-compresses your picture.
+- The removal itself runs on the hosted API (a Cloudflare Worker), not on your computer.
+  Your images are not stored; only the corner crop is sent.
+
+The server reverses the watermark's alpha blend (lossless) and falls back to AI inpainting
+only for what that cannot explain.
+
+## Usage
+
+### One image
+
+```python
+from gemini_logo_remover import remove_logo
+
+result = remove_logo("in.png", "out.png")        # saves out.png
+print(result.method, result.clean, result.warnings)
+
+# no file written, work with the Pillow image instead
+result = remove_logo("in.png")
+result.image.show()
+result.save("later.jpg")                          # .jpg -> JPEG, otherwise PNG
+```
+
+`image` can be a path, `bytes`, an open binary file, or a `PIL.Image`.
+
+`Result` fields: `image`, `method` (`alpha`, `inpaint`, `alpha+inpaint`, `none`),
+`detected`, `slot`, `confidence`, `clean`, `warnings`, `output_path`.
+
+### Many images, in parallel
+
+```python
+from gemini_logo_remover import remove_logo_many
+
+items = remove_logo_many(["a.png", "b.png", "c.jpg"], "cleaned/", workers=3)
+for item in items:
+    print(item.source, "ok" if item.ok else f"failed: {item.error}")
+```
+
+One bad file never stops the others; failures are returned in the list. Keep `workers`
+at 3 or less on the free hosted API.
+
+### Command line
+
+```bash
+gemini-logo-remover photo.png                     # writes photo_clean.png next to it
+gemini-logo-remover *.png -o cleaned/ --workers 3
+gemini-logo-remover photo.png --mode alpha        # lossless only
+python -m gemini_logo_remover photo.png           # same thing
+```
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `auto` | `auto`: reverse the watermark, inpaint only what is left. `alpha`: lossless only, never inpaints (image unchanged + a warning if it cannot). `inpaint`: skip alpha. |
+| `sparkle` | `False` | Also inpaint the small V3 slot. Unverified; can damage text near the corner. |
+| `api_url` | hosted API | Your own server. Or set `GEMINI_LOGO_REMOVER_API_URL`. |
+| `api_key` | none | If the server requires a key. Or set `GEMINI_LOGO_REMOVER_API_KEY`. |
+| `retries` | `3` | Extra attempts on 429 / 5xx / network errors / cut-off replies. |
+| `timeout` | `180` | Seconds per request. |
+
+### Errors
+
+- `InvalidImageError` — the input is not a readable image.
+- `ApiError` — the API rejected the request or kept failing. Has `.status` and `.code`.
+- `GeminiLogoRemoverError` — base class of both.
+
+## Limits
+
+The hosted API runs on a free tier. Expect to process a few images at a time, not
+thousands. Point `api_url` at your own deployment of the server for heavy use.
+
+## Development and publishing
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+
+python -m build                      # creates dist/*.whl and dist/*.tar.gz
+twine check dist/*
+twine upload --repository testpypi dist/*   # try it on TestPyPI first
+twine upload dist/*                         # publish to PyPI
+```
+
+Uploading needs a PyPI account and an API token (pypi.org → Account settings → API tokens);
+use `__token__` as the username and the token as the password. Bump `version` in
+`pyproject.toml` (and `__version__`) for every release — PyPI never lets you re-upload the
+same version.

gemini_logo_remover-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gemini-logo-remover"
+version = "0.1.0"
+description = "Remove the Gemini watermark from images with one function call, using the Gemini Logo Remover API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["gemini", "watermark", "logo", "remover", "image", "ai"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics",
+  "Typing :: Typed",
+]
+dependencies = [
+  "requests>=2.28",
+  "Pillow>=9.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.scripts]
+gemini-logo-remover = "gemini_logo_remover.cli:main"
+
+[project.urls]
+Homepage = "https://app.gemini-logo-remover.workers.dev"
+Documentation = "https://app.gemini-logo-remover.workers.dev/developers"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gemini_logo_remover = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gemini_logo_remover-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gemini_logo_remover-0.1.0/src/gemini_logo_remover/__init__.py

@@ -0,0 +1,27 @@
+"""Remove the Gemini watermark from images.
+
+    from gemini_logo_remover import remove_logo
+    remove_logo("in.png", "out.png")
+"""
+from .client import (
+    DEFAULT_API_URL,
+    ApiError,
+    BatchItem,
+    GeminiLogoRemoverError,
+    InvalidImageError,
+    Result,
+    remove_logo,
+    remove_logo_many,
+)
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "ApiError",
+    "BatchItem",
+    "GeminiLogoRemoverError",
+    "InvalidImageError",
+    "Result",
+    "remove_logo",
+    "remove_logo_many",
+]
+__version__ = "0.1.0"

gemini_logo_remover-0.1.0/src/gemini_logo_remover/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gemini_logo_remover-0.1.0/src/gemini_logo_remover/cli.py

@@ -0,0 +1,83 @@
+"""Command line: ``gemini-logo-remover photo.png`` (or ``python -m gemini_logo_remover``)."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from .client import (
+    DEFAULT_API_URL,
+    ENV_API_KEY,
+    ENV_API_URL,
+    BatchItem,
+    remove_logo_many,
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="gemini-logo-remover",
+        description="Remove the Gemini watermark from images using the Gemini Logo Remover API.",
+    )
+    p.add_argument("images", nargs="+", type=Path, help="one or more image files (PNG/JPEG/WebP)")
+    p.add_argument(
+        "-o", "--output-dir", type=Path, default=None,
+        help="where to write results (default: next to each input, as <name>_clean.png)",
+    )
+    p.add_argument("--mode", choices=("auto", "alpha", "inpaint"), default="auto",
+                   help="auto: alpha blend then inpaint only what is left (default); alpha: lossless only")
+    p.add_argument("--format", choices=("png", "jpg"), default="png", help="output format (default: png)")
+    p.add_argument("--sparkle", action="store_true", help="also inpaint the small V3 slot (can damage text)")
+    p.add_argument("--workers", type=int, default=3, help="images processed in parallel (default: 3)")
+    p.add_argument("--api-url", default=None, help=f"API endpoint (default: ${ENV_API_URL} or {DEFAULT_API_URL})")
+    p.add_argument("--api-key", default=None, help=f"API key (default: ${ENV_API_KEY})")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _parser().parse_args(argv)
+    ext = ".jpg" if args.format == "jpg" else ".png"
+
+    failures = 0
+
+    def report(item: BatchItem) -> None:
+        nonlocal failures
+        if item.error is not None:
+            failures += 1
+            print(f"FAILED {item.source}: {item.error}", file=sys.stderr)
+            return
+        r = item.result
+        assert r is not None
+        extra = f" ({'; '.join(r.warnings)})" if r.warnings else ""
+        state = "clean" if r.clean else "residue left"
+        print(f"done   {item.source} -> {r.output_path}  [{r.method}, {state}]{extra}")
+
+    # Group by output directory so each file lands where the user asked.
+    groups: dict = {}
+    for path in args.images:
+        out_dir = args.output_dir or path.resolve().parent
+        groups.setdefault(out_dir, []).append(path)
+
+    for out_dir, paths in groups.items():
+        remove_logo_many(
+            paths,
+            out_dir,
+            workers=args.workers,
+            ext=ext,
+            on_done=report,
+            mode=args.mode,
+            sparkle=args.sparkle,
+            api_url=args.api_url,
+            api_key=args.api_key,
+        )
+
+    total = len(args.images)
+    print(f"{total - failures} succeeded, {failures} failed")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gemini_logo_remover-0.1.0/src/gemini_logo_remover/client.py

@@ -0,0 +1,278 @@
+"""Client for the Gemini Logo Remover API.
+
+The watermark only ever sits in the bottom-right corner, so instead of uploading
+the whole picture this crops that corner (at most 480x480 px), sends the small
+crop to the API, and pastes the cleaned corner back into the original on your
+machine. Uploads are tiny and every pixel outside the corner is returned exactly
+as it was.
+"""
+from __future__ import annotations
+
+import io
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import BinaryIO, Callable, Iterable, List, Optional, Sequence, Tuple, Union
+
+import requests
+from PIL import Image, ImageOps
+
+DEFAULT_API_URL = "https://app.gemini-logo-remover.workers.dev/api/v1/remove"
+ENV_API_URL = "GEMINI_LOGO_REMOVER_API_URL"
+ENV_API_KEY = "GEMINI_LOGO_REMOVER_API_KEY"
+
+#: Corner size in px. Must match the server (it validates the crop dimensions).
+WINDOW = 480
+
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+_MODES = ("auto", "alpha", "inpaint")
+
+ImageInput = Union[str, "os.PathLike[str]", bytes, bytearray, BinaryIO, Image.Image]
+
+
+class GeminiLogoRemoverError(Exception):
+    """Base class for all errors raised by this package."""
+
+
+class ApiError(GeminiLogoRemoverError):
+    """The API answered with an error (or kept failing after all retries)."""
+
+    def __init__(self, message: str, status: Optional[int] = None, code: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class InvalidImageError(GeminiLogoRemoverError):
+    """The input could not be read as an image."""
+
+
+@dataclass
+class Result:
+    """Outcome of one removal."""
+
+    image: Image.Image
+    #: "alpha" (lossless), "inpaint", "alpha+inpaint" or "none" (nothing changed).
+    method: str = "none"
+    detected: bool = False
+    slot: Optional[str] = None
+    confidence: Optional[float] = None
+    #: True when no watermark signal is left in the cleaned slot.
+    clean: bool = True
+    warnings: List[str] = field(default_factory=list)
+    output_path: Optional[Path] = None
+
+    def save(self, path: Union[str, "os.PathLike[str]"], quality: int = 95) -> Path:
+        """Save the cleaned image. ``.jpg`` / ``.jpeg`` -> JPEG, anything else -> PNG."""
+        out = Path(path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if out.suffix.lower() in (".jpg", ".jpeg"):
+            self.image.convert("RGB").save(out, "JPEG", quality=quality, subsampling=0)
+        else:
+            self.image.save(out, "PNG")
+        self.output_path = out
+        return out
+
+
+def _open_image(source: ImageInput) -> Tuple[Image.Image, Optional[str]]:
+    """Return (RGB/RGBA image with EXIF rotation applied, original format)."""
+    try:
+        if isinstance(source, Image.Image):
+            img, fmt = source, source.format
+        elif isinstance(source, (bytes, bytearray)):
+            img = Image.open(io.BytesIO(bytes(source)))
+            fmt = img.format
+        elif hasattr(source, "read"):
+            img = Image.open(io.BytesIO(source.read()))  # type: ignore[union-attr]
+            fmt = img.format
+        else:
+            img = Image.open(source)  # type: ignore[arg-type]
+            fmt = img.format
+        img.load()
+    except (OSError, ValueError) as exc:
+        raise InvalidImageError(f"Could not read the image: {exc}") from exc
+
+    img = ImageOps.exif_transpose(img)
+    if img.mode not in ("RGB", "RGBA"):
+        img = img.convert("RGB")
+    return img, fmt
+
+
+def _headers(response: requests.Response) -> dict:
+    return {k.lower(): v for k, v in response.headers.items() if k.lower().startswith("x-")}
+
+
+def _post_crop(
+    crop_png: bytes,
+    full_size: Tuple[int, int],
+    *,
+    api_url: str,
+    api_key: Optional[str],
+    mode: str,
+    sparkle: bool,
+    timeout: float,
+    retries: int,
+    session: Optional[requests.Session],
+) -> Tuple[Image.Image, dict]:
+    """Send the corner crop; retry transient failures. Returns (cleaned crop, headers)."""
+    http = session or requests
+    headers = {"X-API-Key": api_key} if api_key else {}
+    params = {
+        "mode": mode,
+        "format": "png",
+        "sparkle": "true" if sparkle else "false",
+        "full_size": f"{full_size[0]}x{full_size[1]}",
+    }
+
+    last = "unknown error"
+    last_status: Optional[int] = None
+    last_code: Optional[str] = None
+    for attempt in range(retries + 1):
+        try:
+            response = http.post(
+                api_url,
+                params=params,
+                headers=headers,
+                files={"image": ("corner.png", crop_png, "image/png")},
+                timeout=timeout,
+            )
+            if response.status_code == 200:
+                patch = Image.open(io.BytesIO(response.content))
+                patch.load()  # a cut-off body fails here and is retried
+                return patch, _headers(response)
+
+            last_status = response.status_code
+            try:
+                error = response.json().get("error", {})
+                last_code, last = error.get("code"), error.get("message", response.text[:200])
+            except ValueError:
+                last_code, last = None, response.text[:200] or f"HTTP {response.status_code}"
+            if response.status_code not in _RETRY_STATUS:
+                break
+        except (requests.RequestException, OSError, ValueError) as exc:
+            last_status, last_code, last = None, None, f"{type(exc).__name__}: {exc}"
+        if attempt < retries:
+            time.sleep(2 * (attempt + 1))
+
+    raise ApiError(f"Gemini Logo Remover API failed: {last}", status=last_status, code=last_code)
+
+
+def remove_logo(
+    image: ImageInput,
+    output: Optional[Union[str, "os.PathLike[str]"]] = None,
+    *,
+    api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    mode: str = "auto",
+    sparkle: bool = False,
+    timeout: float = 180.0,
+    retries: int = 3,
+    quality: int = 95,
+    session: Optional[requests.Session] = None,
+) -> Result:
+    """Remove the Gemini watermark from one image.
+
+    :param image: a file path, ``bytes``, an open binary file, or a ``PIL.Image``.
+    :param output: where to save the cleaned image (``.jpg`` -> JPEG, else PNG).
+        When omitted nothing is written; use ``result.image`` / ``result.save()``.
+    :param api_url: API endpoint. Default: ``$GEMINI_LOGO_REMOVER_API_URL`` or the hosted one.
+    :param api_key: API key, if the server requires one. Default: ``$GEMINI_LOGO_REMOVER_API_KEY``.
+    :param mode: ``"auto"`` (alpha blend, inpaint only what is left), ``"alpha"``
+        (lossless only, never inpaints) or ``"inpaint"``.
+    :param sparkle: also inpaint the small V3 slot (unverified; can damage text).
+    :param retries: extra attempts on 429/5xx/network errors/truncated replies.
+    :raises InvalidImageError: the input is not a readable image.
+    :raises ApiError: the API rejected the request or kept failing.
+    """
+    if mode not in _MODES:
+        raise ValueError(f"mode must be one of {_MODES}, got {mode!r}")
+
+    img, _fmt = _open_image(image)
+    width, height = img.size
+    w, h = min(width, WINDOW), min(height, WINDOW)
+    box = (width - w, height - h, width, height)
+
+    buf = io.BytesIO()
+    img.crop(box).convert("RGB").save(buf, "PNG")
+
+    patch, info = _post_crop(
+        buf.getvalue(),
+        (width, height),
+        api_url=api_url or os.environ.get(ENV_API_URL) or DEFAULT_API_URL,
+        api_key=api_key or os.environ.get(ENV_API_KEY),
+        mode=mode,
+        sparkle=sparkle,
+        timeout=timeout,
+        retries=retries,
+        session=session,
+    )
+
+    if patch.size != (w, h):
+        raise ApiError(f"API returned a {patch.size} corner, expected {(w, h)}")
+
+    cleaned = img.copy()
+    cleaned.paste(patch.convert(cleaned.mode), box[:2])
+
+    warnings = [s.strip() for s in info.get("x-warnings", "").split("|") if s.strip()]
+    confidence = info.get("x-detection-confidence")
+    result = Result(
+        image=cleaned,
+        method=info.get("x-removal-method", "none"),
+        detected=info.get("x-watermark-detected", "false").lower() == "true",
+        slot=info.get("x-watermark-slot"),
+        confidence=float(confidence) if confidence else None,
+        clean=info.get("x-clean", "true").lower() == "true",
+        warnings=warnings,
+    )
+    if output is not None:
+        result.save(output, quality=quality)
+    return result
+
+
+@dataclass
+class BatchItem:
+    """One entry of a :func:`remove_logo_many` run."""
+
+    source: Path
+    result: Optional[Result] = None
+    error: Optional[Exception] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+def remove_logo_many(
+    sources: Iterable[Union[str, "os.PathLike[str]"]],
+    output_dir: Union[str, "os.PathLike[str]"],
+    *,
+    workers: int = 3,
+    suffix: str = "_clean",
+    ext: str = ".png",
+    on_done: Optional[Callable[[BatchItem], None]] = None,
+    **options,
+) -> List[BatchItem]:
+    """Clean many files in parallel. Never raises for a single bad file.
+
+    Each input ``photo.jpg`` becomes ``<output_dir>/photo_clean.png``. Failures are
+    returned in the list (``item.error``) so one broken image does not stop the rest.
+    Keep ``workers`` at 3 or less on the free hosted API.
+    """
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    paths: Sequence[Path] = [Path(p) for p in sources]
+
+    def run(path: Path) -> BatchItem:
+        item = BatchItem(source=path)
+        try:
+            item.result = remove_logo(path, out_dir / f"{path.stem}{suffix}{ext}", **options)
+        except Exception as exc:  # noqa: BLE001 - reported per item
+            item.error = exc
+        if on_done:
+            on_done(item)
+        return item
+
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        return list(pool.map(run, paths))

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: gemini-logo-remover
+Version: 0.1.0
+Summary: Remove the Gemini watermark from images with one function call, using the Gemini Logo Remover API.
+License: MIT
+Project-URL: Homepage, https://app.gemini-logo-remover.workers.dev
+Project-URL: Documentation, https://app.gemini-logo-remover.workers.dev/developers
+Keywords: gemini,watermark,logo,remover,image,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: Pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# gemini-logo-remover
+
+Remove the Gemini watermark from images with one function call.
+
+```bash
+pip install gemini-logo-remover
+```
+
+```python
+from gemini_logo_remover import remove_logo
+
+remove_logo("gemini-image.png", "clean.png")
+```
+
+## How it works
+
+The watermark only sits in the bottom-right corner. This package cuts out that corner
+(at most 480×480 px), sends **only that small piece** to the Gemini Logo Remover API,
+and pastes the cleaned corner back into your original image on your machine.
+
+- Uploads are tiny (a few hundred KB), so it is fast.
+- Every pixel outside the corner is returned exactly as it was — the server never
+  re-compresses your picture.
+- The removal itself runs on the hosted API (a Cloudflare Worker), not on your computer.
+  Your images are not stored; only the corner crop is sent.
+
+The server reverses the watermark's alpha blend (lossless) and falls back to AI inpainting
+only for what that cannot explain.
+
+## Usage
+
+### One image
+
+```python
+from gemini_logo_remover import remove_logo
+
+result = remove_logo("in.png", "out.png")        # saves out.png
+print(result.method, result.clean, result.warnings)
+
+# no file written, work with the Pillow image instead
+result = remove_logo("in.png")
+result.image.show()
+result.save("later.jpg")                          # .jpg -> JPEG, otherwise PNG
+```
+
+`image` can be a path, `bytes`, an open binary file, or a `PIL.Image`.
+
+`Result` fields: `image`, `method` (`alpha`, `inpaint`, `alpha+inpaint`, `none`),
+`detected`, `slot`, `confidence`, `clean`, `warnings`, `output_path`.
+
+### Many images, in parallel
+
+```python
+from gemini_logo_remover import remove_logo_many
+
+items = remove_logo_many(["a.png", "b.png", "c.jpg"], "cleaned/", workers=3)
+for item in items:
+    print(item.source, "ok" if item.ok else f"failed: {item.error}")
+```
+
+One bad file never stops the others; failures are returned in the list. Keep `workers`
+at 3 or less on the free hosted API.
+
+### Command line
+
+```bash
+gemini-logo-remover photo.png                     # writes photo_clean.png next to it
+gemini-logo-remover *.png -o cleaned/ --workers 3
+gemini-logo-remover photo.png --mode alpha        # lossless only
+python -m gemini_logo_remover photo.png           # same thing
+```
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `auto` | `auto`: reverse the watermark, inpaint only what is left. `alpha`: lossless only, never inpaints (image unchanged + a warning if it cannot). `inpaint`: skip alpha. |
+| `sparkle` | `False` | Also inpaint the small V3 slot. Unverified; can damage text near the corner. |
+| `api_url` | hosted API | Your own server. Or set `GEMINI_LOGO_REMOVER_API_URL`. |
+| `api_key` | none | If the server requires a key. Or set `GEMINI_LOGO_REMOVER_API_KEY`. |
+| `retries` | `3` | Extra attempts on 429 / 5xx / network errors / cut-off replies. |
+| `timeout` | `180` | Seconds per request. |
+
+### Errors
+
+- `InvalidImageError` — the input is not a readable image.
+- `ApiError` — the API rejected the request or kept failing. Has `.status` and `.code`.
+- `GeminiLogoRemoverError` — base class of both.
+
+## Limits
+
+The hosted API runs on a free tier. Expect to process a few images at a time, not
+thousands. Point `api_url` at your own deployment of the server for heavy use.
+
+## Development and publishing
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+
+python -m build                      # creates dist/*.whl and dist/*.tar.gz
+twine check dist/*
+twine upload --repository testpypi dist/*   # try it on TestPyPI first
+twine upload dist/*                         # publish to PyPI
+```
+
+Uploading needs a PyPI account and an API token (pypi.org → Account settings → API tokens);
+use `__token__` as the username and the token as the password. Bump `version` in
+`pyproject.toml` (and `__version__`) for every release — PyPI never lets you re-upload the
+same version.

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/gemini_logo_remover/__init__.py
+src/gemini_logo_remover/__main__.py
+src/gemini_logo_remover/cli.py
+src/gemini_logo_remover/client.py
+src/gemini_logo_remover/py.typed
+src/gemini_logo_remover.egg-info/PKG-INFO
+src/gemini_logo_remover.egg-info/SOURCES.txt
+src/gemini_logo_remover.egg-info/dependency_links.txt
+src/gemini_logo_remover.egg-info/entry_points.txt
+src/gemini_logo_remover.egg-info/requires.txt
+src/gemini_logo_remover.egg-info/top_level.txt
+tests/test_client.py

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gemini-logo-remover = gemini_logo_remover.cli:main

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.28
+Pillow>=9.0
+
+[dev]
+pytest>=7
+build
+twine

gemini_logo_remover-0.1.0/src/gemini_logo_remover.egg-info/top_level.txt

@@ -0,0 +1 @@
+gemini_logo_remover

gemini_logo_remover-0.1.0/tests/test_client.py

@@ -0,0 +1,232 @@
+"""Tests against a local fake API over real HTTP (no network, no mocks of requests)."""
+from __future__ import annotations
+
+import io
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+from PIL import Image
+
+import gemini_logo_remover.client as client_mod
+from gemini_logo_remover import (
+    ApiError,
+    InvalidImageError,
+    remove_logo,
+    remove_logo_many,
+)
+from gemini_logo_remover.cli import main as cli_main
+
+PNG_START = b"\x89PNG\r\n\x1a\n"
+PNG_END = b"IEND\xaeB`\x82"
+
+
+class FakeApi:
+    """Local server. `script` is a list of behaviours, consumed one per request."""
+
+    def __init__(self) -> None:
+        self.requests: list[dict] = []
+        self.script: list[str] = []
+        self.server = HTTPServer(("127.0.0.1", 0), self._handler())
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+
+    @property
+    def url(self) -> str:
+        return f"http://127.0.0.1:{self.server.server_port}/api/v1/remove"
+
+    def close(self) -> None:
+        self.server.shutdown()
+        self.server.server_close()
+
+    def _handler(self):
+        api = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):  # silence
+                pass
+
+            def do_POST(self):
+                body = self.rfile.read(int(self.headers["Content-Length"]))
+                start = body.index(PNG_START)
+                end = body.index(PNG_END) + len(PNG_END)
+                crop = Image.open(io.BytesIO(body[start:end])).convert("RGB")
+                query = parse_qs(urlparse(self.path).query)
+                api.requests.append(
+                    {"query": {k: v[0] for k, v in query.items()}, "key": self.headers.get("X-API-Key"), "size": crop.size}
+                )
+                action = api.script.pop(0) if api.script else "ok"
+
+                if action.startswith("status:"):
+                    status = int(action.split(":")[1])
+                    payload = json.dumps({"ok": False, "error": {"code": "test_error", "message": f"boom {status}"}}).encode()
+                    self.send_response(status)
+                    self.send_header("Content-Type", "application/json")
+                    self.send_header("Content-Length", str(len(payload)))
+                    self.end_headers()
+                    self.wfile.write(payload)
+                    return
+
+                # "cleaned" corner: paint a marker so we can see the paste-back
+                patch = crop.copy()
+                patch.paste((10, 200, 30), (0, 0, 8, 8))
+                out = io.BytesIO()
+                patch.save(out, "PNG")
+                data = out.getvalue()
+                if action == "truncated":
+                    data = data[: len(data) // 2]
+                self.send_response(200)
+                self.send_header("Content-Type", "image/png")
+                self.send_header("X-Removal-Method", "alpha")
+                self.send_header("X-Watermark-Detected", "true")
+                self.send_header("X-Watermark-Slot", "v2")
+                self.send_header("X-Detection-Confidence", "0.95")
+                self.send_header("X-Clean", "true")
+                self.send_header("X-Warnings", "first | second")
+                self.send_header("Content-Length", str(len(out.getvalue())))  # truncated body < declared
+                self.end_headers()
+                self.wfile.write(data)
+
+        return Handler
+
+
+@pytest.fixture()
+def api(monkeypatch):
+    monkeypatch.setattr(client_mod.time, "sleep", lambda s: None)  # no real backoff waits
+    server = FakeApi()
+    yield server
+    server.close()
+
+
+def make_image(path: Path, size=(1000, 1200), color=(120, 80, 60)) -> Path:
+    Image.new("RGB", size, color).save(path)
+    return path
+
+
+def test_sends_only_the_corner_and_pastes_it_back(tmp_path, api):
+    src = make_image(tmp_path / "in.png")
+    result = remove_logo(src, tmp_path / "out.png", api_url=api.url, api_key="k1", mode="alpha")
+
+    sent = api.requests[0]
+    assert sent["size"] == (480, 480)  # not the whole 1000x1200 image
+    assert sent["query"]["full_size"] == "1000x1200"
+    assert sent["query"]["mode"] == "alpha"
+    assert sent["query"]["format"] == "png"
+    assert sent["query"]["sparkle"] == "false"
+    assert sent["key"] == "k1"
+
+    out = Image.open(tmp_path / "out.png")
+    assert out.size == (1000, 1200)
+    # marker lands at the top-left of the corner window; everything else is untouched
+    assert out.getpixel((1000 - 480 + 2, 1200 - 480 + 2)) == (10, 200, 30)
+    assert out.getpixel((10, 10)) == (120, 80, 60)
+    assert out.getpixel((999, 1199)) == (120, 80, 60)
+
+    assert result.method == "alpha" and result.detected and result.slot == "v2"
+    assert result.confidence == 0.95 and result.clean
+    assert result.warnings == ["first", "second"]
+    assert result.output_path == tmp_path / "out.png"
+
+
+def test_small_image_sends_the_whole_image(tmp_path, api):
+    src = make_image(tmp_path / "s.png", size=(200, 150))
+    remove_logo(src, api_url=api.url)
+    assert api.requests[0]["size"] == (200, 150)
+    assert api.requests[0]["query"]["full_size"] == "200x150"
+
+
+@pytest.mark.parametrize("kind", ["path", "bytes", "file", "pil"])
+def test_accepts_every_input_type(tmp_path, api, kind):
+    src = make_image(tmp_path / "in.png")
+    value = {
+        "path": src,
+        "bytes": src.read_bytes(),
+        "file": open(src, "rb"),
+        "pil": Image.open(src),
+    }[kind]
+    result = remove_logo(value, api_url=api.url)
+    assert result.image.size == (1000, 1200)
+
+
+def test_rgba_input_keeps_alpha(tmp_path, api):
+    path = tmp_path / "a.png"
+    Image.new("RGBA", (600, 600), (1, 2, 3, 128)).save(path)
+    result = remove_logo(path, api_url=api.url)
+    assert result.image.mode == "RGBA"
+
+
+def test_jpeg_output_by_extension(tmp_path, api):
+    src = make_image(tmp_path / "in.png")
+    result = remove_logo(src, tmp_path / "out.jpg", api_url=api.url)
+    assert Image.open(result.output_path).format == "JPEG"
+
+
+def test_retries_transient_errors_then_succeeds(tmp_path, api):
+    api.script = ["status:503", "truncated", "status:429"]
+    src = make_image(tmp_path / "in.png")
+    result = remove_logo(src, api_url=api.url, retries=3)
+    assert len(api.requests) == 4  # 3 failures + 1 success
+    assert result.method == "alpha"
+
+
+def test_gives_up_after_retries(tmp_path, api):
+    api.script = ["status:503"] * 10
+    src = make_image(tmp_path / "in.png")
+    with pytest.raises(ApiError) as exc:
+        remove_logo(src, api_url=api.url, retries=2)
+    assert exc.value.status == 503 and exc.value.code == "test_error"
+    assert len(api.requests) == 3
+
+
+def test_does_not_retry_client_errors(tmp_path, api):
+    api.script = ["status:401"]
+    src = make_image(tmp_path / "in.png")
+    with pytest.raises(ApiError) as exc:
+        remove_logo(src, api_url=api.url, retries=3)
+    assert exc.value.status == 401
+    assert len(api.requests) == 1
+
+
+def test_invalid_image_and_bad_mode(tmp_path, api):
+    bad = tmp_path / "x.png"
+    bad.write_bytes(b"not an image")
+    with pytest.raises(InvalidImageError):
+        remove_logo(bad, api_url=api.url)
+    with pytest.raises(ValueError):
+        remove_logo(make_image(tmp_path / "ok.png"), api_url=api.url, mode="nope")
+    assert api.requests == []
+
+
+def test_env_configuration(tmp_path, api, monkeypatch):
+    monkeypatch.setenv("GEMINI_LOGO_REMOVER_API_URL", api.url)
+    monkeypatch.setenv("GEMINI_LOGO_REMOVER_API_KEY", "from-env")
+    remove_logo(make_image(tmp_path / "in.png"))
+    assert api.requests[0]["key"] == "from-env"
+
+
+def test_many_runs_in_parallel_and_isolates_failures(tmp_path, api):
+    good = [make_image(tmp_path / f"g{i}.png") for i in range(4)]
+    bad = tmp_path / "bad.png"
+    bad.write_bytes(b"junk")
+    items = remove_logo_many(good + [bad], tmp_path / "out", workers=3, api_url=api.url)
+    assert [i.ok for i in items] == [True, True, True, True, False]
+    assert isinstance(items[-1].error, InvalidImageError)
+    assert sorted(p.name for p in (tmp_path / "out").iterdir()) == [f"g{i}_clean.png" for i in range(4)]
+
+
+def test_cli(tmp_path, api, capsys):
+    a = make_image(tmp_path / "a.png")
+    b = make_image(tmp_path / "b.png")
+    code = cli_main([str(a), str(b), "-o", str(tmp_path / "res"), "--api-url", api.url, "--mode", "alpha"])
+    assert code == 0
+    assert (tmp_path / "res" / "a_clean.png").exists() and (tmp_path / "res" / "b_clean.png").exists()
+    assert "2 succeeded, 0 failed" in capsys.readouterr().out
+
+
+def test_cli_reports_failure_exit_code(tmp_path, api):
+    bad = tmp_path / "bad.png"
+    bad.write_bytes(b"junk")
+    assert cli_main([str(bad), "--api-url", api.url]) == 1