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

magic_hour/resources/v1/ai_image_generator/client.py

@@ -1,7 +1,13 @@
 import typing
 import typing_extensions
 
-from magic_hour.core import (
+from magic_hour.helpers.logger import get_sdk_logger
+from magic_hour.resources.v1.image_projects.client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+)
+from magic_hour.types import models, params
+from make_api_request import (
     AsyncBaseClient,
     RequestOptions,
     SyncBaseClient,
@@ -9,36 +15,103 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__name__)
 
 
 class AiImageGeneratorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        image_count: int,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1AiImageGeneratorCreateBodyStyle,
+        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 AI images (alias for create with additional functionality).
+
+        Create AI images with text prompts. Each image costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            image_count: Number of images to generate.
+            orientation: The orientation of the output image(s).
+            style: The art style to use for image 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 Image Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_image_generator.generate(
+            image_count=1,
+            orientation="landscape",
+            style={"prompt": "Cool image", "tool": "ai-anime-generator"},
+            name="Generated Image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            image_count=image_count,
+            orientation=orientation,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Image 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,
         *,
         image_count: int,
         orientation: typing_extensions.Literal["landscape", "portrait", "square"],
-        style: params.PostV1AiImageGeneratorBodyStyle,
+        style: params.V1AiImageGeneratorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiImageGeneratorResponse:
+    ) -> models.V1AiImageGeneratorCreateResponse:
         """
-        AI Images
+        AI Image Generator
 
-        Create an AI image. Each image costs 5 frames.
+        Create an AI image. Each standard image costs 5 credits. Pro quality images cost 30 credits.
 
         POST /v1/ai-image-generator
 
         Args:
-            name: The name of image
-            image_count: number to images to generate
-            orientation: typing_extensions.Literal["landscape", "portrait", "square"]
-            style: PostV1AiImageGeneratorBodyStyle
+            name: The name of image. This value is mainly used for your own identification of the image.
+            image_count: Number of images to generate.
+            orientation: The orientation of the output image(s).
+            style: The art style to use for image generation.
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -53,7 +126,11 @@ class AiImageGeneratorClient:
         client.v1.ai_image_generator.create(
             image_count=1,
             orientation="landscape",
-            style={"prompt": "Cool image"},
+            style={
+                "prompt": "Cool image",
+                "quality_mode": "standard",
+                "tool": "ai-anime-generator",
+            },
             name="Ai Image image",
         )
         ```
@@ -65,14 +142,14 @@ class AiImageGeneratorClient:
                 "orientation": orientation,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiImageGeneratorBody,
+            dump_with=params._SerializerV1AiImageGeneratorCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/ai-image-generator",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiImageGeneratorResponse,
+            cast_to=models.V1AiImageGeneratorCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -81,29 +158,94 @@ class AsyncAiImageGeneratorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        image_count: int,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1AiImageGeneratorCreateBodyStyle,
+        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 AI images (alias for create with additional functionality).
+
+        Create AI images with text prompts. Each image costs 5 credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            image_count: Number of images to generate.
+            orientation: The orientation of the output image(s).
+            style: The art style to use for image 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 Image Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_image_generator.generate(
+            image_count=1,
+            orientation="landscape",
+            style={"prompt": "Cool image", "tool": "ai-anime-generator"},
+            name="Generated Image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            image_count=image_count,
+            orientation=orientation,
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Image 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,
         *,
         image_count: int,
         orientation: typing_extensions.Literal["landscape", "portrait", "square"],
-        style: params.PostV1AiImageGeneratorBodyStyle,
+        style: params.V1AiImageGeneratorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiImageGeneratorResponse:
+    ) -> models.V1AiImageGeneratorCreateResponse:
         """
-        AI Images
+        AI Image Generator
 
-        Create an AI image. Each image costs 5 frames.
+        Create an AI image. Each standard image costs 5 credits. Pro quality images cost 30 credits.
 
         POST /v1/ai-image-generator
 
         Args:
-            name: The name of image
-            image_count: number to images to generate
-            orientation: typing_extensions.Literal["landscape", "portrait", "square"]
-            style: PostV1AiImageGeneratorBodyStyle
+            name: The name of image. This value is mainly used for your own identification of the image.
+            image_count: Number of images to generate.
+            orientation: The orientation of the output image(s).
+            style: The art style to use for image generation.
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -118,7 +260,11 @@ class AsyncAiImageGeneratorClient:
         await client.v1.ai_image_generator.create(
             image_count=1,
             orientation="landscape",
-            style={"prompt": "Cool image"},
+            style={
+                "prompt": "Cool image",
+                "quality_mode": "standard",
+                "tool": "ai-anime-generator",
+            },
             name="Ai Image image",
         )
         ```
@@ -130,13 +276,13 @@ class AsyncAiImageGeneratorClient:
                 "orientation": orientation,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiImageGeneratorBody,
+            dump_with=params._SerializerV1AiImageGeneratorCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/ai-image-generator",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiImageGeneratorResponse,
+            cast_to=models.V1AiImageGeneratorCreateResponse,
             request_options=request_options or default_request_options(),
         )

magic_hour/resources/v1/ai_image_upscaler/README.md

@@ -1,11 +1,85 @@
+# v1.ai_image_upscaler
 
-### create <a name="create"></a>
-AI Image Upscaler
+## Module Functions
 
-Upscale your image using AI. Each 2x upscale costs 50 frames, and 4x upscale costs 200 frames.
+<!-- 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>
+
+Upscale your image using AI. Each 2x upscale costs 50 credits, and 4x upscale costs 200 credits.
 
 **API Endpoint**: `POST /v1/ai-image-upscaler`
 
+#### Parameters
+
+| 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
 
 ```python
@@ -35,3 +109,15 @@ res = await client.v1.ai_image_upscaler.create(
     name="Image Upscaler image",
 )
 ```
+
+#### Response
+
+##### Type
+
+[V1AiImageUpscalerCreateResponse](/magic_hour/types/models/v1_ai_image_upscaler_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 50, "frame_cost": 50, "id": "cuid-example"}
+```

magic_hour/resources/v1/ai_image_upscaler/client.py

@@ -1,6 +1,13 @@
 import typing
 
-from magic_hour.core import (
+from magic_hour.helpers.logger import get_sdk_logger
+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
+from make_api_request import (
     AsyncBaseClient,
     RequestOptions,
     SyncBaseClient,
@@ -8,36 +15,110 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__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,
         *,
-        assets: params.PostV1AiImageUpscalerBodyAssets,
+        assets: params.V1AiImageUpscalerCreateBodyAssets,
         scale_factor: float,
-        style: params.PostV1AiImageUpscalerBodyStyle,
+        style: params.V1AiImageUpscalerCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiImageUpscalerResponse:
+    ) -> models.V1AiImageUpscalerCreateResponse:
         """
         AI Image Upscaler
 
-        Upscale your image using AI. Each 2x upscale costs 50 frames, and 4x upscale costs 200 frames.
+        Upscale your image using AI. Each 2x upscale costs 50 credits, and 4x upscale costs 200 credits.
 
         POST /v1/ai-image-upscaler
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the image.
             assets: Provide the assets for upscaling
-            scale_factor: How much to scale the image. Must be either 2 or 4
-            style: PostV1AiImageUpscalerBodyStyle
+            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.
+            style: V1AiImageUpscalerCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -64,14 +145,14 @@ class AiImageUpscalerClient:
                 "scale_factor": scale_factor,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiImageUpscalerBody,
+            dump_with=params._SerializerV1AiImageUpscalerCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/ai-image-upscaler",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiImageUpscalerResponse,
+            cast_to=models.V1AiImageUpscalerCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -80,29 +161,101 @@ 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,
         *,
-        assets: params.PostV1AiImageUpscalerBodyAssets,
+        assets: params.V1AiImageUpscalerCreateBodyAssets,
         scale_factor: float,
-        style: params.PostV1AiImageUpscalerBodyStyle,
+        style: params.V1AiImageUpscalerCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiImageUpscalerResponse:
+    ) -> models.V1AiImageUpscalerCreateResponse:
         """
         AI Image Upscaler
 
-        Upscale your image using AI. Each 2x upscale costs 50 frames, and 4x upscale costs 200 frames.
+        Upscale your image using AI. Each 2x upscale costs 50 credits, and 4x upscale costs 200 credits.
 
         POST /v1/ai-image-upscaler
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the image.
             assets: Provide the assets for upscaling
-            scale_factor: How much to scale the image. Must be either 2 or 4
-            style: PostV1AiImageUpscalerBodyStyle
+            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.
+            style: V1AiImageUpscalerCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -129,13 +282,13 @@ class AsyncAiImageUpscalerClient:
                 "scale_factor": scale_factor,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiImageUpscalerBody,
+            dump_with=params._SerializerV1AiImageUpscalerCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/ai-image-upscaler",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiImageUpscalerResponse,
+            cast_to=models.V1AiImageUpscalerCreateResponse,
             request_options=request_options or default_request_options(),
         )