poofbg 0.1.0__tar.gz

poofbg-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/

poofbg-0.1.0/LICENSE

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

poofbg-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: poofbg
+Version: 0.1.0
+Summary: Python SDK for the Poof background removal API
+Project-URL: Homepage, https://poof.bg
+Project-URL: Documentation, https://docs.poof.bg
+Project-URL: Repository, https://github.com/poof-bg/py
+Project-URL: Issues, https://github.com/poof-bg/py/issues
+Author-email: Poof <support@poof.bg>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,background-removal,image-processing,poof,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# poofbg
+
+The official Python SDK for the [Poof](https://poof.bg) background removal API.
+
+## Installation
+
+```bash
+pip install poofbg
+```
+
+## Quick Start
+
+```python
+from poof import Poof
+
+# Initialize the client
+client = Poof(api_key="your-api-key")
+
+# Remove background from an image
+result = client.remove_background("photo.jpg")
+
+# Save the result
+result.save("output.png")
+```
+
+## Usage
+
+### Remove Background
+
+```python
+from poof import Poof
+
+client = Poof(api_key="your-api-key")
+
+# From a file path
+result = client.remove_background("image.jpg")
+
+# From bytes
+with open("image.jpg", "rb") as f:
+    image_bytes = f.read()
+result = client.remove_background(image_bytes)
+
+# From a file object
+with open("image.jpg", "rb") as f:
+    result = client.remove_background(f)
+
+# Save the result
+result.save("output.png")
+
+# Or get the bytes directly
+image_data = result.data
+# or: image_data = bytes(result)
+```
+
+### Options
+
+```python
+# Different output format
+result = client.remove_background("photo.jpg", format="webp")
+
+# Crop to subject bounds
+result = client.remove_background("photo.jpg", crop=True)
+
+# RGB output with background color (no transparency)
+result = client.remove_background(
+    "photo.jpg",
+    channels="rgb",
+    bg_color="#ffffff"
+)
+
+# Different size presets
+result = client.remove_background("photo.jpg", size="preview")
+```
+
+### Result Metadata
+
+```python
+result = client.remove_background("photo.jpg")
+
+print(f"Image size: {result.width}x{result.height}")
+print(f"Processing time: {result.processing_time_ms}ms")
+print(f"Content type: {result.content_type}")
+print(f"Request ID: {result.request_id}")
+```
+
+### Account Info
+
+```python
+info = client.me()
+
+print(f"Plan: {info['plan']}")
+print(f"Credits used: {info['usedCredits']} / {info['maxCredits']}")
+```
+
+### Context Manager
+
+```python
+with Poof(api_key="your-api-key") as client:
+    result = client.remove_background("photo.jpg")
+    result.save("output.png")
+# Client is automatically closed
+```
+
+## Error Handling
+
+```python
+from poof import (
+    Poof,
+    PoofError,
+    AuthError,
+    RateLimitError,
+    PaymentRequiredError,
+    ValidationError,
+)
+
+client = Poof(api_key="your-api-key")
+
+try:
+    result = client.remove_background("photo.jpg")
+except AuthError as e:
+    print(f"Authentication failed: {e.message}")
+except PaymentRequiredError as e:
+    print(f"Insufficient credits: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except PoofError as e:
+    print(f"API error: {e.message} (code: {e.code})")
+```
+
+All exceptions include:
+- `message`: Human-readable error description
+- `code`: Machine-readable error code
+- `details`: Additional troubleshooting info
+- `request_id`: Unique ID for support
+- `status_code`: HTTP status code
+
+## Configuration
+
+```python
+# Custom timeout (default: 60 seconds)
+client = Poof(api_key="...", timeout=120)
+
+# Custom base URL
+client = Poof(api_key="...", base_url="https://api.example.com/v1")
+
+# Bring your own httpx client
+import httpx
+
+with httpx.Client(timeout=30, http2=True) as http_client:
+    client = Poof(api_key="...", httpx_client=http_client)
+    result = client.remove_background("photo.jpg")
+```
+
+## API Reference
+
+### `Poof(api_key, *, base_url, timeout, httpx_client)`
+
+Create a new Poof client.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your Poof API key |
+| `base_url` | `str` | `https://api.poof.bg/v1` | API base URL |
+| `timeout` | `float` | `60.0` | Request timeout in seconds |
+| `httpx_client` | `httpx.Client` | `None` | Custom HTTP client |
+
+### `client.remove_background(image, *, format, channels, bg_color, size, crop)`
+
+Remove background from an image.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `image` | `str \| Path \| bytes \| BinaryIO` | required | Image to process |
+| `format` | `"png" \| "jpg" \| "webp"` | `"png"` | Output format |
+| `channels` | `"rgba" \| "rgb"` | `"rgba"` | Color channels |
+| `bg_color` | `str` | `None` | Background color (when `channels="rgb"`) |
+| `size` | `"full" \| "preview" \| "small" \| "medium" \| "large"` | `"full"` | Output size |
+| `crop` | `bool` | `False` | Crop to subject bounds |
+
+Returns a `RemoveBackgroundResult` with:
+- `data`: Image bytes
+- `content_type`: MIME type
+- `width`, `height`: Image dimensions
+- `processing_time_ms`: Processing time
+- `request_id`: Request ID for support
+- `save(path)`: Save to file
+
+### `client.me()`
+
+Get account information.
+
+Returns an `AccountInfo` dict:
+- `organizationId`: Organization ID
+- `plan`: Plan name
+- `maxCredits`: Total credits
+- `usedCredits`: Used credits
+- `autoRechargeThreshold`: Auto-recharge threshold (if enabled)
+
+## License
+
+MIT

poofbg-0.1.0/README.md

@@ -0,0 +1,203 @@
+# poofbg
+
+The official Python SDK for the [Poof](https://poof.bg) background removal API.
+
+## Installation
+
+```bash
+pip install poofbg
+```
+
+## Quick Start
+
+```python
+from poof import Poof
+
+# Initialize the client
+client = Poof(api_key="your-api-key")
+
+# Remove background from an image
+result = client.remove_background("photo.jpg")
+
+# Save the result
+result.save("output.png")
+```
+
+## Usage
+
+### Remove Background
+
+```python
+from poof import Poof
+
+client = Poof(api_key="your-api-key")
+
+# From a file path
+result = client.remove_background("image.jpg")
+
+# From bytes
+with open("image.jpg", "rb") as f:
+    image_bytes = f.read()
+result = client.remove_background(image_bytes)
+
+# From a file object
+with open("image.jpg", "rb") as f:
+    result = client.remove_background(f)
+
+# Save the result
+result.save("output.png")
+
+# Or get the bytes directly
+image_data = result.data
+# or: image_data = bytes(result)
+```
+
+### Options
+
+```python
+# Different output format
+result = client.remove_background("photo.jpg", format="webp")
+
+# Crop to subject bounds
+result = client.remove_background("photo.jpg", crop=True)
+
+# RGB output with background color (no transparency)
+result = client.remove_background(
+    "photo.jpg",
+    channels="rgb",
+    bg_color="#ffffff"
+)
+
+# Different size presets
+result = client.remove_background("photo.jpg", size="preview")
+```
+
+### Result Metadata
+
+```python
+result = client.remove_background("photo.jpg")
+
+print(f"Image size: {result.width}x{result.height}")
+print(f"Processing time: {result.processing_time_ms}ms")
+print(f"Content type: {result.content_type}")
+print(f"Request ID: {result.request_id}")
+```
+
+### Account Info
+
+```python
+info = client.me()
+
+print(f"Plan: {info['plan']}")
+print(f"Credits used: {info['usedCredits']} / {info['maxCredits']}")
+```
+
+### Context Manager
+
+```python
+with Poof(api_key="your-api-key") as client:
+    result = client.remove_background("photo.jpg")
+    result.save("output.png")
+# Client is automatically closed
+```
+
+## Error Handling
+
+```python
+from poof import (
+    Poof,
+    PoofError,
+    AuthError,
+    RateLimitError,
+    PaymentRequiredError,
+    ValidationError,
+)
+
+client = Poof(api_key="your-api-key")
+
+try:
+    result = client.remove_background("photo.jpg")
+except AuthError as e:
+    print(f"Authentication failed: {e.message}")
+except PaymentRequiredError as e:
+    print(f"Insufficient credits: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except PoofError as e:
+    print(f"API error: {e.message} (code: {e.code})")
+```
+
+All exceptions include:
+- `message`: Human-readable error description
+- `code`: Machine-readable error code
+- `details`: Additional troubleshooting info
+- `request_id`: Unique ID for support
+- `status_code`: HTTP status code
+
+## Configuration
+
+```python
+# Custom timeout (default: 60 seconds)
+client = Poof(api_key="...", timeout=120)
+
+# Custom base URL
+client = Poof(api_key="...", base_url="https://api.example.com/v1")
+
+# Bring your own httpx client
+import httpx
+
+with httpx.Client(timeout=30, http2=True) as http_client:
+    client = Poof(api_key="...", httpx_client=http_client)
+    result = client.remove_background("photo.jpg")
+```
+
+## API Reference
+
+### `Poof(api_key, *, base_url, timeout, httpx_client)`
+
+Create a new Poof client.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your Poof API key |
+| `base_url` | `str` | `https://api.poof.bg/v1` | API base URL |
+| `timeout` | `float` | `60.0` | Request timeout in seconds |
+| `httpx_client` | `httpx.Client` | `None` | Custom HTTP client |
+
+### `client.remove_background(image, *, format, channels, bg_color, size, crop)`
+
+Remove background from an image.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `image` | `str \| Path \| bytes \| BinaryIO` | required | Image to process |
+| `format` | `"png" \| "jpg" \| "webp"` | `"png"` | Output format |
+| `channels` | `"rgba" \| "rgb"` | `"rgba"` | Color channels |
+| `bg_color` | `str` | `None` | Background color (when `channels="rgb"`) |
+| `size` | `"full" \| "preview" \| "small" \| "medium" \| "large"` | `"full"` | Output size |
+| `crop` | `bool` | `False` | Crop to subject bounds |
+
+Returns a `RemoveBackgroundResult` with:
+- `data`: Image bytes
+- `content_type`: MIME type
+- `width`, `height`: Image dimensions
+- `processing_time_ms`: Processing time
+- `request_id`: Request ID for support
+- `save(path)`: Save to file
+
+### `client.me()`
+
+Get account information.
+
+Returns an `AccountInfo` dict:
+- `organizationId`: Organization ID
+- `plan`: Plan name
+- `maxCredits`: Total credits
+- `usedCredits`: Used credits
+- `autoRechargeThreshold`: Auto-recharge threshold (if enabled)
+
+## License
+
+MIT

poofbg-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "poofbg"
+version = "0.1.0"
+description = "Python SDK for the Poof background removal API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Poof", email = "support@poof.bg" }
+]
+keywords = [
+    "background-removal",
+    "image-processing",
+    "poof",
+    "api",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "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 :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://poof.bg"
+Documentation = "https://docs.poof.bg"
+Repository = "https://github.com/poof-bg/py"
+Issues = "https://github.com/poof-bg/py/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/poof"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

poofbg-0.1.0/src/poof/__init__.py

@@ -0,0 +1,364 @@
+"""
+Poof - Python SDK for the Poof background removal API.
+
+Simple, clean API for removing backgrounds from images.
+
+Example:
+    from poof import Poof
+
+    client = Poof(api_key="your-api-key")
+    result = client.remove_background("image.jpg")
+
+    # Save the result
+    with open("output.png", "wb") as f:
+        f.write(result)
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from io import IOBase
+from pathlib import Path
+from typing import BinaryIO, Literal, TypedDict, Union
+
+import httpx
+
+from .exceptions import (
+    AuthError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    PoofError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Poof",
+    "PoofError",
+    "AuthError",
+    "RateLimitError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "ValidationError",
+    "ServerError",
+    "AccountInfo",
+    "RemoveBackgroundResult",
+]
+
+DEFAULT_BASE_URL = "https://api.poof.bg/v1"
+DEFAULT_TIMEOUT = 60.0
+
+# Type aliases
+ImageInput = Union[str, Path, bytes, BinaryIO]
+Format = Literal["png", "jpg", "webp"]
+Channels = Literal["rgba", "rgb"]
+Size = Literal["full", "preview", "small", "medium", "large"]
+
+
+class AccountInfo(TypedDict, total=False):
+    """Account information returned by the /me endpoint."""
+
+    organizationId: str
+    plan: str
+    maxCredits: int
+    usedCredits: int
+    autoRechargeThreshold: int | None
+
+
+class RemoveBackgroundResult:
+    """Result of a background removal operation.
+
+    Attributes:
+        data: The processed image bytes.
+        content_type: MIME type of the image (e.g., "image/png").
+        request_id: Unique request identifier for support.
+        processing_time_ms: Processing time in milliseconds.
+        width: Output image width in pixels.
+        height: Output image height in pixels.
+    """
+
+    __slots__ = (
+        "data",
+        "content_type",
+        "request_id",
+        "processing_time_ms",
+        "width",
+        "height",
+    )
+
+    def __init__(
+        self,
+        data: bytes,
+        content_type: str | None = None,
+        request_id: str | None = None,
+        processing_time_ms: int | None = None,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> None:
+        self.data = data
+        self.content_type = content_type
+        self.request_id = request_id
+        self.processing_time_ms = processing_time_ms
+        self.width = width
+        self.height = height
+
+    def __bytes__(self) -> bytes:
+        """Return the image data as bytes."""
+        return self.data
+
+    def __len__(self) -> int:
+        """Return the size of the image data in bytes."""
+        return len(self.data)
+
+    def save(self, path: str | Path) -> None:
+        """Save the image to a file.
+
+        Args:
+            path: Destination file path.
+        """
+        Path(path).write_bytes(self.data)
+
+    def __repr__(self) -> str:
+        return (
+            f"RemoveBackgroundResult("
+            f"size={len(self.data)}, "
+            f"content_type={self.content_type!r}, "
+            f"dimensions={self.width}x{self.height})"
+        )
+
+
+class Poof:
+    """Client for the Poof background removal API.
+
+    Args:
+        api_key: Your Poof API key. Get one at https://dash.poof.bg
+        base_url: API base URL. Defaults to https://api.poof.bg/v1
+        timeout: Request timeout in seconds. Defaults to 60.
+        httpx_client: Optional custom httpx.Client instance.
+
+    Example:
+        >>> from poof import Poof
+        >>> client = Poof(api_key="your-api-key")
+        >>> result = client.remove_background("photo.jpg")
+        >>> result.save("output.png")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        httpx_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._owns_client = httpx_client is None
+        self._client = httpx_client or httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> Poof:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._owns_client:
+            self._client.close()
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get default headers for API requests."""
+        return {
+            "x-api-key": self._api_key,
+            "User-Agent": f"poofbg/{__version__}",
+        }
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle error responses from the API."""
+        try:
+            error_data = response.json()
+            code = error_data.get("code", "unknown_error")
+            message = error_data.get("message", "Unknown error")
+            details = error_data.get("details")
+            request_id = error_data.get("request_id")
+        except Exception:
+            code = "unknown_error"
+            message = response.text or f"HTTP {response.status_code}"
+            details = None
+            request_id = response.headers.get("X-Request-ID")
+
+        error_kwargs = {
+            "message": message,
+            "code": code,
+            "details": details,
+            "request_id": request_id,
+            "status_code": response.status_code,
+        }
+
+        if response.status_code == 401:
+            raise AuthError(**error_kwargs)
+        elif response.status_code == 402:
+            raise PaymentRequiredError(**error_kwargs)
+        elif response.status_code == 403:
+            raise PermissionDeniedError(**error_kwargs)
+        elif response.status_code == 429:
+            raise RateLimitError(**error_kwargs)
+        elif response.status_code == 400:
+            raise ValidationError(**error_kwargs)
+        elif response.status_code >= 500:
+            raise ServerError(**error_kwargs)
+        else:
+            raise PoofError(**error_kwargs)
+
+    def _prepare_image(
+        self, image: ImageInput
+    ) -> tuple[str, bytes, str]:
+        """Prepare image for upload.
+
+        Returns:
+            Tuple of (filename, data, content_type)
+        """
+        if isinstance(image, (str, Path)):
+            path = Path(image)
+            if not path.exists():
+                raise FileNotFoundError(f"Image file not found: {path}")
+            filename = path.name
+            data = path.read_bytes()
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        elif isinstance(image, bytes):
+            filename = "image"
+            data = image
+            content_type = "application/octet-stream"
+        elif isinstance(image, IOBase) or hasattr(image, "read"):
+            # File-like object
+            data = image.read()  # type: ignore
+            filename = getattr(image, "name", "image")
+            if isinstance(filename, (str, Path)):
+                filename = Path(filename).name
+            else:
+                filename = "image"
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        else:
+            raise TypeError(
+                f"image must be a file path, bytes, or file-like object, "
+                f"got {type(image).__name__}"
+            )
+
+        return filename, data, content_type
+
+    def remove_background(
+        self,
+        image: ImageInput,
+        *,
+        format: Format | None = None,
+        channels: Channels | None = None,
+        bg_color: str | None = None,
+        size: Size | None = None,
+        crop: bool | None = None,
+    ) -> RemoveBackgroundResult:
+        """Remove background from an image.
+
+        Args:
+            image: Image to process. Can be a file path (str or Path),
+                bytes, or a file-like object.
+            format: Output format - "png", "jpg", or "webp". Defaults to "png".
+            channels: Color channels - "rgba" for transparency, "rgb" for opaque.
+                Defaults to "rgba".
+            bg_color: Background color when channels="rgb". Can be hex (#ffffff),
+                rgb, or color name.
+            size: Output size preset - "full", "preview", "small", "medium", "large".
+                Defaults to "full".
+            crop: Whether to crop the image to the subject bounds.
+
+        Returns:
+            RemoveBackgroundResult containing the processed image and metadata.
+
+        Raises:
+            FileNotFoundError: If image path doesn't exist.
+            AuthError: Invalid or missing API key.
+            PaymentRequiredError: Insufficient credits.
+            RateLimitError: Rate limit exceeded.
+            ValidationError: Invalid parameters or image.
+            ServerError: Server-side error.
+            PoofError: Other API errors.
+
+        Example:
+            >>> result = client.remove_background("photo.jpg", format="webp", crop=True)
+            >>> result.save("output.webp")
+        """
+        filename, data, content_type = self._prepare_image(image)
+
+        # Build multipart form data
+        files = {"image_file": (filename, data, content_type)}
+        form_data: dict[str, str] = {}
+
+        if format is not None:
+            form_data["format"] = format
+        if channels is not None:
+            form_data["channels"] = channels
+        if bg_color is not None:
+            form_data["bg_color"] = bg_color
+        if size is not None:
+            form_data["size"] = size
+        if crop is not None:
+            form_data["crop"] = str(crop).lower()
+
+        response = self._client.post(
+            f"{self._base_url}/remove",
+            headers=self._get_headers(),
+            files=files,
+            data=form_data if form_data else None,
+        )
+
+        if response.status_code != 200:
+            self._handle_error(response)
+
+        # Extract metadata from headers
+        headers = response.headers
+        processing_time = headers.get("X-Processing-Time-Ms")
+        width = headers.get("X-Image-Width")
+        height = headers.get("X-Image-Height")
+
+        return RemoveBackgroundResult(
+            data=response.content,
+            content_type=headers.get("Content-Type"),
+            request_id=headers.get("X-Request-ID"),
+            processing_time_ms=int(processing_time) if processing_time else None,
+            width=int(width) if width else None,
+            height=int(height) if height else None,
+        )
+
+    def me(self) -> AccountInfo:
+        """Get account information.
+
+        Returns information about the authenticated account including
+        plan details and credit usage.
+
+        Returns:
+            AccountInfo dict with organization details and credit usage.
+
+        Raises:
+            AuthError: Invalid or missing API key.
+            PoofError: Other API errors.
+
+        Example:
+            >>> info = client.me()
+            >>> print(f"Used {info['usedCredits']} of {info['maxCredits']} credits")
+        """
+        response = self._client.get(
+            f"{self._base_url}/me",
+            headers=self._get_headers(),
+        )
+
+        if response.status_code != 200:
+            self._handle_error(response)
+
+        return response.json()

poofbg-0.1.0/src/poof/exceptions.py

@@ -0,0 +1,96 @@
+"""Custom exceptions for the Poof SDK."""
+
+from __future__ import annotations
+
+
+class PoofError(Exception):
+    """Base exception for all Poof API errors.
+
+    Attributes:
+        message: Human-readable error message.
+        code: Machine-readable error code.
+        details: Additional details or troubleshooting steps.
+        request_id: Unique request ID for support.
+        status_code: HTTP status code.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        details: str | None = None,
+        request_id: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        self.message = message
+        self.code = code
+        self.details = details
+        self.request_id = request_id
+        self.status_code = status_code
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        parts = [f"PoofError({self.message!r}"]
+        if self.code:
+            parts.append(f", code={self.code!r}")
+        if self.status_code:
+            parts.append(f", status_code={self.status_code}")
+        if self.request_id:
+            parts.append(f", request_id={self.request_id!r}")
+        parts.append(")")
+        return "".join(parts)
+
+
+class AuthError(PoofError):
+    """Raised when authentication fails (401).
+
+    This typically means the API key is invalid, missing, or revoked.
+    """
+
+    pass
+
+
+class PaymentRequiredError(PoofError):
+    """Raised when the account has insufficient credits (402).
+
+    Upgrade your plan or wait for the next billing cycle.
+    """
+
+    pass
+
+
+class PermissionDeniedError(PoofError):
+    """Raised when access is forbidden (403).
+
+    The account may be suspended or the API key lacks permissions.
+    """
+
+    pass
+
+
+class RateLimitError(PoofError):
+    """Raised when rate limit is exceeded (429).
+
+    Implement exponential backoff and retry.
+    """
+
+    pass
+
+
+class ValidationError(PoofError):
+    """Raised when request validation fails (400).
+
+    Check the parameters and image format.
+    """
+
+    pass
+
+
+class ServerError(PoofError):
+    """Raised when a server-side error occurs (5xx).
+
+    Please try again later.
+    """
+
+    pass