magic_hour 0.35.0__py3-none-any.whl → 0.36.1__py3-none-any.whl

magic_hour/resources/v1/image_projects/README.md

@@ -1,3 +1,54 @@
+# v1_image_projects
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Check results <a name="check-result"></a>
+
+Poll the details API to check on the status of the rendering. Optionally can also download the output
+
+#### Parameters
+
+| Parameter             | Required | Description                                                                                          | Example          |
+| --------------------- | :------: | ---------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`                  |    ✓     | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. | `"cuid-example"` |
+| `wait_for_completion` |    ✗     | Whether to wait for the project to complete.                                                         | `True`           |
+| `download_outputs`    |    ✗     | Whether to download the generated files                                                              | `True`           |
+| `download_directory`  |    ✗     | Directory to save downloaded files (defaults to current directory)                                   | `"./outputs"`    |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.image_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.image_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### Delete image <a name="delete"></a>
 
@@ -83,3 +134,4 @@ res = await client.v1.image_projects.get(id="cuid-example")
 
 ##### Example
 `{"created_at": "1970-01-01T00:00:00", "credits_charged": 5, "downloads": [{"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.png"}], "enabled": True, "error": {"code": "no_source_face", "message": "Please use an image with a detectable face"}, "id": "cuid-example", "image_count": 1, "name": "Example Name", "status": "complete", "total_frame_cost": 5, "type_": "AI_IMAGE"}`
+

magic_hour/resources/v1/image_projects/__init__.py

@@ -1,4 +1,12 @@
-from .client import AsyncImageProjectsClient, ImageProjectsClient
+from .client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+    V1ImageProjectsGetResponseWithDownloads,
+)
 
 
-__all__ = ["AsyncImageProjectsClient", "ImageProjectsClient"]
+__all__ = [
+    "AsyncImageProjectsClient",
+    "ImageProjectsClient",
+    "V1ImageProjectsGetResponseWithDownloads",
+]

magic_hour/resources/v1/image_projects/client.py

@@ -1,3 +1,8 @@
+import asyncio
+import logging
+import os
+import pydantic
+import time
 import typing
 
 from magic_hour.core import (
@@ -6,13 +11,87 @@ from magic_hour.core import (
     SyncBaseClient,
     default_request_options,
 )
+from magic_hour.helpers.download import download_files_async, download_files_sync
 from magic_hour.types import models
 
 
+logger = logging.getLogger(__name__)
+
+
+class V1ImageProjectsGetResponseWithDownloads(models.V1ImageProjectsGetResponse):
+    downloaded_paths: typing.Optional[typing.List[str]] = pydantic.Field(
+        default=None, alias="downloaded_paths"
+    )
+    """
+    The paths to the downloaded files.
+
+    This field is only populated if `download_outputs` is True and the image project is complete.
+    """
+
+
 class ImageProjectsClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def check_result(
+        self,
+        id: str,
+        wait_for_completion: bool,
+        download_outputs: bool,
+        download_directory: typing.Optional[str] = None,
+    ) -> V1ImageProjectsGetResponseWithDownloads:
+        """
+        Check the result of an image project with optional waiting and downloading.
+
+        This method retrieves the status of an image project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the image project
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided,
+                the outputs will be downloaded to the current working directory
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The image project response with optional
+                downloaded file paths included
+        """
+        api_response = self.get(id=id)
+        if not wait_for_completion:
+            response = V1ImageProjectsGetResponseWithDownloads(
+                **api_response.model_dump()
+            )
+            return response
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        status = api_response.status
+
+        while status not in ["complete", "error", "canceled"]:
+            api_response = self.get(id=id)
+            status = api_response.status
+            time.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(
+                f"Image project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1ImageProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1ImageProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = download_files_sync(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1ImageProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None:
@@ -95,6 +174,65 @@ class AsyncImageProjectsClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def check_result(
+        self,
+        id: str,
+        wait_for_completion: bool,
+        download_outputs: bool,
+        download_directory: typing.Optional[str] = None,
+    ) -> V1ImageProjectsGetResponseWithDownloads:
+        """
+        Check the result of an image project with optional waiting and downloading.
+
+        This method retrieves the status of an image project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the image project
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided,
+                the outputs will be downloaded to the current working directory
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The image project response with optional
+                downloaded file paths included
+        """
+        api_response = await self.get(id=id)
+        if not wait_for_completion:
+            response = V1ImageProjectsGetResponseWithDownloads(
+                **api_response.model_dump()
+            )
+            return response
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        status = api_response.status
+
+        while status not in ["complete", "error", "canceled"]:
+            api_response = await self.get(id=id)
+            status = api_response.status
+            await asyncio.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(
+                f"Image project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1ImageProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1ImageProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = await download_files_async(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1ImageProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     async def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None: