magic_hour 0.9.5__py3-none-any.whl → 0.44.0__py3-none-any.whl

magic_hour/resources/v1/face_detection/client.py

@@ -0,0 +1,380 @@
+import asyncio
+import os
+import pydantic
+import time
+import typing
+
+from magic_hour.helpers.download import download_files_async, download_files_sync
+from magic_hour.helpers.logger import get_sdk_logger
+from magic_hour.resources.v1.files import AsyncFilesClient, FilesClient
+from magic_hour.types import models, params
+from make_api_request import (
+    AsyncBaseClient,
+    RequestOptions,
+    SyncBaseClient,
+    default_request_options,
+    to_encodable,
+    type_utils,
+)
+
+
+logger = get_sdk_logger(__name__)
+
+
+class V1FaceDetectionGetResponseWithDownloads(models.V1FaceDetectionGetResponse):
+    downloaded_paths: typing.Optional[typing.List[str]] = pydantic.Field(
+        default=None, alias="downloaded_paths"
+    )
+    """
+    The paths to the downloaded face images.
+
+    This field is only populated if `download_outputs` is True and the face detection is complete.
+    """
+
+
+class FaceDetectionClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def generate(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], 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,
+    ) -> V1FaceDetectionGetResponseWithDownloads:
+        """
+        Generate face detection results with optional waiting and downloading.
+
+        This method creates a face detection task and optionally waits for completion
+        and downloads the detected face images.
+
+        Args:
+            assets: Provide the assets for face detection
+            confidence_score: Confidence threshold for filtering detected faces
+            wait_for_completion: Whether to wait for the face detection task to complete
+            download_outputs: Whether to download the detected face images
+            download_directory: The directory to download the face images to. If not provided,
+                the images will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1FaceDetectionGetResponseWithDownloads: The face detection response with optional
+                downloaded face image paths included
+        """
+        # Handle file upload if needed
+        file_client = FilesClient(base_client=self._base_client)
+        target_file_path = assets["target_file_path"]
+        assets["target_file_path"] = file_client.upload_file(file=target_file_path)
+
+        create_response = self.create(
+            assets=assets,
+            confidence_score=confidence_score,
+            request_options=request_options,
+        )
+
+        task_id = create_response.id
+
+        api_response = self.get(id=task_id)
+        if not wait_for_completion:
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        while api_response.status not in ["complete", "error"]:
+            api_response = self.get(id=task_id)
+            time.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(f"Face detection {task_id} has status {api_response.status}")
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs or not api_response.faces:
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        face_downloads = [
+            models.V1ImageProjectsGetResponseDownloadsItem(
+                url=face.url,
+                expires_at="ignore",
+            )
+            for face in api_response.faces
+        ]
+        downloaded_paths = download_files_sync(
+            downloads=face_downloads,
+            download_directory=download_directory,
+        )
+
+        return V1FaceDetectionGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
+    def get(
+        self, *, id: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> models.V1FaceDetectionGetResponse:
+        """
+        Get face detection details
+
+        Get the details of a face detection task.
+
+        Use this API to get the list of faces detected in the image or video to use in the [face swap photo](/api-reference/face-swap-photo/face-swap-photo) or [face swap video](/api-reference/face-swap/face-swap-video) API calls for multi-face swaps.
+
+        GET /v1/face-detection/{id}
+
+        Args:
+            id: The id of the task. This value is returned by the [face detection API](/api-reference/files/face-detection#response-id).
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        client.v1.face_detection.get(id="uuid-example")
+        ```
+        """
+        return self._base_client.request(
+            method="GET",
+            path=f"/v1/face-detection/{id}",
+            auth_names=["bearerAuth"],
+            cast_to=models.V1FaceDetectionGetResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+    def create(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1FaceDetectionCreateResponse:
+        """
+        Face Detection
+
+        Detect faces in an image or video.
+
+        Use this API to get the list of faces detected in the image or video to use in the [face swap photo](/api-reference/face-swap-photo/face-swap-photo) or [face swap video](/api-reference/face-swap/face-swap-video) API calls for multi-face swaps.
+
+        Note: Face detection is free to use for the near future. Pricing may change in the future.
+
+        POST /v1/face-detection
+
+        Args:
+            confidence_score: Confidence threshold for filtering detected faces.
+        * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.
+        * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
+            assets: Provide the assets for face detection
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        client.v1.face_detection.create(
+            assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"confidence_score": confidence_score, "assets": assets},
+            dump_with=params._SerializerV1FaceDetectionCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/face-detection",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1FaceDetectionCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncFaceDetectionClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def generate(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], 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,
+    ) -> V1FaceDetectionGetResponseWithDownloads:
+        """
+        Generate face detection results with optional waiting and downloading.
+
+        This method creates a face detection task and optionally waits for completion
+        and downloads the detected face images.
+
+        Args:
+            assets: Provide the assets for face detection
+            confidence_score: Confidence threshold for filtering detected faces
+            wait_for_completion: Whether to wait for the face detection task to complete
+            download_outputs: Whether to download the detected face images
+            download_directory: The directory to download the face images to. If not provided,
+                the images will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1FaceDetectionGetResponseWithDownloads: The face detection response with optional
+                downloaded face image paths included
+        """
+        # Handle file upload if needed
+        file_client = AsyncFilesClient(base_client=self._base_client)
+        target_file_path = assets["target_file_path"]
+        assets["target_file_path"] = await file_client.upload_file(
+            file=target_file_path
+        )
+
+        create_response = await self.create(
+            assets=assets,
+            confidence_score=confidence_score,
+            request_options=request_options,
+        )
+
+        task_id = create_response.id
+
+        api_response = await self.get(id=task_id)
+        if not wait_for_completion:
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        while api_response.status not in ["complete", "error"]:
+            api_response = await self.get(id=task_id)
+            await asyncio.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(f"Face detection {task_id} has status {api_response.status}")
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs or not api_response.faces:
+            return V1FaceDetectionGetResponseWithDownloads(**api_response.model_dump())
+
+        face_downloads = [
+            models.V1ImageProjectsGetResponseDownloadsItem(
+                url=face.url,
+                expires_at="ignore",
+            )
+            for face in api_response.faces
+        ]
+        downloaded_paths = await download_files_async(
+            downloads=face_downloads,
+            download_directory=download_directory,
+        )
+
+        return V1FaceDetectionGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
+    async def get(
+        self, *, id: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> models.V1FaceDetectionGetResponse:
+        """
+        Get face detection details
+
+        Get the details of a face detection task.
+
+        Use this API to get the list of faces detected in the image or video to use in the [face swap photo](/api-reference/face-swap-photo/face-swap-photo) or [face swap video](/api-reference/face-swap/face-swap-video) API calls for multi-face swaps.
+
+        GET /v1/face-detection/{id}
+
+        Args:
+            id: The id of the task. This value is returned by the [face detection API](/api-reference/files/face-detection#response-id).
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        await client.v1.face_detection.get(id="uuid-example")
+        ```
+        """
+        return await self._base_client.request(
+            method="GET",
+            path=f"/v1/face-detection/{id}",
+            auth_names=["bearerAuth"],
+            cast_to=models.V1FaceDetectionGetResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+    async def create(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1FaceDetectionCreateResponse:
+        """
+        Face Detection
+
+        Detect faces in an image or video.
+
+        Use this API to get the list of faces detected in the image or video to use in the [face swap photo](/api-reference/face-swap-photo/face-swap-photo) or [face swap video](/api-reference/face-swap/face-swap-video) API calls for multi-face swaps.
+
+        Note: Face detection is free to use for the near future. Pricing may change in the future.
+
+        POST /v1/face-detection
+
+        Args:
+            confidence_score: Confidence threshold for filtering detected faces.
+        * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.
+        * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
+            assets: Provide the assets for face detection
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        await client.v1.face_detection.create(
+            assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"confidence_score": confidence_score, "assets": assets},
+            dump_with=params._SerializerV1FaceDetectionCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/face-detection",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1FaceDetectionCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

magic_hour/resources/v1/face_swap/README.md

@@ -1,14 +1,118 @@
+# v1.face_swap
 
-### create <a name="create"></a>
-Face Swap video
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Face Swap 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.generate(
+    assets={
+        "face_mappings": [
+            {
+                "new_face": "/path/to/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
+        "image_file_path": "image/id/1234.png",
+        "video_file_path": "/path/to/1234.mp4",
+        "video_source": "file",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Face Swap video",
+    style={"version": "default"},
+    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.generate(
+    assets={
+        "face_mappings": [
+            {
+                "new_face": "/path/to/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
+        "image_file_path": "image/id/1234.png",
+        "video_file_path": "/path/to/1234.mp4",
+        "video_source": "file",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Face Swap video",
+    style={"version": "default"},
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### Face Swap Video <a name="create"></a>
 
 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.
-  
-Get more information about this mode at our [product page](/products/face-swap).
-  
+
+Get more information about this mode at our [product page](https://magichour.ai/products/face-swap).
 
 **API Endpoint**: `POST /v1/face-swap`
 
+#### Parameters
+
+| Parameter            | Required | Deprecated | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Example                                                                                                                                                                                                                                             |
+| -------------------- | :------: | :--------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assets`             |    ✓     |     ✗      | Provide the assets for face swap. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used                                                                                                                                                                                                                                                                                                                             | `{"face_mappings": [{"new_face": "api-assets/id/1234.png", "original_face": "api-assets/id/0-0.png"}], "face_swap_mode": "all-faces", "image_file_path": "image/id/1234.png", "video_file_path": "api-assets/id/1234.mp4", "video_source": "file"}` |
+| `└─ 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"`                                                                                                                                                                                                                                       |
+| `└─ image_file_path` |    ✗     |     —      | The path of the input image with the face to be swapped. 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. | `"image/id/1234.png"`                                                                                                                                                                                                                               |
+| `└─ video_file_path` |    ✗     |     —      | Required if `video_source` is `file`. 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.mp4"`                                                                                                                                                                                                                          |
+| `└─ video_source`    |    ✓     |     —      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"file"`                                                                                                                                                                                                                                            |
+| `└─ youtube_url`     |    ✗     |     —      | Using a youtube video as the input source. This field is required if `video_source` is `youtube`                                                                                                                                                                                                                                                                                                                                                                      | `"http://www.example.com"`                                                                                                                                                                                                                          |
+| `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.                                                                                                                                                                                                                                                                                                          | `15.0`                                                                                                                                                                                                                                              |
+| `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.                                                                                                                                                                                                                                                                                                                                           | `0.0`                                                                                                                                                                                                                                               |
+| `height`             |    ✗     |     ✓      | `height` is deprecated and no longer influences the output video's resolution. 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. This field is retained only for backward compatibility and will be removed in a future release.                                                          | `123`                                                                                                                                                                                                                                               |
+| `name`               |    ✗     |     ✗      | The name of video. This value is mainly used for your own identification of the video.                                                                                                                                                                                                                                                                                                                                                                                | `"Face Swap video"`                                                                                                                                                                                                                                 |
+| `style`              |    ✗     |     ✗      | Style of the face swap video.                                                                                                                                                                                                                                                                                                                                                                                                                                         | `{"version": "default"}`                                                                                                                                                                                                                            |
+| `└─ version`         |    ✗     |     —      | * `v1` - May preserve skin detail and texture better, but weaker identity preservation. * `v2` - Faster, sharper, better handling of hair and glasses. stronger identity preservation. * `default` - Use the version we recommend, which will change over time. This is recommended unless you need a specific earlier version. This is the default behavior.                                                                                                         | `"default"`                                                                                                                                                                                                                                         |
+| `width`              |    ✗     |     ✓      | `width` is deprecated and no longer influences the output video's resolution. 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. This field is retained only for backward compatibility and will be removed in a future release.                                                           | `123`                                                                                                                                                                                                                                               |
+
 #### Synchronous Client
 
 ```python
@@ -18,15 +122,21 @@ from os import getenv
 client = Client(token=getenv("API_TOKEN"))
 res = client.v1.face_swap.create(
     assets={
+        "face_mappings": [
+            {
+                "new_face": "api-assets/id/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
         "image_file_path": "image/id/1234.png",
         "video_file_path": "api-assets/id/1234.mp4",
         "video_source": "file",
     },
     end_seconds=15.0,
-    height=960,
     start_seconds=0.0,
-    width=512,
     name="Face Swap video",
+    style={"version": "default"},
 )
 ```
 
@@ -39,14 +149,32 @@ from os import getenv
 client = AsyncClient(token=getenv("API_TOKEN"))
 res = await client.v1.face_swap.create(
     assets={
+        "face_mappings": [
+            {
+                "new_face": "api-assets/id/1234.png",
+                "original_face": "api-assets/id/0-0.png",
+            }
+        ],
+        "face_swap_mode": "all-faces",
         "image_file_path": "image/id/1234.png",
         "video_file_path": "api-assets/id/1234.mp4",
         "video_source": "file",
     },
     end_seconds=15.0,
-    height=960,
     start_seconds=0.0,
-    width=512,
     name="Face Swap video",
+    style={"version": "default"},
 )
 ```
+
+#### Response
+
+##### Type
+
+[V1FaceSwapCreateResponse](/magic_hour/types/models/v1_face_swap_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 450, "estimated_frame_cost": 450, "id": "cuid-example"}
+```