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

magic_hour/resources/v1/auto_subtitle_generator/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,106 @@ 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 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,
         *,
@@ -94,6 +188,90 @@ 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,
         *,

magic_hour/resources/v1/face_detection/README.md

@@ -1,3 +1,60 @@
+# 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>
 
@@ -58,6 +115,7 @@ Note: Face detection is free to use for the near future. Pricing may change in t
 | 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
@@ -93,3 +151,4 @@ res = await client.v1.face_detection.create(
 
 ##### Example
 `{"credits_charged": 123, "id": "uuid-example"}`
+

magic_hour/resources/v1/face_detection/__init__.py

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

magic_hour/resources/v1/face_detection/client.py

@@ -1,3 +1,8 @@
+import asyncio
+import logging
+import os
+import pydantic
+import time
 import typing
 
 from magic_hour.core import (
@@ -8,13 +13,107 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.helpers.download import download_files_async, download_files_sync
+from magic_hour.resources.v1.files import AsyncFilesClient, FilesClient
 from magic_hour.types import models, params
 
 
+logger = logging.getLogger(__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:
@@ -110,6 +209,86 @@ 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:

magic_hour/resources/v1/face_swap/README.md

@@ -1,3 +1,90 @@
+# v1_face_swap
+
+## 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>
 
@@ -10,14 +97,22 @@ Get more information about this mode at our [product page](https://magichour.ai/
 
 #### Parameters
 
-| Parameter | Required | 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"}` |
-| `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"` |
-| `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` |
+| 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. (Recommended) * `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
 
@@ -42,6 +137,7 @@ res = client.v1.face_swap.create(
     end_seconds=15.0,
     start_seconds=0.0,
     name="Face Swap video",
+    style={"version": "default"},
 )
 
 ```
@@ -69,6 +165,7 @@ res = await client.v1.face_swap.create(
     end_seconds=15.0,
     start_seconds=0.0,
     name="Face Swap video",
+    style={"version": "default"},
 )
 
 ```