pedra 0.1.0__tar.gz

pedra-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: PYTHONPATH=src python -m unittest discover -s tests -v

pedra-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+.DS_Store
+.pytest_cache/
+.mypy_cache/

pedra-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- Full coverage of the Pedra API: `enhance`, `enhance_and_correct_perspective`,
+  `empty`, `furnish`, `renovation`, `edit_via_prompt`, `sky`, `remove`, `blur`,
+  `create_video`, `credits`, `feedback`.
+- Zero runtime dependencies (standard library only), typed dataclass responses,
+  and typed errors (`PedraError`, `PedraAPIError`).

pedra-0.1.0/LICENSE

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

pedra-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: pedra
+Version: 0.1.0
+Summary: Official Python SDK for the Pedra API — AI photo editing for real estate (virtual staging, renovation, enhancement, video).
+Project-URL: Homepage, https://pedra.ai
+Project-URL: Documentation, https://pedra.ai/api-documentation
+Project-URL: Repository, https://github.com/pedra-ai/pedra-python
+Project-URL: Issues, https://github.com/pedra-ai/pedra-python/issues
+Author-email: Pedra <felix@pedra.ai>
+License: MIT
+License-File: LICENSE
+Keywords: ai,home-staging,image-editing,interior-design,pedra,proptech,real-estate,real-estate-photography,renovation,sdk,virtual-staging
+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.8
+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: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Pedra Python SDK
+
+Official Python SDK for the [Pedra API](https://pedra.ai/api-documentation) — AI photo editing for real estate: virtual staging, renovation, room emptying, image enhancement, sky replacement, object removal/blur, and property videos.
+
+[![PyPI version](https://img.shields.io/pypi/v/pedra.svg)](https://pypi.org/project/pedra/)
+
+```bash
+pip install pedra
+```
+
+Requires Python 3.8+. Zero runtime dependencies (uses the standard library).
+
+## Quick start
+
+```python
+from pedra import Pedra
+
+pedra = Pedra("YOUR_API_KEY")  # or set PEDRA_API_KEY in the environment
+
+result = pedra.furnish(
+    image_url="https://example.com/empty-living-room.jpg",
+    room_type="Living room",
+    style="Minimalist",
+)
+
+print(result.url)   # → the staged image URL
+print(result.urls)  # → all generated URLs
+```
+
+Get your API key from your [Pedra account settings](https://app.pedra.ai). Every method blocks until the asset is ready and returns the final URL(s) — there are no job IDs to poll. The API uses a heartbeat to keep long requests (like `create_video`) alive.
+
+## Authentication
+
+```python
+pedra = Pedra("YOUR_API_KEY")
+# or
+pedra = Pedra()  # reads PEDRA_API_KEY from the environment
+```
+
+Options:
+
+```python
+pedra = Pedra(
+    "YOUR_API_KEY",
+    base_url="https://app.pedra.ai/api",  # default
+    timeout=600.0,                        # seconds, default 10 min (covers create_video)
+)
+```
+
+## Responses
+
+Image methods return an `ImageResponse`, which normalizes the underlying
+endpoint's output (some return a list, some a single object):
+
+```python
+@dataclass
+class ImageResponse:
+    message: Optional[str]
+    urls: List[str]   # every generated asset URL
+    raw: Any          # the untouched API response
+    # .url -> Optional[str]: convenience for the first URL
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+| --- | --- | --- |
+| `enhance(image_url, *, preserve_original_framing=None)` | `/enhance` | `ImageResponse` |
+| `enhance_and_correct_perspective(image_url, *, preserve_original_framing=None)` | `/enhance_and_correct_perspective` | `ImageResponse` |
+| `empty(image_url)` | `/empty_room` | `ImageResponse` |
+| `furnish(image_url, *, room_type=None, style=None, creativity=None)` | `/furnish` | `ImageResponse` |
+| `renovation(image_url, *, style=None, creativity=None, furnish=None, room_type=None)` | `/renovation` | `ImageResponse` |
+| `edit_via_prompt(image_url, prompt)` | `/edit_via_prompt` | `ImageResponse` |
+| `sky(image_url, *, sky_style=None)` | `/sky_blue` | `ImageResponse` |
+| `remove(image_url, mask_url)` | `/remove_object` | `ImageResponse` |
+| `blur(image_url, objects_to_blur)` | `/blur` | `ImageResponse` |
+| `create_video(images, *, music=None, voice=None, branding=None, ending_title=None, ending_subtitle=None, is_vertical=None, property_characteristics=None)` | `/create_video` | `VideoResponse` |
+| `credits()` | `/credits` | `CreditsResponse` |
+| `feedback(*, image_url=None, image_id=None, vote=None, comment=None, credit_back=None)` | `/feedback` | `FeedbackResponse` |
+
+### Examples
+
+```python
+# Enhance — preserve exact framing (verification verticals)
+pedra.enhance(image_url=url, preserve_original_framing=True)
+
+# Empty a room
+result = pedra.empty(url)
+
+# Renovate, furnished, high creativity
+pedra.renovation(url, style="Scandinavian", creativity="High", furnish=True)
+
+# Edit via prompt
+pedra.edit_via_prompt(url, "Add a large green plant in the corner")
+
+# Sky replacement
+pedra.sky(url)
+
+# Remove an object using a mask
+pedra.remove(url, mask_url)
+
+# Blur faces / plates
+pedra.blur(url, ["faces", "license_plates"])
+
+# Credits
+info = pedra.credits()
+print(info.plan, info.credits_remaining)
+
+# Feedback + credit-back on a bad result
+pedra.feedback(image_url=url, vote="down", comment="Artifacts on the wall", credit_back=True)
+```
+
+### Creating a video
+
+`create_video` blocks server-side (up to ~10 minutes) while the video renders,
+then returns the finished URL inline. Image dicts use snake_case keys — the SDK
+converts them to the API's wire format for you:
+
+```python
+video = pedra.create_video(
+    images=[
+        {"image_url": "https://example.com/photo1.jpg", "effect": "zoom-in", "title": "Living room"},
+        {"image_url": "https://example.com/photo2.jpg", "effect": "zoom-out"},
+        {
+            "image_url": "https://example.com/before.jpg",
+            "effect": "transition",
+            "second_image_url": "https://example.com/after.jpg",
+        },
+    ],
+    music={"enabled": True, "track": "calm"},
+    branding={"show_watermark": True},
+    ending_title="Contact us",
+    ending_subtitle="+1 555 0100",
+    is_vertical=False,
+    property_characteristics=[
+        {"label": "Bedrooms", "value": "3"},
+        {"label": "Bathrooms", "value": "2"},
+    ],
+)
+
+print(video.video_url)
+```
+
+Per-image `effect` is one of `zoom-in` (default), `zoom-out`, `transition`
+(requires `second_image_url`), or `static`. Each non-static image costs 5 credits.
+
+## Error handling
+
+```python
+from pedra import PedraAPIError, PedraError
+
+try:
+    pedra.enhance(url)
+except PedraAPIError as err:
+    print(err.status, err, err.body)
+except PedraError as err:
+    print("Client/network error:", err)
+```
+
+`PedraAPIError` is also raised when a long request fails *after* the heartbeat
+has started — the API returns HTTP 200 with an `{"error": ...}` body in that
+case, and the SDK surfaces it as an error anyway.
+
+## Links
+
+- API documentation: https://pedra.ai/api-documentation
+- Pedra: https://pedra.ai
+
+## License
+
+MIT

pedra-0.1.0/PUBLISHING.md

@@ -0,0 +1,46 @@
+# Publishing `pedra` to PyPI
+
+The PyPI name `pedra` is available. The package builds with `hatchling`.
+
+## One-time setup
+
+1. Create a PyPI account and a project API token at https://pypi.org/manage/account/token/
+   (scope it to the `pedra` project after the first upload, or use an account
+   token for the very first upload).
+2. Install the build/upload tools (ideally in a virtualenv):
+   ```bash
+   python -m pip install --upgrade build twine
+   ```
+
+## Test before publishing
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+## Build + upload
+
+```bash
+python -m build              # creates dist/pedra-<version>.tar.gz and .whl
+twine check dist/*           # validates metadata + README rendering
+twine upload dist/*          # prompts for token (use __token__ as username)
+```
+
+Tip: do a dry run against TestPyPI first:
+```bash
+twine upload --repository testpypi dist/*
+pip install --index-url https://test.pypi.org/simple/ pedra
+```
+
+## Releasing a new version
+
+1. Bump `version` in `pyproject.toml` and `src/pedra/__init__.py` (`__version__`).
+2. Update `CHANGELOG.md`.
+3. `rm -rf dist && python -m build && twine upload dist/*`.
+4. Tag the release: `git tag v<version> && git push --tags`.
+
+## CI
+
+`.github/workflows/ci.yml` runs the test suite on Python 3.8–3.12 for every push
+and PR. Consider adding a publish job using PyPI Trusted Publishing (OIDC) gated
+on tags.

pedra-0.1.0/README.md

@@ -0,0 +1,171 @@
+# Pedra Python SDK
+
+Official Python SDK for the [Pedra API](https://pedra.ai/api-documentation) — AI photo editing for real estate: virtual staging, renovation, room emptying, image enhancement, sky replacement, object removal/blur, and property videos.
+
+[![PyPI version](https://img.shields.io/pypi/v/pedra.svg)](https://pypi.org/project/pedra/)
+
+```bash
+pip install pedra
+```
+
+Requires Python 3.8+. Zero runtime dependencies (uses the standard library).
+
+## Quick start
+
+```python
+from pedra import Pedra
+
+pedra = Pedra("YOUR_API_KEY")  # or set PEDRA_API_KEY in the environment
+
+result = pedra.furnish(
+    image_url="https://example.com/empty-living-room.jpg",
+    room_type="Living room",
+    style="Minimalist",
+)
+
+print(result.url)   # → the staged image URL
+print(result.urls)  # → all generated URLs
+```
+
+Get your API key from your [Pedra account settings](https://app.pedra.ai). Every method blocks until the asset is ready and returns the final URL(s) — there are no job IDs to poll. The API uses a heartbeat to keep long requests (like `create_video`) alive.
+
+## Authentication
+
+```python
+pedra = Pedra("YOUR_API_KEY")
+# or
+pedra = Pedra()  # reads PEDRA_API_KEY from the environment
+```
+
+Options:
+
+```python
+pedra = Pedra(
+    "YOUR_API_KEY",
+    base_url="https://app.pedra.ai/api",  # default
+    timeout=600.0,                        # seconds, default 10 min (covers create_video)
+)
+```
+
+## Responses
+
+Image methods return an `ImageResponse`, which normalizes the underlying
+endpoint's output (some return a list, some a single object):
+
+```python
+@dataclass
+class ImageResponse:
+    message: Optional[str]
+    urls: List[str]   # every generated asset URL
+    raw: Any          # the untouched API response
+    # .url -> Optional[str]: convenience for the first URL
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+| --- | --- | --- |
+| `enhance(image_url, *, preserve_original_framing=None)` | `/enhance` | `ImageResponse` |
+| `enhance_and_correct_perspective(image_url, *, preserve_original_framing=None)` | `/enhance_and_correct_perspective` | `ImageResponse` |
+| `empty(image_url)` | `/empty_room` | `ImageResponse` |
+| `furnish(image_url, *, room_type=None, style=None, creativity=None)` | `/furnish` | `ImageResponse` |
+| `renovation(image_url, *, style=None, creativity=None, furnish=None, room_type=None)` | `/renovation` | `ImageResponse` |
+| `edit_via_prompt(image_url, prompt)` | `/edit_via_prompt` | `ImageResponse` |
+| `sky(image_url, *, sky_style=None)` | `/sky_blue` | `ImageResponse` |
+| `remove(image_url, mask_url)` | `/remove_object` | `ImageResponse` |
+| `blur(image_url, objects_to_blur)` | `/blur` | `ImageResponse` |
+| `create_video(images, *, music=None, voice=None, branding=None, ending_title=None, ending_subtitle=None, is_vertical=None, property_characteristics=None)` | `/create_video` | `VideoResponse` |
+| `credits()` | `/credits` | `CreditsResponse` |
+| `feedback(*, image_url=None, image_id=None, vote=None, comment=None, credit_back=None)` | `/feedback` | `FeedbackResponse` |
+
+### Examples
+
+```python
+# Enhance — preserve exact framing (verification verticals)
+pedra.enhance(image_url=url, preserve_original_framing=True)
+
+# Empty a room
+result = pedra.empty(url)
+
+# Renovate, furnished, high creativity
+pedra.renovation(url, style="Scandinavian", creativity="High", furnish=True)
+
+# Edit via prompt
+pedra.edit_via_prompt(url, "Add a large green plant in the corner")
+
+# Sky replacement
+pedra.sky(url)
+
+# Remove an object using a mask
+pedra.remove(url, mask_url)
+
+# Blur faces / plates
+pedra.blur(url, ["faces", "license_plates"])
+
+# Credits
+info = pedra.credits()
+print(info.plan, info.credits_remaining)
+
+# Feedback + credit-back on a bad result
+pedra.feedback(image_url=url, vote="down", comment="Artifacts on the wall", credit_back=True)
+```
+
+### Creating a video
+
+`create_video` blocks server-side (up to ~10 minutes) while the video renders,
+then returns the finished URL inline. Image dicts use snake_case keys — the SDK
+converts them to the API's wire format for you:
+
+```python
+video = pedra.create_video(
+    images=[
+        {"image_url": "https://example.com/photo1.jpg", "effect": "zoom-in", "title": "Living room"},
+        {"image_url": "https://example.com/photo2.jpg", "effect": "zoom-out"},
+        {
+            "image_url": "https://example.com/before.jpg",
+            "effect": "transition",
+            "second_image_url": "https://example.com/after.jpg",
+        },
+    ],
+    music={"enabled": True, "track": "calm"},
+    branding={"show_watermark": True},
+    ending_title="Contact us",
+    ending_subtitle="+1 555 0100",
+    is_vertical=False,
+    property_characteristics=[
+        {"label": "Bedrooms", "value": "3"},
+        {"label": "Bathrooms", "value": "2"},
+    ],
+)
+
+print(video.video_url)
+```
+
+Per-image `effect` is one of `zoom-in` (default), `zoom-out`, `transition`
+(requires `second_image_url`), or `static`. Each non-static image costs 5 credits.
+
+## Error handling
+
+```python
+from pedra import PedraAPIError, PedraError
+
+try:
+    pedra.enhance(url)
+except PedraAPIError as err:
+    print(err.status, err, err.body)
+except PedraError as err:
+    print("Client/network error:", err)
+```
+
+`PedraAPIError` is also raised when a long request fails *after* the heartbeat
+has started — the API returns HTTP 200 with an `{"error": ...}` body in that
+case, and the SDK surfaces it as an error anyway.
+
+## Links
+
+- API documentation: https://pedra.ai/api-documentation
+- Pedra: https://pedra.ai
+
+## License
+
+MIT

pedra-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pedra"
+version = "0.1.0"
+description = "Official Python SDK for the Pedra API — AI photo editing for real estate (virtual staging, renovation, enhancement, video)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Pedra", email = "felix@pedra.ai" }]
+keywords = [
+    "pedra",
+    "real-estate",
+    "proptech",
+    "virtual-staging",
+    "home-staging",
+    "renovation",
+    "interior-design",
+    "ai",
+    "image-editing",
+    "real-estate-photography",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://pedra.ai"
+Documentation = "https://pedra.ai/api-documentation"
+Repository = "https://github.com/pedra-ai/pedra-python"
+Issues = "https://github.com/pedra-ai/pedra-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pedra"]

pedra-0.1.0/src/pedra/__init__.py

@@ -0,0 +1,29 @@
+"""Official Python SDK for the Pedra API.
+
+>>> from pedra import Pedra
+>>> pedra = Pedra("YOUR_API_KEY")
+>>> result = pedra.furnish(image_url="https://example.com/room.jpg", style="Minimalist")
+>>> print(result.url)
+"""
+
+from .client import Pedra
+from .errors import PedraAPIError, PedraError
+from .models import (
+    CreditsResponse,
+    FeedbackResponse,
+    ImageResponse,
+    VideoResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Pedra",
+    "PedraError",
+    "PedraAPIError",
+    "ImageResponse",
+    "VideoResponse",
+    "CreditsResponse",
+    "FeedbackResponse",
+    "__version__",
+]

pedra-0.1.0/src/pedra/client.py

@@ -0,0 +1,308 @@
+"""Synchronous client for the Pedra API."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .errors import PedraAPIError, PedraError
+from .models import CreditsResponse, FeedbackResponse, ImageResponse, VideoResponse
+
+DEFAULT_BASE_URL = "https://app.pedra.ai/api"
+# createVideo blocks server-side until the video is rendered (up to ~10 min).
+DEFAULT_TIMEOUT = 600.0
+
+
+def _to_camel(key: str) -> str:
+    """Convert a snake_case key to camelCase (the API's wire format)."""
+    head, *tail = key.split("_")
+    return head + "".join(word[:1].upper() + word[1:] for word in tail)
+
+
+def _camelize(value: Any) -> Any:
+    """Recursively convert dict keys from snake_case to camelCase.
+
+    Only keys are transformed; string values (URLs, prompts, labels) are left
+    untouched. This lets callers use Pythonic snake_case everywhere while the
+    request body matches the camelCase the API expects.
+    """
+    if isinstance(value, dict):
+        return {_to_camel(k): _camelize(v) for k, v in value.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        return [_camelize(v) for v in value]
+    return value
+
+
+class Pedra:
+    """Client for the Pedra API.
+
+    Every method is a synchronous, blocking call that returns the final
+    asset URL(s) — there are no client-side job IDs to poll (the API keeps long
+    requests alive with a heartbeat).
+
+    Example::
+
+        from pedra import Pedra
+
+        pedra = Pedra("YOUR_API_KEY")
+        result = pedra.furnish(
+            image_url="https://example.com/empty-room.jpg",
+            room_type="Living room",
+            style="Minimalist",
+        )
+        print(result.url)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key or os.environ.get("PEDRA_API_KEY")
+        if not key:
+            raise PedraError(
+                "A Pedra API key is required. Pass it to Pedra(api_key=...) or "
+                "set the PEDRA_API_KEY environment variable."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # --- endpoints -----------------------------------------------------------
+
+    def enhance(
+        self, image_url: str, *, preserve_original_framing: Optional[bool] = None
+    ) -> ImageResponse:
+        """Enhance an image (lighting, color, sharpness)."""
+        return self._image(
+            self._post(
+                "/enhance",
+                image_url=image_url,
+                preserve_original_framing=preserve_original_framing,
+            )
+        )
+
+    def enhance_and_correct_perspective(
+        self, image_url: str, *, preserve_original_framing: Optional[bool] = None
+    ) -> ImageResponse:
+        """Enhance an image and correct its perspective."""
+        return self._image(
+            self._post(
+                "/enhance_and_correct_perspective",
+                image_url=image_url,
+                preserve_original_framing=preserve_original_framing,
+            )
+        )
+
+    def empty(self, image_url: str) -> ImageResponse:
+        """Empty a room — remove all furniture and objects. (``/empty_room``)"""
+        return self._image(self._post("/empty_room", image_url=image_url))
+
+    def furnish(
+        self,
+        image_url: str,
+        *,
+        room_type: Optional[str] = None,
+        style: Optional[str] = None,
+        creativity: Optional[str] = None,
+    ) -> ImageResponse:
+        """Virtually stage / furnish a room."""
+        return self._image(
+            self._post(
+                "/furnish",
+                image_url=image_url,
+                room_type=room_type,
+                style=style,
+                creativity=creativity,
+            )
+        )
+
+    def renovation(
+        self,
+        image_url: str,
+        *,
+        style: Optional[str] = None,
+        creativity: Optional[str] = None,
+        furnish: Any = None,
+        room_type: Optional[str] = None,
+    ) -> ImageResponse:
+        """Renovate a space. ``furnish`` accepts a bool or the explicit string
+        ("With furniture" / "Empty" / "Auto")."""
+        return self._image(
+            self._post(
+                "/renovation",
+                image_url=image_url,
+                style=style,
+                creativity=creativity,
+                furnish=furnish,
+                room_type=room_type,
+            )
+        )
+
+    def edit_via_prompt(self, image_url: str, prompt: str) -> ImageResponse:
+        """Edit an image from a natural-language prompt. (``/edit_via_prompt``)"""
+        return self._image(
+            self._post("/edit_via_prompt", image_url=image_url, prompt=prompt)
+        )
+
+    def sky(self, image_url: str, *, sky_style: Optional[str] = None) -> ImageResponse:
+        """Replace a dull/overcast sky with a clear blue one. (``/sky_blue``)"""
+        return self._image(
+            self._post("/sky_blue", image_url=image_url, sky_style=sky_style)
+        )
+
+    def remove(self, image_url: str, mask_url: str) -> ImageResponse:
+        """Remove an object using a mask. (``/remove_object``)"""
+        return self._image(
+            self._post("/remove_object", image_url=image_url, mask_url=mask_url)
+        )
+
+    def blur(self, image_url: str, objects_to_blur: Any) -> ImageResponse:
+        """Blur objects (e.g. faces, license plates)."""
+        return self._image(
+            self._post("/blur", image_url=image_url, objects_to_blur=objects_to_blur)
+        )
+
+    def create_video(
+        self,
+        images: List[Dict[str, Any]],
+        *,
+        music: Optional[Dict[str, Any]] = None,
+        voice: Optional[Dict[str, Any]] = None,
+        branding: Optional[Dict[str, Any]] = None,
+        ending_title: Optional[str] = None,
+        ending_subtitle: Optional[str] = None,
+        is_vertical: Optional[bool] = None,
+        property_characteristics: Optional[List[Dict[str, Any]]] = None,
+    ) -> VideoResponse:
+        """Create a property video from a list of images.
+
+        Blocks server-side (up to ~10 min) and returns the finished video URL
+        inline. Each image dict accepts snake_case keys (``image_url``,
+        ``effect``, ``second_image_url``, ``subtitle``, ``title``,
+        ``watermark``, ``characteristics``). (``/create_video``)
+        """
+        data = self._post(
+            "/create_video",
+            images=images,
+            music=music,
+            voice=voice,
+            branding=branding,
+            ending_title=ending_title,
+            ending_subtitle=ending_subtitle,
+            is_vertical=is_vertical,
+            property_characteristics=property_characteristics,
+        )
+        return VideoResponse(
+            message=data.get("message"),
+            video_id=data.get("videoId", ""),
+            video_url=data.get("videoUrl", ""),
+            raw=data,
+        )
+
+    def credits(self) -> CreditsResponse:
+        """Read the account's remaining credits and plan. Never deducts credits."""
+        data = self._post("/credits")
+        return CreditsResponse(
+            plan=data.get("plan", "free"),
+            credits_remaining=int(data.get("creditsRemaining", 0) or 0),
+            raw=data,
+        )
+
+    def feedback(
+        self,
+        *,
+        image_url: Optional[str] = None,
+        image_id: Optional[str] = None,
+        vote: Optional[str] = None,
+        comment: Optional[str] = None,
+        credit_back: Optional[bool] = None,
+    ) -> FeedbackResponse:
+        """Submit thumbs up/down feedback on a generated image, with an optional
+        credit-back on a thumbs-down (subject to the API's eligibility rules).
+        Provide one of ``image_url`` or ``image_id``."""
+        data = self._post(
+            "/feedback",
+            image_url=image_url,
+            image_id=image_id,
+            vote=vote,
+            comment=comment,
+            credit_back=credit_back,
+        )
+        return FeedbackResponse(
+            message=data.get("message"),
+            credited_back=data.get("creditedBack", data.get("creditBack")),
+            raw=data,
+        )
+
+    # --- internals -----------------------------------------------------------
+
+    def _post(self, path: str, **params: Any) -> Dict[str, Any]:
+        # Drop unset optionals, then convert keys to the camelCase wire format.
+        body = _camelize({k: v for k, v in params.items() if v is not None})
+        body["apiKey"] = self.api_key
+        payload = json.dumps(body).encode("utf-8")
+
+        request = urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=payload,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                status = response.getcode()
+                text = response.read().decode("utf-8")
+        except urllib.error.HTTPError as err:  # non-2xx
+            text = err.read().decode("utf-8", errors="replace")
+            data = self._parse(text)
+            message = (
+                (data.get("error") or data.get("message"))
+                if isinstance(data, dict)
+                else None
+            ) or f"Request to {path} failed with status {err.code}"
+            raise PedraAPIError(message, status=err.code, body=data) from None
+        except urllib.error.URLError as err:
+            raise PedraError(f"Network error calling {path}: {err.reason}") from err
+        except TimeoutError as err:
+            raise PedraError(
+                f"Request to {path} timed out after {self.timeout}s"
+            ) from err
+
+        data = self._parse(text)
+        if data is None:
+            raise PedraError(f"Could not parse the response from {path}")
+
+        # Heartbeat caveat: a request that runs long and then fails returns HTTP
+        # 200 with an ``{"error": ...}`` body (the 200 header was already sent).
+        if isinstance(data, dict) and data.get("error"):
+            raise PedraAPIError(str(data["error"]), status=status, body=data)
+
+        return data
+
+    @staticmethod
+    def _parse(text: str) -> Any:
+        # json.loads tolerates the leading whitespace the heartbeat prepends.
+        if not text or not text.strip():
+            return None
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return None
+
+    @staticmethod
+    def _image(data: Dict[str, Any]) -> ImageResponse:
+        output = data.get("output")
+        urls: List[str] = []
+        if isinstance(output, list):
+            urls = [o["url"] for o in output if isinstance(o, dict) and o.get("url")]
+        elif isinstance(output, dict) and output.get("url"):
+            urls = [output["url"]]
+        return ImageResponse(message=data.get("message"), urls=urls, raw=data)

pedra-0.1.0/src/pedra/errors.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by the Pedra SDK."""
+
+from typing import Any, Optional
+
+
+class PedraError(Exception):
+    """Base class for every error raised by the SDK.
+
+    Catch this to handle any Pedra-originated failure (network, timeout, bad
+    input, or an API error).
+    """
+
+
+class PedraAPIError(PedraError):
+    """Raised when the API returns an error.
+
+    ``status`` is the HTTP status code. Note: the Pedra API keeps long requests
+    alive with a heartbeat, so a generation that runs long and *then* fails
+    comes back as HTTP 200 with an ``{"error": ...}`` body — in that case
+    ``status`` is 200 but the call still raises this error. ``body`` is the
+    parsed JSON response when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

pedra-0.1.0/src/pedra/models.py

@@ -0,0 +1,45 @@
+"""Typed response models returned by the SDK."""
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+
+@dataclass
+class ImageResponse:
+    """Response from any image-generation endpoint.
+
+    The raw API returns ``output`` as either a list or a single object
+    depending on the endpoint; the SDK normalizes that into ``urls`` (and the
+    convenience ``url`` for the first result).
+    """
+
+    message: Optional[str]
+    urls: List[str]
+    raw: Any = field(repr=False, default=None)
+
+    @property
+    def url(self) -> Optional[str]:
+        """The first generated asset URL, or ``None`` if there were none."""
+        return self.urls[0] if self.urls else None
+
+
+@dataclass
+class VideoResponse:
+    message: Optional[str]
+    video_id: str
+    video_url: str
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class CreditsResponse:
+    plan: str
+    credits_remaining: int
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class FeedbackResponse:
+    message: Optional[str]
+    credited_back: Optional[bool]
+    raw: Any = field(repr=False, default=None)

pedra-0.1.0/tests/test_client.py

@@ -0,0 +1,127 @@
+"""Tests for the Pedra Python client.
+
+Run with: python -m unittest discover -s tests
+"""
+
+import json
+import unittest
+from unittest import mock
+
+from pedra import Pedra, PedraAPIError, PedraError
+from pedra.client import _camelize
+
+
+class FakeResponse:
+    def __init__(self, text, status=200):
+        self._text = text
+        self._status = status
+
+    def read(self):
+        return self._text.encode("utf-8")
+
+    def getcode(self):
+        return self._status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+
+def patch_urlopen(text, status=200):
+    captured = {}
+
+    def fake_urlopen(request, timeout=None):
+        captured["url"] = request.full_url
+        captured["body"] = json.loads(request.data.decode("utf-8"))
+        captured["timeout"] = timeout
+        return FakeResponse(text, status)
+
+    return mock.patch("urllib.request.urlopen", fake_urlopen), captured
+
+
+class ClientTests(unittest.TestCase):
+    def test_requires_api_key(self):
+        with mock.patch.dict("os.environ", {}, clear=True):
+            with self.assertRaises(PedraError):
+                Pedra()
+
+    def test_sends_apikey_and_camelcased_params(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"message": "ok", "output": [{"url": "https://x/1"}]})
+        )
+        with patcher:
+            pedra = Pedra("k")
+            res = pedra.furnish(image_url="https://img", room_type="Living room")
+
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/furnish")
+        self.assertEqual(
+            captured["body"],
+            {"apiKey": "k", "imageUrl": "https://img", "roomType": "Living room"},
+        )
+        self.assertEqual(res.url, "https://x/1")
+        self.assertEqual(res.urls, ["https://x/1"])
+
+    def test_drops_unset_optionals(self):
+        patcher, captured = patch_urlopen(json.dumps({"output": {"url": "u"}}))
+        with patcher:
+            Pedra("k").enhance(image_url="https://img")
+        self.assertNotIn("preserveOriginalFraming", captured["body"])
+
+    def test_normalizes_single_object_output(self):
+        patcher, _ = patch_urlopen(json.dumps({"output": {"url": "https://x/2"}}))
+        with patcher:
+            res = Pedra("k").edit_via_prompt(image_url="https://img", prompt="cozy")
+        self.assertEqual(res.url, "https://x/2")
+        self.assertEqual(res.urls, ["https://x/2"])
+
+    def test_tolerates_heartbeat_whitespace(self):
+        patcher, _ = patch_urlopen("    " + json.dumps({"output": [{"url": "https://x/3"}]}))
+        with patcher:
+            res = Pedra("k").enhance(image_url="https://img")
+        self.assertEqual(res.url, "https://x/3")
+
+    def test_raises_on_200_with_error_body(self):
+        patcher, _ = patch_urlopen(json.dumps({"error": "Video processing failed"}))
+        with patcher:
+            with self.assertRaises(PedraAPIError):
+                Pedra("k").create_video(images=[{"image_url": "https://img"}])
+
+    def test_credits(self):
+        patcher, _ = patch_urlopen(json.dumps({"plan": "pro", "creditsRemaining": 42}))
+        with patcher:
+            res = Pedra("k").credits()
+        self.assertEqual(res.plan, "pro")
+        self.assertEqual(res.credits_remaining, 42)
+
+    def test_create_video_deep_camelizes(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"videoId": "v1", "videoUrl": "https://v/1"})
+        )
+        with patcher:
+            res = Pedra("k").create_video(
+                images=[{"image_url": "https://a", "second_image_url": "https://b"}],
+                voice={"enabled": True, "audio_url": "https://aud"},
+                is_vertical=True,
+            )
+        self.assertEqual(captured["body"]["images"][0]["imageUrl"], "https://a")
+        self.assertEqual(captured["body"]["images"][0]["secondImageUrl"], "https://b")
+        self.assertEqual(captured["body"]["voice"]["audioUrl"], "https://aud")
+        self.assertTrue(captured["body"]["isVertical"])
+        self.assertEqual(res.video_url, "https://v/1")
+
+
+class CamelizeTests(unittest.TestCase):
+    def test_to_camel_keys_only(self):
+        self.assertEqual(
+            _camelize({"image_url": "x", "preserve_original_framing": True}),
+            {"imageUrl": "x", "preserveOriginalFraming": True},
+        )
+
+    def test_drops_none_values(self):
+        self.assertEqual(_camelize({"a_b": None, "c_d": 1}), {"cD": 1})
+
+
+if __name__ == "__main__":
+    unittest.main()