Add project methods: list_projects, list_project_images, create_project, add_images_to_project

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: felixingla

src/pedra/__init__.py

@@ -9,10 +9,17 @@
 from .client import Pedra
 from .errors import PedraAPIError, PedraError
 from .models import (
+    AddImagesResponse,
     CreditsResponse,
     FeedbackResponse,
     ImageResponse,
+    MusicLibraryResponse,
+    ProjectImagesResponse,
+    ProjectResponse,
+    ProjectsResponse,
+    ScriptResponse,
     VideoResponse,
+    VoiceResponse,
 )
 
 __version__ = "0.1.1"
@@ -25,5 +32,12 @@
     "VideoResponse",
     "CreditsResponse",
     "FeedbackResponse",
+    "ScriptResponse",
+    "VoiceResponse",
+    "MusicLibraryResponse",
+    "ProjectsResponse",
+    "ProjectImagesResponse",
+    "ProjectResponse",
+    "AddImagesResponse",
     "__version__",
 ]

src/pedra/client.py

@@ -8,7 +8,19 @@
 from typing import Any, Dict, List, Optional
 
 from .errors import PedraAPIError, PedraError
-from .models import CreditsResponse, FeedbackResponse, ImageResponse, VideoResponse
+from .models import (
+    AddImagesResponse,
+    CreditsResponse,
+    FeedbackResponse,
+    ImageResponse,
+    MusicLibraryResponse,
+    ProjectImagesResponse,
+    ProjectResponse,
+    ProjectsResponse,
+    ScriptResponse,
+    VideoResponse,
+    VoiceResponse,
+)
 
 DEFAULT_BASE_URL = "https://app.pedra.ai/api"
 # createVideo blocks server-side until the video is rendered (up to ~10 min).
@@ -221,6 +233,149 @@ def create_video(
             raw=data,
         )
 
+    def update_video(
+        self,
+        video_id: str,
+        *,
+        images: Optional[List[Dict[str, Any]]] = None,
+        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:
+        """Edit an existing video without re-rendering unchanged clips.
+
+        Only new/changed photos re-animate (and cost credits); reordering,
+        music, voice, branding and text re-stitch for free. Omit ``images`` to
+        change only audio/text/branding while keeping the timeline; omit
+        ``music``/``voice``/``branding``/ending text to leave them unchanged.
+        Blocks until rendered and returns the new video URL. (``/update_video``)
+        """
+        data = self._post(
+            "/update_video",
+            video_id=video_id,
+            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_id),
+            video_url=data.get("videoUrl", ""),
+            raw=data,
+        )
+
+    def generate_voice_script(
+        self,
+        *,
+        images: Optional[List[Any]] = None,
+        property_characteristics: Optional[List[Dict[str, Any]]] = None,
+        language: Optional[str] = None,
+    ) -> ScriptResponse:
+        """Write a voiceover script from photos (and optional property facts).
+
+        GPT-4o vision reads the images so the script reflects what's shown.
+        ``images`` accepts URL strings or ``{"image_url": ...}`` dicts. Feed the
+        result to :meth:`generate_voice`. (``/generate_voice_script``)
+        """
+        data = self._post(
+            "/generate_voice_script",
+            images=images,
+            property_characteristics=property_characteristics,
+            language=language,
+        )
+        return ScriptResponse(
+            message=data.get("message"),
+            script=data.get("script", ""),
+            raw=data,
+        )
+
+    def generate_voice(
+        self, text: str, *, language: Optional[str] = None
+    ) -> VoiceResponse:
+        """Render a voiceover from a script via TTS.
+
+        Returns an ``audio_id`` to pass as a video's ``voice={"audio_id": ...}``
+        (which also drives synced subtitles). (``/generate_voice``)
+        """
+        data = self._post("/generate_voice", text=text, language=language)
+        return VoiceResponse(
+            message=data.get("message"),
+            audio_id=data.get("audioId", ""),
+            audio_url=data.get("audioUrl", ""),
+            alignment_url=data.get("alignmentUrl"),
+            duration=data.get("duration"),
+            raw=data,
+        )
+
+    def music_library(self) -> MusicLibraryResponse:
+        """List the background-music catalog and voice languages. Read-only.
+
+        Returns the valid ``music`` ``track`` values (genre keys) with labels.
+        (``/music_library``)
+        """
+        data = self._post("/music_library")
+        return MusicLibraryResponse(
+            tracks=data.get("tracks", []),
+            variants_per_track=int(data.get("variantsPerTrack", 0) or 0),
+            default_track=data.get("defaultTrack", ""),
+            voice_languages=data.get("voiceLanguages", []),
+            raw=data,
+        )
+
+    def list_projects(self) -> ProjectsResponse:
+        """List the account's projects (id, name, photo count, appUrl). Use it to
+        find photos already in the account. (``/list_projects``)"""
+        data = self._post("/list_projects")
+        return ProjectsResponse(projects=data.get("projects", []), raw=data)
+
+    def list_project_images(self, project_id: str) -> ProjectImagesResponse:
+        """List a project's photos as public URLs, ready to pass to
+        :meth:`create_video` or the edit methods. (``/list_project_images``)"""
+        data = self._post("/list_project_images", project_id=project_id)
+        return ProjectImagesResponse(
+            project_id=data.get("projectId", project_id),
+            name=data.get("name"),
+            images=data.get("images", []),
+            raw=data,
+        )
+
+    def create_project(self, *, name: Optional[str] = None) -> ProjectResponse:
+        """Create a project. Returns its id and an ``app_url`` to open it in Pedra
+        (the way to add brand-new local photos). (``/create_project``)"""
+        data = self._post("/create_project", name=name)
+        return ProjectResponse(
+            message=data.get("message"),
+            project_id=data.get("projectId", ""),
+            app_url=data.get("appUrl"),
+            raw=data,
+        )
+
+    def add_images_to_project(
+        self, project_id: str, image_urls: List[str]
+    ) -> AddImagesResponse:
+        """Add photos to a project by URL — the server fetches and stores each one,
+        so any public https image URL works. (``/add_images_to_project``)"""
+        data = self._post(
+            "/add_images_to_project", project_id=project_id, image_urls=image_urls
+        )
+        return AddImagesResponse(
+            message=data.get("message"),
+            project_id=data.get("projectId", project_id),
+            added=data.get("added", []),
+            failed=data.get("failed", []),
+            app_url=data.get("appUrl"),
+            raw=data,
+        )
+
     def credits(self) -> CreditsResponse:
         """Read the account's remaining credits and plan. Never deducts credits."""
         data = self._post("/credits")

src/pedra/models.py

@@ -43,3 +43,61 @@ class FeedbackResponse:
     message: Optional[str]
     credited_back: Optional[bool]
     raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class ScriptResponse:
+    message: Optional[str]
+    script: str
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class VoiceResponse:
+    message: Optional[str]
+    audio_id: str
+    audio_url: str
+    alignment_url: Optional[str] = None
+    duration: Optional[int] = None
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class MusicLibraryResponse:
+    tracks: List[Any]
+    variants_per_track: int
+    default_track: str
+    voice_languages: List[str]
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class ProjectsResponse:
+    projects: List[Any]
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class ProjectImagesResponse:
+    project_id: str
+    name: Optional[str]
+    images: List[Any]
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class ProjectResponse:
+    message: Optional[str]
+    project_id: str
+    app_url: Optional[str] = None
+    raw: Any = field(repr=False, default=None)
+
+
+@dataclass
+class AddImagesResponse:
+    message: Optional[str]
+    project_id: str
+    added: List[Any]
+    failed: List[Any]
+    app_url: Optional[str] = None
+    raw: Any = field(repr=False, default=None)

tests/test_client.py

@@ -112,6 +112,111 @@ def test_create_video_deep_camelizes(self):
         self.assertTrue(captured["body"]["isVertical"])
         self.assertEqual(res.video_url, "https://v/1")
 
+    def test_update_video_camelizes_and_targets_endpoint(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"videoId": "v1", "videoUrl": "https://v/2"})
+        )
+        with patcher:
+            res = Pedra("k").update_video(
+                "v1",
+                music={"track": "cinematic"},
+                voice={"audio_id": "a1", "show_subtitles": False},
+            )
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/update_video")
+        self.assertEqual(captured["body"]["videoId"], "v1")
+        self.assertEqual(captured["body"]["voice"]["audioId"], "a1")
+        self.assertFalse(captured["body"]["voice"]["showSubtitles"])
+        # images omitted → patch-style metadata edit
+        self.assertNotIn("images", captured["body"])
+        self.assertEqual(res.video_url, "https://v/2")
+
+    def test_generate_voice(self):
+        patcher, captured = patch_urlopen(
+            json.dumps(
+                {"audioId": "a1", "audioUrl": "https://aud/1", "duration": 7}
+            )
+        )
+        with patcher:
+            res = Pedra("k").generate_voice("A bright home.", language="Español")
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/generate_voice")
+        self.assertEqual(captured["body"]["text"], "A bright home.")
+        self.assertEqual(captured["body"]["language"], "Español")
+        self.assertEqual(res.audio_id, "a1")
+        self.assertEqual(res.duration, 7)
+
+    def test_generate_voice_script(self):
+        patcher, captured = patch_urlopen(json.dumps({"script": "Lovely place."}))
+        with patcher:
+            res = Pedra("k").generate_voice_script(
+                images=["https://a"],
+                property_characteristics=[{"label": "Bedrooms", "value": "3"}],
+            )
+        self.assertEqual(
+            captured["url"], "https://app.pedra.ai/api/generate_voice_script"
+        )
+        self.assertEqual(captured["body"]["images"], ["https://a"])
+        self.assertEqual(
+            captured["body"]["propertyCharacteristics"][0]["label"], "Bedrooms"
+        )
+        self.assertEqual(res.script, "Lovely place.")
+
+    def test_music_library(self):
+        patcher, _ = patch_urlopen(
+            json.dumps(
+                {
+                    "tracks": [{"track": "chill", "label": "Chill Beats"}],
+                    "variantsPerTrack": 6,
+                    "defaultTrack": "chill",
+                    "voiceLanguages": ["English"],
+                }
+            )
+        )
+        with patcher:
+            res = Pedra("k").music_library()
+        self.assertEqual(res.default_track, "chill")
+        self.assertEqual(res.variants_per_track, 6)
+        self.assertEqual(res.tracks[0]["track"], "chill")
+
+    def test_list_projects(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"projects": [{"projectId": "p1", "name": "Listing", "photoCount": 3}]})
+        )
+        with patcher:
+            res = Pedra("k").list_projects()
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/list_projects")
+        self.assertEqual(res.projects[0]["projectId"], "p1")
+
+    def test_list_project_images(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"projectId": "p1", "images": [{"imageId": "i1", "url": "https://img.pedra.ai/i1"}]})
+        )
+        with patcher:
+            res = Pedra("k").list_project_images("p1")
+        self.assertEqual(captured["body"]["projectId"], "p1")
+        self.assertEqual(res.images[0]["url"], "https://img.pedra.ai/i1")
+
+    def test_create_project(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"message": "Project created", "projectId": "p2", "appUrl": "https://app.pedra.ai/?projectId=p2"})
+        )
+        with patcher:
+            res = Pedra("k").create_project(name="New listing")
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/create_project")
+        self.assertEqual(captured["body"]["name"], "New listing")
+        self.assertEqual(res.project_id, "p2")
+        self.assertIn("projectId=p2", res.app_url)
+
+    def test_add_images_to_project_camelizes(self):
+        patcher, captured = patch_urlopen(
+            json.dumps({"message": "Added 1 image(s)", "projectId": "p1", "added": [{"imageId": "i9", "url": "https://img.pedra.ai/i9"}], "failed": []})
+        )
+        with patcher:
+            res = Pedra("k").add_images_to_project("p1", ["https://x/a.jpg"])
+        self.assertEqual(captured["url"], "https://app.pedra.ai/api/add_images_to_project")
+        self.assertEqual(captured["body"]["projectId"], "p1")
+        self.assertEqual(captured["body"]["imageUrls"], ["https://x/a.jpg"])
+        self.assertEqual(res.added[0]["url"], "https://img.pedra.ai/i9")
+
 
 class CamelizeTests(unittest.TestCase):
     def test_to_camel_keys_only(self):