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

magic_hour/resources/v1/ai_face_editor/README.md

@@ -1,3 +1,96 @@
+# v1_ai_face_editor
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Face Editor 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.ai_face_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    style={
+        "enhance_face": False,
+        "eye_gaze_horizontal": 0.0,
+        "eye_gaze_vertical": 0.0,
+        "eye_open_ratio": 0.0,
+        "eyebrow_direction": 0.0,
+        "head_pitch": 0.0,
+        "head_roll": 0.0,
+        "head_yaw": 0.0,
+        "lip_open_ratio": 0.0,
+        "mouth_grim": 0.0,
+        "mouth_position_horizontal": 0.0,
+        "mouth_position_vertical": 0.0,
+        "mouth_pout": 0.0,
+        "mouth_purse": 0.0,
+        "mouth_smile": 0.0,
+    },
+    name="Face Editor image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_face_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    style={
+        "enhance_face": False,
+        "eye_gaze_horizontal": 0.0,
+        "eye_gaze_vertical": 0.0,
+        "eye_open_ratio": 0.0,
+        "eyebrow_direction": 0.0,
+        "head_pitch": 0.0,
+        "head_roll": 0.0,
+        "head_yaw": 0.0,
+        "lip_open_ratio": 0.0,
+        "mouth_grim": 0.0,
+        "mouth_position_horizontal": 0.0,
+        "mouth_position_vertical": 0.0,
+        "mouth_pout": 0.0,
+        "mouth_purse": 0.0,
+        "mouth_smile": 0.0,
+    },
+    name="Face Editor image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI Face Editor <a name="create"></a>
 
@@ -10,7 +103,23 @@ Edit facial features of an image using AI. Each edit costs 1 frame. The height/w
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `assets` | ✓ | Provide the assets for face editor | `{"image_file_path": "api-assets/id/1234.png"}` |
+| `└─ image_file_path` | ✓ | This is the image whose face will be edited. 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"` |
 | `style` | ✓ | Face editing parameters | `{"enhance_face": False, "eye_gaze_horizontal": 0.0, "eye_gaze_vertical": 0.0, "eye_open_ratio": 0.0, "eyebrow_direction": 0.0, "head_pitch": 0.0, "head_roll": 0.0, "head_yaw": 0.0, "lip_open_ratio": 0.0, "mouth_grim": 0.0, "mouth_position_horizontal": 0.0, "mouth_position_vertical": 0.0, "mouth_pout": 0.0, "mouth_purse": 0.0, "mouth_smile": 0.0}` |
+| `└─ enhance_face` | ✗ | Enhance face features | `False` |
+| `└─ eye_gaze_horizontal` | ✗ | Horizontal eye gaze (-100 to 100), in increments of 5 | `0.0` |
+| `└─ eye_gaze_vertical` | ✗ | Vertical eye gaze (-100 to 100), in increments of 5 | `0.0` |
+| `└─ eye_open_ratio` | ✗ | Eye open ratio (-100 to 100), in increments of 5 | `0.0` |
+| `└─ eyebrow_direction` | ✗ | Eyebrow direction (-100 to 100), in increments of 5 | `0.0` |
+| `└─ head_pitch` | ✗ | Head pitch (-100 to 100), in increments of 5 | `0.0` |
+| `└─ head_roll` | ✗ | Head roll (-100 to 100), in increments of 5 | `0.0` |
+| `└─ head_yaw` | ✗ | Head yaw (-100 to 100), in increments of 5 | `0.0` |
+| `└─ lip_open_ratio` | ✗ | Lip open ratio (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_grim` | ✗ | Mouth grim (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_position_horizontal` | ✗ | Horizontal mouth position (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_position_vertical` | ✗ | Vertical mouth position (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_pout` | ✗ | Mouth pout (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_purse` | ✗ | Mouth purse (-100 to 100), in increments of 5 | `0.0` |
+| `└─ mouth_smile` | ✗ | Mouth smile (-100 to 100), in increments of 5 | `0.0` |
 | `name` | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Face Editor image"` |
 
 #### Synchronous Client
@@ -82,3 +191,4 @@ res = await client.v1.ai_face_editor.create(
 
 ##### Example
 `{"credits_charged": 1, "frame_cost": 1, "id": "cuid-example"}`
+

magic_hour/resources/v1/ai_face_editor/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,101 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.resources.v1.files.client import AsyncFilesClient, FilesClient
+from magic_hour.resources.v1.image_projects.client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+)
 from magic_hour.types import models, params
 
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
 class AiFaceEditorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1AiFaceEditorGenerateBodyAssets,
+        style: params.V1AiFaceEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate face edited image (alias for create with additional functionality).
+
+        Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](/pricing) page for more details
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for face editor
+            style: Face editing parameters
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided, the outputs will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the AI Face Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_face_editor.generate(
+            assets={"image_file_path": "path/to/face.png"},
+            style={
+                "enhance_face": True,
+                "eye_gaze_horizontal": 0.2,
+                "eye_gaze_vertical": -0.1,
+                "eye_open_ratio": 0.8,
+                "eyebrow_direction": 0.3,
+                "head_pitch": 0.1,
+                "head_roll": 0.0,
+                "head_yaw": -0.2,
+                "lip_open_ratio": 0.0,
+                "mouth_grim": 0.0,
+                "mouth_position_horizontal": 0.0,
+                "mouth_position_vertical": 0.0,
+                "mouth_pout": 0.0,
+                "mouth_purse": 0.0,
+                "mouth_smile": 0.5,
+            },
+            name="Face Editor image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        image_file_path = assets["image_file_path"]
+        assets["image_file_path"] = file_client.upload_file(file=image_file_path)
+
+        create_response = self.create(
+            assets=assets, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI Face Editor response: {create_response}")
+
+        image_projects_client = ImageProjectsClient(base_client=self._base_client)
+        response = image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     def create(
         self,
         *,
@@ -88,6 +177,85 @@ class AsyncAiFaceEditorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1AiFaceEditorGenerateBodyAssets,
+        style: params.V1AiFaceEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate face edited image (alias for create with additional functionality).
+
+        Edit facial features of an image using AI. Each edit costs 1 frame. The height/width of the output image depends on your subscription. Please refer to our [pricing](/pricing) page for more details
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for face editor
+            style: Face editing parameters
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided, the outputs will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the AI Face Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_face_editor.generate(
+            assets={"image_file_path": "path/to/face.png"},
+            style={
+                "enhance_face": True,
+                "eye_gaze_horizontal": 0.2,
+                "eye_gaze_vertical": -0.1,
+                "eye_open_ratio": 0.8,
+                "eyebrow_direction": 0.3,
+                "head_pitch": 0.1,
+                "head_roll": 0.0,
+                "head_yaw": -0.2,
+                "lip_open_ratio": 0.0,
+                "mouth_grim": 0.0,
+                "mouth_position_horizontal": 0.0,
+                "mouth_position_vertical": 0.0,
+                "mouth_pout": 0.0,
+                "mouth_purse": 0.0,
+                "mouth_smile": 0.5,
+            },
+            name="Face Editor image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        image_file_path = assets["image_file_path"]
+        assets["image_file_path"] = await file_client.upload_file(file=image_file_path)
+
+        create_response = await self.create(
+            assets=assets, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI Face Editor response: {create_response}")
+
+        image_projects_client = AsyncImageProjectsClient(base_client=self._base_client)
+        response = await image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     async def create(
         self,
         *,

magic_hour/resources/v1/ai_gif_generator/README.md

@@ -1,3 +1,60 @@
+# v1_ai_gif_generator
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Gif Generator 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.ai_gif_generator.generate(
+    style={"prompt": "Cute dancing cat, pixel art"}, name="Ai Gif gif"
+    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.ai_gif_generator.generate(
+    style={"prompt": "Cute dancing cat, pixel art"}, name="Ai Gif gif"
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI GIFs <a name="create"></a>
 
@@ -10,6 +67,7 @@ Create an AI GIF. Each GIF costs 50 credits.
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `style` | ✓ |  | `{"prompt": "Cute dancing cat, pixel art"}` |
+| `└─ prompt` | ✓ | The prompt used for the GIF. | `"Cute dancing cat, pixel art"` |
 | `name` | ✗ | The name of gif. This value is mainly used for your own identification of the gif. | `"Ai Gif gif"` |
 
 #### Synchronous Client
@@ -45,3 +103,4 @@ res = await client.v1.ai_gif_generator.create(
 
 ##### Example
 `{"credits_charged": 50, "frame_cost": 50, "id": "cuid-example"}`
+

magic_hour/resources/v1/ai_gif_generator/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,76 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
+from magic_hour.resources.v1.image_projects.client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+)
 from magic_hour.types import models, params
 
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
 class AiGifGeneratorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        style: params.V1AiGifGeneratorCreateBodyStyle,
+        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 GIF (alias for create with additional functionality).
+
+        Create an AI GIF. Each GIF costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: The art style to use for GIF generation
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided, the outputs will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the AI GIF Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_gif_generator.generate(
+            style={"prompt": "Cute dancing cat, pixel art"},
+            name="Dancing Cat GIF",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI GIF Generator response: {create_response}")
+
+        image_projects_client = ImageProjectsClient(base_client=self._base_client)
+        response = image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     def create(
         self,
         *,
@@ -68,6 +132,61 @@ class AsyncAiGifGeneratorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        style: params.V1AiGifGeneratorCreateBodyStyle,
+        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 GIF (alias for create with additional functionality).
+
+        Create an AI GIF. Each GIF costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: The art style to use for GIF generation
+            wait_for_completion: Whether to wait for the image project to complete
+            download_outputs: Whether to download the outputs
+            download_directory: The directory to download the outputs to. If not provided, the outputs will be downloaded to the current working directory
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            V1ImageProjectsGetResponseWithDownloads: The response from the AI GIF Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_gif_generator.generate(
+            style={"prompt": "Cute dancing cat, pixel art"},
+            name="Dancing Cat GIF",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI GIF Generator response: {create_response}")
+
+        image_projects_client = AsyncImageProjectsClient(base_client=self._base_client)
+        response = await image_projects_client.check_result(
+            id=create_response.id,
+            wait_for_completion=wait_for_completion,
+            download_outputs=download_outputs,
+            download_directory=download_directory,
+        )
+
+        return response
+
     async def create(
         self,
         *,

magic_hour/resources/v1/ai_headshot_generator/README.md

@@ -1,3 +1,60 @@
+# v1_ai_headshot_generator
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Headshot Generator 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.ai_headshot_generator.generate(
+    assets={"image_file_path": "/path/to/1234.png"}, name="Ai Headshot image"
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_headshot_generator.generate(
+    assets={"image_file_path": "/path/to/1234.png"}, name="Ai Headshot image"
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI Headshots <a name="create"></a>
 
@@ -10,8 +67,10 @@ Create an AI headshot. Each headshot costs 50 credits.
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `assets` | ✓ | Provide the assets for headshot photo | `{"image_file_path": "api-assets/id/1234.png"}` |
+| `└─ image_file_path` | ✓ | The image used to generate the headshot. This image must contain one detectable face. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).  Please refer to the [Input File documentation](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) to learn more.  | `"api-assets/id/1234.png"` |
 | `name` | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Ai Headshot image"` |
 | `style` | ✗ |  | `{}` |
+| `└─ prompt` | ✗ | Prompt used to guide the style of your headshot. We recommend omitting the prompt unless you want to customize your headshot. You can visit [AI headshot generator](https://magichour.ai/create/ai-headshot-generator) to view an example of a good prompt used for our 'Professional' style. | `"string"` |
 
 #### Synchronous Client
 
@@ -46,3 +105,4 @@ res = await client.v1.ai_headshot_generator.create(
 
 ##### Example
 `{"credits_charged": 50, "frame_cost": 50, "id": "cuid-example"}`
+