magic_hour 0.34.0__py3-none-any.whl → 0.36.0__py3-none-any.whl

magic_hour/resources/v1/face_swap/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,130 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.resources.v1.files.client import AsyncFilesClient, FilesClient
+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 FaceSwapClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1FaceSwapGenerateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        height: typing.Union[
+            typing.Optional[int], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1FaceSwapCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        width: typing.Union[
+            typing.Optional[int], 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 face swap video (alias for create with additional functionality).
+
+        Create a Face Swap 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:
+            height: `height` is deprecated and no longer influences the output video's resolution.
+            name: The name of video. This value is mainly used for your own identification of the video.
+            width: `width` is deprecated and no longer influences the output video's resolution.
+            assets: Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used
+            end_seconds: The end time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.1, and more than the start_seconds.
+            start_seconds: The start time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.
+            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 Face Swap API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.face_swap.generate(
+            assets={
+                "face_swap_mode": "all-faces",
+                "video_file_path": "path/to/video.mp4",
+                "video_source": "file",
+                "image_file_path": "path/to/image.png",
+            },
+            end_seconds=15.0,
+            start_seconds=0.0,
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        # Upload image file if provided (required for all-faces mode)
+        if "image_file_path" in assets and assets["image_file_path"]:
+            image_file_path = assets["image_file_path"]
+            assets["image_file_path"] = file_client.upload_file(file=image_file_path)
+
+        # Upload video file if video_source is "file" and video_file_path is provided
+        if (
+            assets.get("video_source") == "file"
+            and "video_file_path" in assets
+            and assets["video_file_path"]
+        ):
+            video_file_path = assets["video_file_path"]
+            assets["video_file_path"] = file_client.upload_file(file=video_file_path)
+
+        # Upload face mappings if present
+        if "face_mappings" in assets and assets["face_mappings"]:
+            for face_mapping in assets["face_mappings"]:
+                if "new_face" in face_mapping and face_mapping["new_face"]:
+                    new_face_file_path = face_mapping["new_face"]
+                    face_mapping["new_face"] = file_client.upload_file(
+                        file=new_face_file_path
+                    )
+
+        create_response = self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            height=height,
+            name=name,
+            style=style,
+            width=width,
+            request_options=request_options,
+        )
+        logger.info(f"Face Swap 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,
         *,
@@ -27,6 +145,9 @@ class FaceSwapClient:
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1FaceSwapCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
         width: typing.Union[
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -43,23 +164,22 @@ class FaceSwapClient:
         POST /v1/face-swap
 
         Args:
-            height: Used to determine the dimensions of the output video.
-
-        * If height is provided, width will also be required. The larger value between width and height will be used to determine the maximum output resolution while maintaining the original aspect ratio.
-        * If both height and width are omitted, the video will be resized according to your subscription's maximum resolution, while preserving aspect ratio.
+            height: `height` is deprecated and no longer influences the output video's resolution.
 
-        Note: if the video's original resolution is less than the maximum, the video will not be resized.
+        Output resolution is determined by the **minimum** of:
+        - The resolution of the input video
+        - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.
 
-        See our [pricing page](https://magichour.ai/pricing) for more details.
+        This field is retained only for backward compatibility and will be removed in a future release.
             name: The name of video. This value is mainly used for your own identification of the video.
-            width: Used to determine the dimensions of the output video.
+            style: Style of the face swap video.
+            width: `width` is deprecated and no longer influences the output video's resolution.
 
-        * If width is provided, height will also be required. The larger value between width and height will be used to determine the maximum output resolution while maintaining the original aspect ratio.
-        * If both height and width are omitted, the video will be resized according to your subscription's maximum resolution, while preserving aspect ratio.
+        Output resolution is determined by the **minimum** of:
+        - The resolution of the input video
+        - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.
 
-        Note: if the video's original resolution is less than the maximum, the video will not be resized.
-
-        See our [pricing page](https://magichour.ai/pricing) for more details.
+        This field is retained only for backward compatibility and will be removed in a future release.
             assets: Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used
             end_seconds: The end time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.1, and more than the start_seconds.
             start_seconds: The start time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.
@@ -89,9 +209,8 @@ class FaceSwapClient:
             },
             end_seconds=15.0,
             start_seconds=0.0,
-            height=960,
             name="Face Swap video",
-            width=512,
+            style={"version": "default"},
         )
         ```
         """
@@ -99,6 +218,7 @@ class FaceSwapClient:
             item={
                 "height": height,
                 "name": name,
+                "style": style,
                 "width": width,
                 "assets": assets,
                 "end_seconds": end_seconds,
@@ -120,6 +240,118 @@ class AsyncFaceSwapClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1FaceSwapGenerateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        height: typing.Union[
+            typing.Optional[int], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1FaceSwapCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        width: typing.Union[
+            typing.Optional[int], 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 face swap video (alias for create with additional functionality).
+
+        Create a Face Swap 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:
+            height: `height` is deprecated and no longer influences the output video's resolution.
+            name: The name of video. This value is mainly used for your own identification of the video.
+            width: `width` is deprecated and no longer influences the output video's resolution.
+            assets: Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used
+            end_seconds: The end time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.1, and more than the start_seconds.
+            start_seconds: The start time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.
+            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 Face Swap API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.face_swap.generate(
+            assets={
+                "face_swap_mode": "all-faces",
+                "video_file_path": "path/to/video.mp4",
+                "video_source": "file",
+                "image_file_path": "path/to/image.png",
+            },
+            end_seconds=15.0,
+            start_seconds=0.0,
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        # Upload image file if provided (required for all-faces mode)
+        if "image_file_path" in assets and assets["image_file_path"]:
+            image_file_path = assets["image_file_path"]
+            assets["image_file_path"] = await file_client.upload_file(
+                file=image_file_path
+            )
+
+        # Upload video file if video_source is "file" and video_file_path is provided
+        if (
+            assets.get("video_source") == "file"
+            and "video_file_path" in assets
+            and assets["video_file_path"]
+        ):
+            video_file_path = assets["video_file_path"]
+            assets["video_file_path"] = await file_client.upload_file(
+                file=video_file_path
+            )
+
+        # Upload face mappings if present
+        if "face_mappings" in assets and assets["face_mappings"]:
+            for face_mapping in assets["face_mappings"]:
+                if "new_face" in face_mapping and face_mapping["new_face"]:
+                    new_face_file_path = face_mapping["new_face"]
+                    face_mapping["new_face"] = await file_client.upload_file(
+                        file=new_face_file_path
+                    )
+
+        create_response = await self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            height=height,
+            name=name,
+            style=style,
+            width=width,
+            request_options=request_options,
+        )
+        logger.info(f"Face Swap 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,
         *,
@@ -132,6 +364,9 @@ class AsyncFaceSwapClient:
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1FaceSwapCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
         width: typing.Union[
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -148,23 +383,22 @@ class AsyncFaceSwapClient:
         POST /v1/face-swap
 
         Args:
-            height: Used to determine the dimensions of the output video.
-
-        * If height is provided, width will also be required. The larger value between width and height will be used to determine the maximum output resolution while maintaining the original aspect ratio.
-        * If both height and width are omitted, the video will be resized according to your subscription's maximum resolution, while preserving aspect ratio.
+            height: `height` is deprecated and no longer influences the output video's resolution.
 
-        Note: if the video's original resolution is less than the maximum, the video will not be resized.
+        Output resolution is determined by the **minimum** of:
+        - The resolution of the input video
+        - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.
 
-        See our [pricing page](https://magichour.ai/pricing) for more details.
+        This field is retained only for backward compatibility and will be removed in a future release.
             name: The name of video. This value is mainly used for your own identification of the video.
-            width: Used to determine the dimensions of the output video.
-
-        * If width is provided, height will also be required. The larger value between width and height will be used to determine the maximum output resolution while maintaining the original aspect ratio.
-        * If both height and width are omitted, the video will be resized according to your subscription's maximum resolution, while preserving aspect ratio.
+            style: Style of the face swap video.
+            width: `width` is deprecated and no longer influences the output video's resolution.
 
-        Note: if the video's original resolution is less than the maximum, the video will not be resized.
+        Output resolution is determined by the **minimum** of:
+        - The resolution of the input video
+        - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.
 
-        See our [pricing page](https://magichour.ai/pricing) for more details.
+        This field is retained only for backward compatibility and will be removed in a future release.
             assets: Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used
             end_seconds: The end time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.1, and more than the start_seconds.
             start_seconds: The start time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.
@@ -194,9 +428,8 @@ class AsyncFaceSwapClient:
             },
             end_seconds=15.0,
             start_seconds=0.0,
-            height=960,
             name="Face Swap video",
-            width=512,
+            style={"version": "default"},
         )
         ```
         """
@@ -204,6 +437,7 @@ class AsyncFaceSwapClient:
             item={
                 "height": height,
                 "name": name,
+                "style": style,
                 "width": width,
                 "assets": assets,
                 "end_seconds": end_seconds,

magic_hour/resources/v1/face_swap_photo/README.md

@@ -1,3 +1,82 @@
+# v1_face_swap_photo
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Face Swap Photo 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.face_swap_photo.generate(
+    assets={
+        "face_mappings": [
+            {
+                "new_face": "/path/to/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
+        "source_file_path": "/path/to/1234.png",
+        "target_file_path": "/path/to/1234.png",
+    },
+    name="Face Swap image",
+    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.face_swap_photo.generate(
+    assets={
+        "face_mappings": [
+            {
+                "new_face": "/path/to/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
+        "source_file_path": "/path/to/1234.png",
+        "target_file_path": "/path/to/1234.png",
+    },
+    name="Face Swap image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### Face Swap Photo <a name="create"></a>
 
@@ -10,6 +89,10 @@ Create a face swap photo. Each photo costs 5 credits. The height/width of the ou
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `assets` | ✓ | Provide the assets for face swap photo | `{"face_mappings": [{"new_face": "api-assets/id/1234.png", "original_face": "api-assets/id/0-0.png"}], "face_swap_mode": "all-faces", "source_file_path": "api-assets/id/1234.png", "target_file_path": "api-assets/id/1234.png"}` |
+| `└─ face_mappings` | ✗ | This is the array of face mappings used for multiple face swap. The value is required if `face_swap_mode` is `individual-faces`. | `[{"new_face": "api-assets/id/1234.png", "original_face": "api-assets/id/0-0.png"}]` |
+| `└─ face_swap_mode` | ✗ | The mode of face swap. * `all-faces` - Swap all faces in the target image or video. `source_file_path` is required. * `individual-faces` - Swap individual faces in the target image or video. `source_faces` is required. | `"all-faces"` |
+| `└─ source_file_path` | ✗ | This is the image from which the face is extracted. The value is required if `face_swap_mode` is `all-faces`.  This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).  Please refer to the [Input File documentation](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) to learn more.  | `"api-assets/id/1234.png"` |
+| `└─ target_file_path` | ✓ | This is the image where the face from the source image will be placed. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).  Please refer to the [Input File documentation](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) to learn more.  | `"api-assets/id/1234.png"` |
 | `name` | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Face Swap image"` |
 
 #### Synchronous Client
@@ -67,3 +150,4 @@ res = await client.v1.face_swap_photo.create(
 
 ##### Example
 `{"credits_charged": 5, "frame_cost": 5, "id": "cuid-example"}`
+

magic_hour/resources/v1/face_swap_photo/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,101 @@ 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 FaceSwapPhotoClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1FaceSwapPhotoGenerateBodyAssets,
+        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 face swap photo (alias for create with additional functionality).
+
+        Swap faces in a photo using AI. Each face swap 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 face swap photo
+            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 Face Swap Photo API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        client.v1.face_swap_photo.generate(
+            assets={
+                "face_swap_mode": "all-faces",
+                "source_file_path": "api-assets/id/1234.png",
+                "target_file_path": "api-assets/id/1234.png",
+            },
+            name="Face Swap image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="./outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        # Upload source image file if present
+        if "source_file_path" in assets and assets["source_file_path"]:
+            source_file_path = assets["source_file_path"]
+            assets["source_file_path"] = file_client.upload_file(file=source_file_path)
+
+        # Upload target image file
+        target_file_path = assets["target_file_path"]
+        assets["target_file_path"] = file_client.upload_file(file=target_file_path)
+
+        # Upload face mappings if present
+        if "face_mappings" in assets and assets["face_mappings"]:
+            for face_mapping in assets["face_mappings"]:
+                if "new_face" in face_mapping and face_mapping["new_face"]:
+                    new_face_file_path = face_mapping["new_face"]
+                    face_mapping["new_face"] = file_client.upload_file(
+                        file=new_face_file_path
+                    )
+
+        create_response = self.create(
+            assets=assets, name=name, request_options=request_options
+        )
+        logger.info(f"Face Swap Photo 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,
         *,
@@ -79,6 +168,89 @@ class AsyncFaceSwapPhotoClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1FaceSwapPhotoGenerateBodyAssets,
+        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 face swap photo (alias for create with additional functionality).
+
+        Swap faces in a photo using AI. Each face swap 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 face swap photo
+            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 Face Swap Photo API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        await client.v1.face_swap_photo.generate(
+            assets={
+                "face_swap_mode": "all-faces",
+                "source_file_path": "api-assets/id/1234.png",
+                "target_file_path": "api-assets/id/1234.png",
+            },
+            name="Face Swap image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="./outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        # Upload source image file if present
+        if "source_file_path" in assets and assets["source_file_path"]:
+            source_file_path = assets["source_file_path"]
+            assets["source_file_path"] = await file_client.upload_file(
+                file=source_file_path
+            )
+
+        # Upload target image file
+        target_file_path = assets["target_file_path"]
+        assets["target_file_path"] = await file_client.upload_file(
+            file=target_file_path
+        )
+
+        # Upload face mappings if present
+        if "face_mappings" in assets and assets["face_mappings"]:
+            for face_mapping in assets["face_mappings"]:
+                if "new_face" in face_mapping and face_mapping["new_face"]:
+                    new_face_file_path = face_mapping["new_face"]
+                    face_mapping["new_face"] = await file_client.upload_file(
+                        file=new_face_file_path
+                    )
+
+        create_response = await self.create(
+            assets=assets, name=name, request_options=request_options
+        )
+        logger.info(f"Face Swap Photo 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,
         *,