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

magic_hour/resources/v1/auto_subtitle_generator/client.py

@@ -0,0 +1,346 @@
+import typing
+
+from magic_hour.helpers.logger import get_sdk_logger
+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
+from make_api_request import (
+    AsyncBaseClient,
+    RequestOptions,
+    SyncBaseClient,
+    default_request_options,
+    to_encodable,
+    type_utils,
+)
+
+
+logger = get_sdk_logger(__name__)
+
+
+class AutoSubtitleGeneratorClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def generate(
+        self,
+        *,
+        assets: params.V1AutoSubtitleGeneratorCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        style: params.V1AutoSubtitleGeneratorCreateBodyStyle,
+        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 subtitled video (alias for create with additional functionality).
+
+        Automatically generate subtitles for your video in multiple languages.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            assets: Provide the assets for auto subtitle generator
+            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.
+            style: Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided.
+        * If only `.style.template` is provided, default values for the template will be used.
+        * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.
+        * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.
+
+        To use custom config only, the following `custom_config` params are required:
+        * `.style.custom_config.font`
+        * `.style.custom_config.text_color`
+        * `.style.custom_config.vertical_position`
+        * `.style.custom_config.horizontal_position`
+
+            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 Auto Subtitle Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.auto_subtitle_generator.generate(
+            assets={"video_file_path": "path/to/video.mp4"},
+            end_seconds=15.0,
+            start_seconds=0.0,
+            style={},
+            name="Subtitled Video",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        video_file_path = assets["video_file_path"]
+        assets["video_file_path"] = file_client.upload_file(file=video_file_path)
+
+        create_response = self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"Auto Subtitle Generator 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,
+        *,
+        assets: params.V1AutoSubtitleGeneratorCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        style: params.V1AutoSubtitleGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AutoSubtitleGeneratorCreateResponse:
+        """
+        Auto Subtitle Generator
+
+        Automatically generate subtitles for your video in multiple languages.
+
+        POST /v1/auto-subtitle-generator
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            assets: Provide the assets for auto subtitle generator
+            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.
+            style: Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided.
+        * If only `.style.template` is provided, default values for the template will be used.
+        * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.
+        * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.
+
+        To use custom config only, the following `custom_config` params are required:
+        * `.style.custom_config.font`
+        * `.style.custom_config.text_color`
+        * `.style.custom_config.vertical_position`
+        * `.style.custom_config.horizontal_position`
+
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            Success
+
+        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.auto_subtitle_generator.create(
+            assets={"video_file_path": "api-assets/id/1234.mp4"},
+            end_seconds=15.0,
+            start_seconds=0.0,
+            style={},
+            name="Auto Subtitle video",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={
+                "name": name,
+                "assets": assets,
+                "end_seconds": end_seconds,
+                "start_seconds": start_seconds,
+                "style": style,
+            },
+            dump_with=params._SerializerV1AutoSubtitleGeneratorCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/auto-subtitle-generator",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AutoSubtitleGeneratorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncAutoSubtitleGeneratorClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def generate(
+        self,
+        *,
+        assets: params.V1AutoSubtitleGeneratorCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        style: params.V1AutoSubtitleGeneratorCreateBodyStyle,
+        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 subtitled video (alias for create with additional functionality).
+
+        Automatically generate subtitles for your video in multiple languages.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            assets: Provide the assets for auto subtitle generator
+            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.
+            style: Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided.
+        * If only `.style.template` is provided, default values for the template will be used.
+        * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.
+        * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.
+
+        To use custom config only, the following `custom_config` params are required:
+        * `.style.custom_config.font`
+        * `.style.custom_config.text_color`
+        * `.style.custom_config.vertical_position`
+        * `.style.custom_config.horizontal_position`
+
+            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 Auto Subtitle Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.auto_subtitle_generator.generate(
+            assets={"video_file_path": "path/to/video.mp4"},
+            end_seconds=15.0,
+            start_seconds=0.0,
+            style={},
+            name="Subtitled Video",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        video_file_path = assets["video_file_path"]
+        assets["video_file_path"] = await file_client.upload_file(file=video_file_path)
+
+        create_response = await self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"Auto Subtitle Generator 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,
+        *,
+        assets: params.V1AutoSubtitleGeneratorCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        style: params.V1AutoSubtitleGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AutoSubtitleGeneratorCreateResponse:
+        """
+        Auto Subtitle Generator
+
+        Automatically generate subtitles for your video in multiple languages.
+
+        POST /v1/auto-subtitle-generator
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            assets: Provide the assets for auto subtitle generator
+            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.
+            style: Style of the subtitle. At least one of `.style.template` or `.style.custom_config` must be provided.
+        * If only `.style.template` is provided, default values for the template will be used.
+        * If both are provided, the fields in `.style.custom_config` will be used to overwrite the fields in `.style.template`.
+        * If only `.style.custom_config` is provided, then all fields in `.style.custom_config` will be used.
+
+        To use custom config only, the following `custom_config` params are required:
+        * `.style.custom_config.font`
+        * `.style.custom_config.text_color`
+        * `.style.custom_config.vertical_position`
+        * `.style.custom_config.horizontal_position`
+
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            Success
+
+        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.auto_subtitle_generator.create(
+            assets={"video_file_path": "api-assets/id/1234.mp4"},
+            end_seconds=15.0,
+            start_seconds=0.0,
+            style={},
+            name="Auto Subtitle video",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={
+                "name": name,
+                "assets": assets,
+                "end_seconds": end_seconds,
+                "start_seconds": start_seconds,
+                "style": style,
+            },
+            dump_with=params._SerializerV1AutoSubtitleGeneratorCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/auto-subtitle-generator",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AutoSubtitleGeneratorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

magic_hour/resources/v1/client.py

@@ -1,12 +1,23 @@
-from magic_hour.core import AsyncBaseClient, SyncBaseClient
 from magic_hour.resources.v1.ai_clothes_changer import (
     AiClothesChangerClient,
     AsyncAiClothesChangerClient,
 )
+from magic_hour.resources.v1.ai_face_editor import (
+    AiFaceEditorClient,
+    AsyncAiFaceEditorClient,
+)
+from magic_hour.resources.v1.ai_gif_generator import (
+    AiGifGeneratorClient,
+    AsyncAiGifGeneratorClient,
+)
 from magic_hour.resources.v1.ai_headshot_generator import (
     AiHeadshotGeneratorClient,
     AsyncAiHeadshotGeneratorClient,
 )
+from magic_hour.resources.v1.ai_image_editor import (
+    AiImageEditorClient,
+    AsyncAiImageEditorClient,
+)
 from magic_hour.resources.v1.ai_image_generator import (
     AiImageGeneratorClient,
     AsyncAiImageGeneratorClient,
@@ -15,6 +26,10 @@ from magic_hour.resources.v1.ai_image_upscaler import (
     AiImageUpscalerClient,
     AsyncAiImageUpscalerClient,
 )
+from magic_hour.resources.v1.ai_meme_generator import (
+    AiMemeGeneratorClient,
+    AsyncAiMemeGeneratorClient,
+)
 from magic_hour.resources.v1.ai_photo_editor import (
     AiPhotoEditorClient,
     AsyncAiPhotoEditorClient,
@@ -23,7 +38,31 @@ from magic_hour.resources.v1.ai_qr_code_generator import (
     AiQrCodeGeneratorClient,
     AsyncAiQrCodeGeneratorClient,
 )
+from magic_hour.resources.v1.ai_talking_photo import (
+    AiTalkingPhotoClient,
+    AsyncAiTalkingPhotoClient,
+)
+from magic_hour.resources.v1.ai_voice_cloner import (
+    AiVoiceClonerClient,
+    AsyncAiVoiceClonerClient,
+)
+from magic_hour.resources.v1.ai_voice_generator import (
+    AiVoiceGeneratorClient,
+    AsyncAiVoiceGeneratorClient,
+)
 from magic_hour.resources.v1.animation import AnimationClient, AsyncAnimationClient
+from magic_hour.resources.v1.audio_projects import (
+    AsyncAudioProjectsClient,
+    AudioProjectsClient,
+)
+from magic_hour.resources.v1.auto_subtitle_generator import (
+    AsyncAutoSubtitleGeneratorClient,
+    AutoSubtitleGeneratorClient,
+)
+from magic_hour.resources.v1.face_detection import (
+    AsyncFaceDetectionClient,
+    FaceDetectionClient,
+)
 from magic_hour.resources.v1.face_swap import AsyncFaceSwapClient, FaceSwapClient
 from magic_hour.resources.v1.face_swap_photo import (
     AsyncFaceSwapPhotoClient,
@@ -43,6 +82,10 @@ from magic_hour.resources.v1.image_to_video import (
     ImageToVideoClient,
 )
 from magic_hour.resources.v1.lip_sync import AsyncLipSyncClient, LipSyncClient
+from magic_hour.resources.v1.photo_colorizer import (
+    AsyncPhotoColorizerClient,
+    PhotoColorizerClient,
+)
 from magic_hour.resources.v1.text_to_video import (
     AsyncTextToVideoClient,
     TextToVideoClient,
@@ -55,6 +98,7 @@ from magic_hour.resources.v1.video_to_video import (
     AsyncVideoToVideoClient,
     VideoToVideoClient,
 )
+from make_api_request import AsyncBaseClient, SyncBaseClient
 
 
 class V1Client:
@@ -62,17 +106,26 @@ class V1Client:
         self._base_client = base_client
         self.image_projects = ImageProjectsClient(base_client=self._base_client)
         self.video_projects = VideoProjectsClient(base_client=self._base_client)
+        self.face_detection = FaceDetectionClient(base_client=self._base_client)
         self.ai_clothes_changer = AiClothesChangerClient(base_client=self._base_client)
+        self.ai_face_editor = AiFaceEditorClient(base_client=self._base_client)
+        self.ai_gif_generator = AiGifGeneratorClient(base_client=self._base_client)
         self.ai_headshot_generator = AiHeadshotGeneratorClient(
             base_client=self._base_client
         )
+        self.ai_image_editor = AiImageEditorClient(base_client=self._base_client)
         self.ai_image_generator = AiImageGeneratorClient(base_client=self._base_client)
         self.ai_image_upscaler = AiImageUpscalerClient(base_client=self._base_client)
+        self.ai_meme_generator = AiMemeGeneratorClient(base_client=self._base_client)
         self.ai_photo_editor = AiPhotoEditorClient(base_client=self._base_client)
         self.ai_qr_code_generator = AiQrCodeGeneratorClient(
             base_client=self._base_client
         )
+        self.ai_talking_photo = AiTalkingPhotoClient(base_client=self._base_client)
         self.animation = AnimationClient(base_client=self._base_client)
+        self.auto_subtitle_generator = AutoSubtitleGeneratorClient(
+            base_client=self._base_client
+        )
         self.face_swap = FaceSwapClient(base_client=self._base_client)
         self.face_swap_photo = FaceSwapPhotoClient(base_client=self._base_client)
         self.files = FilesClient(base_client=self._base_client)
@@ -81,8 +134,12 @@ class V1Client:
         )
         self.image_to_video = ImageToVideoClient(base_client=self._base_client)
         self.lip_sync = LipSyncClient(base_client=self._base_client)
+        self.photo_colorizer = PhotoColorizerClient(base_client=self._base_client)
         self.text_to_video = TextToVideoClient(base_client=self._base_client)
         self.video_to_video = VideoToVideoClient(base_client=self._base_client)
+        self.audio_projects = AudioProjectsClient(base_client=self._base_client)
+        self.ai_voice_generator = AiVoiceGeneratorClient(base_client=self._base_client)
+        self.ai_voice_cloner = AiVoiceClonerClient(base_client=self._base_client)
 
 
 class AsyncV1Client:
@@ -90,23 +147,34 @@ class AsyncV1Client:
         self._base_client = base_client
         self.image_projects = AsyncImageProjectsClient(base_client=self._base_client)
         self.video_projects = AsyncVideoProjectsClient(base_client=self._base_client)
+        self.face_detection = AsyncFaceDetectionClient(base_client=self._base_client)
         self.ai_clothes_changer = AsyncAiClothesChangerClient(
             base_client=self._base_client
         )
+        self.ai_face_editor = AsyncAiFaceEditorClient(base_client=self._base_client)
+        self.ai_gif_generator = AsyncAiGifGeneratorClient(base_client=self._base_client)
         self.ai_headshot_generator = AsyncAiHeadshotGeneratorClient(
             base_client=self._base_client
         )
+        self.ai_image_editor = AsyncAiImageEditorClient(base_client=self._base_client)
         self.ai_image_generator = AsyncAiImageGeneratorClient(
             base_client=self._base_client
         )
         self.ai_image_upscaler = AsyncAiImageUpscalerClient(
             base_client=self._base_client
         )
+        self.ai_meme_generator = AsyncAiMemeGeneratorClient(
+            base_client=self._base_client
+        )
         self.ai_photo_editor = AsyncAiPhotoEditorClient(base_client=self._base_client)
         self.ai_qr_code_generator = AsyncAiQrCodeGeneratorClient(
             base_client=self._base_client
         )
+        self.ai_talking_photo = AsyncAiTalkingPhotoClient(base_client=self._base_client)
         self.animation = AsyncAnimationClient(base_client=self._base_client)
+        self.auto_subtitle_generator = AsyncAutoSubtitleGeneratorClient(
+            base_client=self._base_client
+        )
         self.face_swap = AsyncFaceSwapClient(base_client=self._base_client)
         self.face_swap_photo = AsyncFaceSwapPhotoClient(base_client=self._base_client)
         self.files = AsyncFilesClient(base_client=self._base_client)
@@ -115,5 +183,11 @@ class AsyncV1Client:
         )
         self.image_to_video = AsyncImageToVideoClient(base_client=self._base_client)
         self.lip_sync = AsyncLipSyncClient(base_client=self._base_client)
+        self.photo_colorizer = AsyncPhotoColorizerClient(base_client=self._base_client)
         self.text_to_video = AsyncTextToVideoClient(base_client=self._base_client)
         self.video_to_video = AsyncVideoToVideoClient(base_client=self._base_client)
+        self.audio_projects = AsyncAudioProjectsClient(base_client=self._base_client)
+        self.ai_voice_generator = AsyncAiVoiceGeneratorClient(
+            base_client=self._base_client
+        )
+        self.ai_voice_cloner = AsyncAiVoiceClonerClient(base_client=self._base_client)

magic_hour/resources/v1/face_detection/README.md

@@ -0,0 +1,157 @@
+# v1.face_detection
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Face Detection 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_detection.generate(
+    assets={"target_file_path": "/path/to/1234.png"}, confidence_score=0.5
+    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_detection.generate(
+    assets={"target_file_path": "/path/to/1234.png"}, confidence_score=0.5
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### Get face detection details <a name="get"></a>
+
+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.
+
+**API Endpoint**: `GET /v1/face-detection/{id}`
+
+#### Parameters
+
+| Parameter | Required | Description                                                                                                              | Example          |
+| --------- | :------: | ------------------------------------------------------------------------------------------------------------------------ | ---------------- |
+| `id`      |    ✓     | The id of the task. This value is returned by the [face detection API](/api-reference/files/face-detection#response-id). | `"uuid-example"` |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.face_detection.get(id="uuid-example")
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.face_detection.get(id="uuid-example")
+```
+
+#### Response
+
+##### Type
+
+[V1FaceDetectionGetResponse](/magic_hour/types/models/v1_face_detection_get_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 0, "faces": [{"path": "api-assets/id/0-0.png", "url": "https://videos.magichour.ai/api-assets/id/0-0.png"}], "id": "uuid-example", "status": "complete"}
+```
+
+### Face Detection <a name="create"></a>
+
+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.
+
+**API Endpoint**: `POST /v1/face-detection`
+
+#### Parameters
+
+| Parameter             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                    | Example                                          |
+| --------------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `assets`              |    ✓     | Provide the assets for face detection                                                                                                                                                                                                                                                                                                                                                                          | `{"target_file_path": "api-assets/id/1234.png"}` |
+| `└─ target_file_path` |    ✓     | This is the image or video where the face will be detected. 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"`                       |
+| `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.                                                                                                                                                  | `0.5`                                            |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.face_detection.create(
+    assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.face_detection.create(
+    assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+)
+```
+
+#### Response
+
+##### Type
+
+[V1FaceDetectionCreateResponse](/magic_hour/types/models/v1_face_detection_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 123, "id": "uuid-example"}
+```

magic_hour/resources/v1/face_detection/__init__.py

@@ -0,0 +1,12 @@
+from .client import (
+    AsyncFaceDetectionClient,
+    FaceDetectionClient,
+    V1FaceDetectionGetResponseWithDownloads,
+)
+
+
+__all__ = [
+    "AsyncFaceDetectionClient",
+    "FaceDetectionClient",
+    "V1FaceDetectionGetResponseWithDownloads",
+]