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

magic_hour/resources/v1/ai_image_upscaler/README.md

@@ -1,3 +1,66 @@
+# v1_ai_image_upscaler
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Image Upscaler 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_image_upscaler.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    scale_factor=2.0,
+    style={"enhancement": "Balanced"},
+    name="Image Upscaler 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_image_upscaler.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    scale_factor=2.0,
+    style={"enhancement": "Balanced"},
+    name="Image Upscaler image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI Image Upscaler <a name="create"></a>
 
@@ -10,8 +73,11 @@ Upscale your image using AI. Each 2x upscale costs 50 credits, and 4x upscale co
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `assets` | ✓ | Provide the assets for upscaling | `{"image_file_path": "api-assets/id/1234.png"}` |
+| `└─ image_file_path` | ✓ | The image to upscale. 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"` |
 | `scale_factor` | ✓ | How much to scale the image. Must be either 2 or 4.              Note: 4x upscale is only available on Creator, Pro, or Business tier. | `2.0` |
 | `style` | ✓ |  | `{"enhancement": "Balanced"}` |
+| `└─ enhancement` | ✓ |  | `"Balanced"` |
+| `└─ prompt` | ✗ | A prompt to guide the final image. This value is ignored if `enhancement` is not Creative | `"string"` |
 | `name` | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Image Upscaler image"` |
 
 #### Synchronous Client
@@ -53,3 +119,4 @@ res = await client.v1.ai_image_upscaler.create(
 
 ##### Example
 `{"credits_charged": 50, "frame_cost": 50, "id": "cuid-example"}`
+

magic_hour/resources/v1/ai_image_upscaler/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,92 @@ 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 AiImageUpscalerClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1AiImageUpscalerGenerateBodyAssets,
+        scale_factor: float,
+        style: params.V1AiImageUpscalerCreateBodyStyle,
+        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 upscaled image (alias for create with additional functionality).
+
+        Upscale image using AI. Each upscale costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for image upscaler
+            scale_factor: How much to scale the image. Must be either 2 or 4.
+            style: Image upscaling 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 Image Upscaler API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_image_upscaler.generate(
+            assets={"image_file_path": "path/to/image.png"},
+            scale_factor=2.0,
+            style={"enhancement": "Balanced"},
+            name="Upscaled 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,
+            scale_factor=scale_factor,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Image Upscaler 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,
         *,
@@ -82,6 +162,76 @@ class AsyncAiImageUpscalerClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1AiImageUpscalerGenerateBodyAssets,
+        scale_factor: float,
+        style: params.V1AiImageUpscalerCreateBodyStyle,
+        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 upscaled image (alias for create with additional functionality).
+
+        Upscale image using AI. Each upscale costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for image upscaler
+            scale_factor: How much to scale the image. Must be either 2 or 4.
+            style: Image upscaling 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 Image Upscaler API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_image_upscaler.generate(
+            assets={"image_file_path": "path/to/image.png"},
+            scale_factor=2.0,
+            style={"enhancement": "Balanced"},
+            name="Upscaled 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,
+            scale_factor=scale_factor,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Image Upscaler 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_meme_generator/README.md

@@ -1,3 +1,70 @@
+# v1_ai_meme_generator
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Meme 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_meme_generator.generate(
+    style={
+        "search_web": False,
+        "template": "Drake Hotline Bling",
+        "topic": "When the code finally works",
+    },
+    name="My Funny Meme",
+    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_meme_generator.generate(
+    style={
+        "search_web": False,
+        "template": "Drake Hotline Bling",
+        "topic": "When the code finally works",
+    },
+    name="My Funny Meme",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI Meme Generator <a name="create"></a>
 
@@ -10,6 +77,9 @@ Create an AI generated meme. Each meme costs 10 credits.
 | Parameter | Required | Description | Example |
 |-----------|:--------:|-------------|--------|
 | `style` | ✓ |  | `{"search_web": False, "template": "Drake Hotline Bling", "topic": "When the code finally works"}` |
+| `└─ search_web` | ✗ | Whether to search the web for meme content. | `False` |
+| `└─ template` | ✓ | To use our templates, pass in one of the enum values. | `"Drake Hotline Bling"` |
+| `└─ topic` | ✓ | The topic of the meme. | `"When the code finally works"` |
 | `name` | ✗ | The name of the meme. | `"My Funny Meme"` |
 
 #### Synchronous Client
@@ -55,3 +125,4 @@ res = await client.v1.ai_meme_generator.create(
 
 ##### Example
 `{"credits_charged": 10, "frame_cost": 10, "id": "cuid-example"}`
+

magic_hour/resources/v1/ai_meme_generator/client.py

@@ -1,3 +1,4 @@
+import logging
 import typing
 
 from magic_hour.core import (
@@ -8,13 +9,80 @@ 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 AiMemeGeneratorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        style: params.V1AiMemeGeneratorCreateBodyStyle,
+        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 meme (alias for create with additional functionality).
+
+        Create an AI meme. Each meme 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 meme 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 Meme Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_meme_generator.generate(
+            style={
+                "search_web": False,
+                "template": "Drake Hotline Bling",
+                "topic": "When the code finally works",
+            },
+            name="Funny Programming Meme",
+            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 Meme 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,
         *,
@@ -73,6 +141,65 @@ class AsyncAiMemeGeneratorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        style: params.V1AiMemeGeneratorCreateBodyStyle,
+        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 meme (alias for create with additional functionality).
+
+        Create an AI meme. Each meme 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 meme 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 Meme Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_meme_generator.generate(
+            style={
+                "search_web": False,
+                "template": "Drake Hotline Bling",
+                "topic": "When the code finally works",
+            },
+            name="Funny Programming Meme",
+            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 Meme 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_photo_editor/README.md

@@ -1,3 +1,84 @@
+# v1_ai_photo_editor
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Photo 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_photo_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    resolution=768,
+    style={
+        "image_description": "A photo of a person",
+        "likeness_strength": 5.2,
+        "negative_prompt": "painting, cartoon, sketch",
+        "prompt": "A photo portrait of a person wearing a hat",
+        "prompt_strength": 3.75,
+        "steps": 4,
+        "upscale_factor": 2,
+        "upscale_fidelity": 0.5,
+    },
+    name="Photo 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_photo_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    resolution=768,
+    style={
+        "image_description": "A photo of a person",
+        "likeness_strength": 5.2,
+        "negative_prompt": "painting, cartoon, sketch",
+        "prompt": "A photo portrait of a person wearing a hat",
+        "prompt_strength": 3.75,
+        "steps": 4,
+        "upscale_factor": 2,
+        "upscale_fidelity": 0.5,
+    },
+    name="Photo Editor image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### AI Photo Editor <a name="create"></a>
 
@@ -9,13 +90,22 @@ Edit photo using AI. Each photo costs 10 credits.
 
 #### Parameters
 
-| Parameter | Required | Description | Example |
-|-----------|:--------:|-------------|--------|
-| `assets` | ✓ | Provide the assets for photo editor | `{"image_file_path": "api-assets/id/1234.png"}` |
-| `resolution` | ✓ | The resolution of the final output image. The allowed value is based on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details | `768` |
-| `style` | ✓ |  | `{"image_description": "A photo of a person", "likeness_strength": 5.2, "negative_prompt": "painting, cartoon, sketch", "prompt": "A photo portrait of a person wearing a hat", "prompt_strength": 3.75, "steps": 4, "upscale_factor": 2, "upscale_fidelity": 0.5}` |
-| `name` | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Photo Editor image"` |
-| `steps` | ✗ | Deprecated: Please use `.style.steps` instead. Number of iterations used to generate the output. Higher values improve quality and increase the strength of the prompt but increase processing time. | `123` |
+| Parameter | Required | Deprecated | Description | Example |
+|-----------|:--------:|:----------:|-------------|--------|
+| `assets` | ✓ | ✗ | Provide the assets for photo editor | `{"image_file_path": "api-assets/id/1234.png"}` |
+| `└─ image_file_path` | ✓ | — | The image used to generate the output. 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"` |
+| `resolution` | ✓ | ✗ | The resolution of the final output image. The allowed value is based on your subscription. Please refer to our [pricing page](https://magichour.ai/pricing) for more details | `768` |
+| `style` | ✓ | ✗ |  | `{"image_description": "A photo of a person", "likeness_strength": 5.2, "negative_prompt": "painting, cartoon, sketch", "prompt": "A photo portrait of a person wearing a hat", "prompt_strength": 3.75, "steps": 4, "upscale_factor": 2, "upscale_fidelity": 0.5}` |
+| `└─ image_description` | ✓ | — | Use this to describe what your input image is. This helps maintain aspects of the image you don't want to change. | `"A photo of a person"` |
+| `└─ likeness_strength` | ✓ | — | Determines the input image's influence. Higher values align the output more with the initial image. | `5.2` |
+| `└─ negative_prompt` | ✗ | — | What you want to avoid seeing in the final output; has a minor effect. | `"painting, cartoon, sketch"` |
+| `└─ prompt` | ✓ | — | What you want your final output to look like. We recommend starting with the image description and making minor edits for best results. | `"A photo portrait of a person wearing a hat"` |
+| `└─ prompt_strength` | ✓ | — | Determines the prompt's influence. Higher values align the output more with the prompt. | `3.75` |
+| `└─ steps` | ✗ | — | Number of iterations used to generate the output. Higher values improve quality and increase the strength of the prompt but increase processing time. | `4` |
+| `└─ upscale_factor` | ✗ | — | The multiplier applied to an image's original dimensions during the upscaling process. For example, a scale of 2 doubles the width and height (e.g., from 512x512 to 1024x1024). | `2` |
+| `└─ upscale_fidelity` | ✗ | — | Upscale fidelity refers to the level of quality desired in the generated image. Fidelity value of 1 means more details. | `0.5` |
+| `name` | ✗ | ✗ | The name of image. This value is mainly used for your own identification of the image. | `"Photo Editor image"` |
+| `steps` | ✗ | ✓ | Deprecated: Please use `.style.steps` instead. Number of iterations used to generate the output. Higher values improve quality and increase the strength of the prompt but increase processing time. | `123` |
 
 #### Synchronous Client
 
@@ -74,3 +164,4 @@ res = await client.v1.ai_photo_editor.create(
 
 ##### Example
 `{"credits_charged": 10, "frame_cost": 10, "id": "cuid-example"}`
+