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

magic_hour/resources/v1/photo_colorizer/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,82 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.resources.v1.files.client import AsyncFilesClient, FilesClient
+from magic_hour.resources.v1.image_projects.client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+)
 from magic_hour.types import models, params
 
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
 class PhotoColorizerClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1PhotoColorizerGenerateBodyAssets,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate colorized photo (alias for create with additional functionality).
+
+        Colorize image. Each image costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for photo colorization
+            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
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the Photo Colorizer API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.photo_colorizer.generate(
+            assets={"image_file_path": "path/to/black_white_photo.jpg"},
+            name="Colorized Photo",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        image_file_path = assets["image_file_path"]
+        assets["image_file_path"] = file_client.upload_file(file=image_file_path)
+
+        create_response = self.create(
+            assets=assets, name=name, request_options=request_options
+        )
+        logger.info(f"Photo Colorizer response: {create_response}")
+
+        image_projects_client = ImageProjectsClient(base_client=self._base_client)
+        response = image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     def create(
         self,
         *,
@@ -69,6 +139,66 @@ class AsyncPhotoColorizerClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1PhotoColorizerGenerateBodyAssets,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate colorized photo (alias for create with additional functionality).
+
+        Colorize image. Each image costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for photo colorization
+            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
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the Photo Colorizer API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.photo_colorizer.generate(
+            assets={"image_file_path": "path/to/black_white_photo.jpg"},
+            name="Colorized Photo",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        image_file_path = assets["image_file_path"]
+        assets["image_file_path"] = await file_client.upload_file(file=image_file_path)
+
+        create_response = await self.create(
+            assets=assets, name=name, request_options=request_options
+        )
+        logger.info(f"Photo Colorizer response: {create_response}")
+
+        image_projects_client = AsyncImageProjectsClient(base_client=self._base_client)
+        response = await image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     async def create(
         self,
         *,

magic_hour/resources/v1/text_to_video/README.md

@@ -1,3 +1,68 @@
+# v1_text_to_video
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Text To Video Generate Workflow <a name="generate"></a>
+
+The workflow performs the following action
+
+1. upload local assets to Magic Hour storage. So you can pass in a local path instead of having to upload files yourself
+2. trigger a generation
+3. poll for a completion status. This is configurable
+4. if success, download the output to local directory
+
+> [!TIP]
+> This is the recommended way to use the SDK unless you have specific needs where it is necessary to split up the actions.
+
+#### Parameters
+
+In Additional to the parameters listed in the `.create` section below, `.generate` introduces 3 new parameters:
+
+- `wait_for_completion` (bool, default True): Whether to wait for the project to complete.
+- `download_outputs` (bool, default True): Whether to download the generated files
+- `download_directory` (str, optional): Directory to save downloaded files (defaults to current directory)
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.text_to_video.generate(
+    end_seconds=5.0,
+    orientation="landscape",
+    style={"prompt": "a dog running"},
+    name="Text To Video video",
+    resolution="720p",
+    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.text_to_video.generate(
+    end_seconds=5.0,
+    orientation="landscape",
+    style={"prompt": "a dog running"},
+    name="Text To Video video",
+    resolution="720p",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### Text-to-Video <a name="create"></a>
 
@@ -15,6 +80,8 @@ Get more information about this mode at our [product page](https://magichour.ai/
 | `end_seconds` | ✓ | The total duration of the output video in seconds.  The value must be greater than or equal to 5 seconds and less than or equal to 60 seconds.  Note: For 480p resolution, the value must be either 5 or 10. | `5.0` |
 | `orientation` | ✓ | Determines the orientation of the output video | `"landscape"` |
 | `style` | ✓ |  | `{"prompt": "a dog running"}` |
+| `└─ prompt` | ✓ | The prompt used for the video. | `"a dog running"` |
+| `└─ quality_mode` | ✗ | DEPRECATED: Please use `resolution` field instead. For backward compatibility: * `quick` maps to 720p resolution * `studio` maps to 1080p resolution  This field will be removed in a future version. Use the `resolution` field to directly to specify the resolution. | `"quick"` |
 | `name` | ✗ | The name of video. This value is mainly used for your own identification of the video. | `"Text To Video video"` |
 | `resolution` | ✗ | Controls the output video resolution. Defaults to `720p` if not specified.  480p and 720p are available on Creator, Pro, or Business tiers. However, 1080p require Pro or Business tier.  **Options:** - `480p` - Supports only 5 or 10 second videos. Output: 24fps. Cost: 120 credits per 5 seconds. - `720p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 300 credits per 5 seconds. - `1080p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 600 credits per 5 seconds. | `"720p"` |
 
@@ -59,3 +126,4 @@ res = await client.v1.text_to_video.create(
 
 ##### Example
 `{"credits_charged": 450, "estimated_frame_cost": 450, "id": "cuid-example"}`
+

magic_hour/resources/v1/text_to_video/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 import typing_extensions
 
@@ -9,13 +10,92 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.resources.v1.video_projects.client import (
+    AsyncVideoProjectsClient,
+    VideoProjectsClient,
+)
 from magic_hour.types import models, params
 
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
 class TextToVideoClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        end_seconds: float,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1TextToVideoCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            type_utils.NotGiven,
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate text-to-video (alias for create with additional functionality).
+
+        Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+            end_seconds: The total duration of the output video in seconds.
+            orientation: Determines the orientation of the output video
+            style: V1TextToVideoCreateBodyStyle
+            wait_for_completion: Whether to wait for the video 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
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1VideoProjectsGetResponseWithDownloads: The response from the Text-to-Video API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.text_to_video.generate(
+            end_seconds=5.0,
+            orientation="landscape",
+            style={"prompt": "a dog running through a meadow"},
+            resolution="720p",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            end_seconds=end_seconds,
+            orientation=orientation,
+            style=style,
+            name=name,
+            resolution=resolution,
+            request_options=request_options,
+        )
+        logger.info(f"Text-to-Video response: {create_response}")
+
+        video_projects_client = VideoProjectsClient(base_client=self._base_client)
+        response = video_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     def create(
         self,
         *,
@@ -102,6 +182,77 @@ class AsyncTextToVideoClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        end_seconds: float,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1TextToVideoCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            type_utils.NotGiven,
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate text-to-video (alias for create with additional functionality).
+
+        Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+            end_seconds: The total duration of the output video in seconds.
+            orientation: Determines the orientation of the output video
+            style: V1TextToVideoCreateBodyStyle
+            wait_for_completion: Whether to wait for the video 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
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1VideoProjectsGetResponseWithDownloads: The response from the Text-to-Video API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.text_to_video.generate(
+            end_seconds=5.0,
+            orientation="landscape",
+            style={"prompt": "a dog running through a meadow"},
+            resolution="720p",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            end_seconds=end_seconds,
+            orientation=orientation,
+            style=style,
+            name=name,
+            resolution=resolution,
+            request_options=request_options,
+        )
+        logger.info(f"Text-to-Video response: {create_response}")
+
+        video_projects_client = AsyncVideoProjectsClient(base_client=self._base_client)
+        response = await video_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     async def create(
         self,
         *,

magic_hour/resources/v1/video_projects/README.md

@@ -1,3 +1,54 @@
+# v1_video_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 video project. This value is returned by all of the POST APIs that create an video. | `"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.video_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.video_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### Delete video <a name="delete"></a>
 
@@ -83,3 +134,4 @@ res = await client.v1.video_projects.get(id="cuid-example")
 
 ##### Example
 `{"created_at": "1970-01-01T00:00:00", "credits_charged": 450, "download": {"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.mp4"}, "downloads": [{"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.mp4"}], "enabled": True, "end_seconds": 15.0, "error": {"code": "no_source_face", "message": "Please use an image with a detectable face"}, "fps": 30.0, "height": 960, "id": "cuid-example", "name": "Example Name", "start_seconds": 0.0, "status": "complete", "total_frame_cost": 450, "type_": "FACE_SWAP", "width": 512}`
+

magic_hour/resources/v1/video_projects/__init__.py

@@ -1,4 +1,12 @@
-from .client import AsyncVideoProjectsClient, VideoProjectsClient
+from .client import (
+    AsyncVideoProjectsClient,
+    V1VideoProjectsGetResponseWithDownloads,
+    VideoProjectsClient,
+)
 
 
-__all__ = ["AsyncVideoProjectsClient", "VideoProjectsClient"]
+__all__ = [
+    "AsyncVideoProjectsClient",
+    "V1VideoProjectsGetResponseWithDownloads",
+    "VideoProjectsClient",
+]

magic_hour/resources/v1/video_projects/client.py

@@ -1,3 +1,7 @@
+import logging
+import os
+import pydantic
+import time
 import typing
 
 from magic_hour.core import (
@@ -6,13 +10,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 V1VideoProjectsGetResponseWithDownloads(models.V1VideoProjectsGetResponse):
+    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 video project is complete.
+    """
+
+
 class VideoProjectsClient:
     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,
+    ) -> V1VideoProjectsGetResponseWithDownloads:
+        """
+        Check the result of a video project with optional waiting and downloading.
+
+        This method retrieves the status of a video project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the video project
+            wait_for_completion: Whether to wait for the video 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:
+            V1VideoProjectsGetResponseWithDownloads: The video project response with optional
+                downloaded file paths included
+        """
+        api_response = self.get(id=id)
+        if not wait_for_completion:
+            response = V1VideoProjectsGetResponseWithDownloads(
+                **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"Video project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1VideoProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1VideoProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = download_files_sync(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1VideoProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None:
@@ -95,6 +173,65 @@ class AsyncVideoProjectsClient:
     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,
+    ) -> V1VideoProjectsGetResponseWithDownloads:
+        """
+        Check the result of a video project with optional waiting and downloading.
+
+        This method retrieves the status of a video project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the video project
+            wait_for_completion: Whether to wait for the video 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:
+            V1VideoProjectsGetResponseWithDownloads: The video project response with optional
+                downloaded file paths included
+        """
+        api_response = await self.get(id=id)
+        if not wait_for_completion:
+            response = V1VideoProjectsGetResponseWithDownloads(
+                **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
+            time.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(
+                f"Video project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1VideoProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1VideoProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = await download_files_async(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1VideoProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     async def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None: