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

magic_hour/resources/v1/ai_photo_editor/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,19 +15,103 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__name__)
 
 
 class AiPhotoEditorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1AiPhotoEditorGenerateBodyAssets,
+        resolution: int,
+        style: params.V1AiPhotoEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        steps: typing.Union[
+            typing.Optional[int], 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 edited photo (alias for create with additional functionality).
+
+        Edit photo using AI. Each edit 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 photo editor
+            style: Photo 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 Photo Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_photo_editor.generate(
+            assets={"image_file_path": "path/to/photo.jpg"},
+            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="Edited Portrait",
+            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,
+            resolution=resolution,
+            style=style,
+            name=name,
+            steps=steps,
+            request_options=request_options,
+        )
+        logger.info(f"AI Photo 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,
         *,
-        assets: params.PostV1AiPhotoEditorBodyAssets,
+        assets: params.V1AiPhotoEditorCreateBodyAssets,
         resolution: int,
-        style: params.PostV1AiPhotoEditorBodyStyle,
+        style: params.V1AiPhotoEditorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -28,22 +119,22 @@ class AiPhotoEditorClient:
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiPhotoEditorResponse:
+    ) -> models.V1AiPhotoEditorCreateResponse:
         """
         AI Photo Editor
 
         > **NOTE**: this API is still in early development stages, and should be avoided. Please reach out to us if you're interested in this API.
 
-        Edit photo using AI. Each photo costs 10 frames.
+        Edit photo using AI. Each photo costs 10 credits.
 
         POST /v1/ai-photo-editor
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the 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.
             assets: Provide the assets for photo editor
             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
-            style: PostV1AiPhotoEditorBodyStyle
+            style: V1AiPhotoEditorCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -61,8 +152,12 @@ class AiPhotoEditorClient:
             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",
         )
@@ -76,14 +171,14 @@ class AiPhotoEditorClient:
                 "resolution": resolution,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiPhotoEditorBody,
+            dump_with=params._SerializerV1AiPhotoEditorCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/ai-photo-editor",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiPhotoEditorResponse,
+            cast_to=models.V1AiPhotoEditorCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -92,12 +187,94 @@ class AsyncAiPhotoEditorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1AiPhotoEditorGenerateBodyAssets,
+        resolution: int,
+        style: params.V1AiPhotoEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        steps: typing.Union[
+            typing.Optional[int], 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 edited photo (alias for create with additional functionality).
+
+        Edit photo using AI. Each edit 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 photo editor
+            style: Photo 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 Photo Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_photo_editor.generate(
+            assets={"image_file_path": "path/to/photo.jpg"},
+            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="Edited Portrait",
+            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,
+            resolution=resolution,
+            style=style,
+            name=name,
+            steps=steps,
+            request_options=request_options,
+        )
+        logger.info(f"AI Photo 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,
         *,
-        assets: params.PostV1AiPhotoEditorBodyAssets,
+        assets: params.V1AiPhotoEditorCreateBodyAssets,
         resolution: int,
-        style: params.PostV1AiPhotoEditorBodyStyle,
+        style: params.V1AiPhotoEditorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -105,22 +282,22 @@ class AsyncAiPhotoEditorClient:
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiPhotoEditorResponse:
+    ) -> models.V1AiPhotoEditorCreateResponse:
         """
         AI Photo Editor
 
         > **NOTE**: this API is still in early development stages, and should be avoided. Please reach out to us if you're interested in this API.
 
-        Edit photo using AI. Each photo costs 10 frames.
+        Edit photo using AI. Each photo costs 10 credits.
 
         POST /v1/ai-photo-editor
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the 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.
             assets: Provide the assets for photo editor
             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
-            style: PostV1AiPhotoEditorBodyStyle
+            style: V1AiPhotoEditorCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -138,8 +315,12 @@ class AsyncAiPhotoEditorClient:
             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",
         )
@@ -153,13 +334,13 @@ class AsyncAiPhotoEditorClient:
                 "resolution": resolution,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1AiPhotoEditorBody,
+            dump_with=params._SerializerV1AiPhotoEditorCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/ai-photo-editor",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiPhotoEditorResponse,
+            cast_to=models.V1AiPhotoEditorCreateResponse,
             request_options=request_options or default_request_options(),
         )

magic_hour/resources/v1/ai_qr_code_generator/README.md

@@ -1,11 +1,80 @@
+# v1.ai_qr_code_generator
 
-### create <a name="create"></a>
-AI QR Code
+## Module Functions
 
-Create an AI QR code. Each QR code costs 20 frames.
+<!-- CUSTOM DOCS START -->
+
+### Ai Qr Code 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_qr_code_generator.generate(
+    content="https://magichour.ai",
+    style={"art_style": "Watercolor"},
+    name="Qr Code 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_qr_code_generator.generate(
+    content="https://magichour.ai",
+    style={"art_style": "Watercolor"},
+    name="Qr Code image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### AI QR Code Generator <a name="create"></a>
+
+Create an AI QR code. Each QR code costs 0 credits.
 
 **API Endpoint**: `POST /v1/ai-qr-code-generator`
 
+#### Parameters
+
+| Parameter      | Required | Description                                                                                                                                                                                                                                 | Example                       |
+| -------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `content`      |    ✓     | The content of the QR code.                                                                                                                                                                                                                 | `"https://magichour.ai"`      |
+| `style`        |    ✓     |                                                                                                                                                                                                                                             | `{"art_style": "Watercolor"}` |
+| `└─ art_style` |    ✓     | To use our templates, pass in one of Watercolor, Cyberpunk City, Ink Landscape, Interior Painting, Japanese Street, Mech, Minecraft, Picasso Painting, Game Map, Spaceship, Chinese Painting, Winter Village, or pass any custom art style. | `"Watercolor"`                |
+| `name`         |    ✗     | The name of image. This value is mainly used for your own identification of the image.                                                                                                                                                      | `"Qr Code image"`             |
+
 #### Synchronous Client
 
 ```python
@@ -33,3 +102,15 @@ res = await client.v1.ai_qr_code_generator.create(
     name="Qr Code image",
 )
 ```
+
+#### Response
+
+##### Type
+
+[V1AiQrCodeGeneratorCreateResponse](/magic_hour/types/models/v1_ai_qr_code_generator_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 0, "frame_cost": 0, "id": "cuid-example"}
+```

magic_hour/resources/v1/ai_qr_code_generator/client.py

@@ -1,6 +1,12 @@
 import typing
 
-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,
@@ -8,34 +14,93 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__name__)
 
 
 class AiQrCodeGeneratorClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        content: str,
+        style: params.V1AiQrCodeGeneratorCreateBodyStyle,
+        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 QR code (alias for create with additional functionality).
+
+        Create an AI QR code. Each QR code 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 QR code 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 QR Code Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_qr_code_generator.generate(
+            content="https://magichour.ai",
+            style={"art_style": "Watercolor"},
+            name="Artistic QR Code",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            content=content, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI QR Code 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,
         *,
         content: str,
-        style: params.PostV1AiQrCodeGeneratorBodyStyle,
+        style: params.V1AiQrCodeGeneratorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiQrCodeGeneratorResponse:
+    ) -> models.V1AiQrCodeGeneratorCreateResponse:
         """
-        AI QR Code
+        AI QR Code Generator
 
-        Create an AI QR code. Each QR code costs 20 frames.
+        Create an AI QR code. Each QR code costs 0 credits.
 
         POST /v1/ai-qr-code-generator
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the image.
             content: The content of the QR code.
-            style: PostV1AiQrCodeGeneratorBodyStyle
+            style: V1AiQrCodeGeneratorCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -56,14 +121,14 @@ class AiQrCodeGeneratorClient:
         """
         _json = to_encodable(
             item={"name": name, "content": content, "style": style},
-            dump_with=params._SerializerPostV1AiQrCodeGeneratorBody,
+            dump_with=params._SerializerV1AiQrCodeGeneratorCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/ai-qr-code-generator",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiQrCodeGeneratorResponse,
+            cast_to=models.V1AiQrCodeGeneratorCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -72,27 +137,84 @@ class AsyncAiQrCodeGeneratorClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        content: str,
+        style: params.V1AiQrCodeGeneratorCreateBodyStyle,
+        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 QR code (alias for create with additional functionality).
+
+        Create an AI QR code. Each QR code 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 QR code 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 QR Code Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_qr_code_generator.generate(
+            content="https://magichour.ai",
+            style={"art_style": "Watercolor"},
+            name="Artistic QR Code",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            content=content, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI QR Code 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,
         *,
         content: str,
-        style: params.PostV1AiQrCodeGeneratorBodyStyle,
+        style: params.V1AiQrCodeGeneratorCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1AiQrCodeGeneratorResponse:
+    ) -> models.V1AiQrCodeGeneratorCreateResponse:
         """
-        AI QR Code
+        AI QR Code Generator
 
-        Create an AI QR code. Each QR code costs 20 frames.
+        Create an AI QR code. Each QR code costs 0 credits.
 
         POST /v1/ai-qr-code-generator
 
         Args:
-            name: The name of image
+            name: The name of image. This value is mainly used for your own identification of the image.
             content: The content of the QR code.
-            style: PostV1AiQrCodeGeneratorBodyStyle
+            style: V1AiQrCodeGeneratorCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -113,13 +235,13 @@ class AsyncAiQrCodeGeneratorClient:
         """
         _json = to_encodable(
             item={"name": name, "content": content, "style": style},
-            dump_with=params._SerializerPostV1AiQrCodeGeneratorBody,
+            dump_with=params._SerializerV1AiQrCodeGeneratorCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/ai-qr-code-generator",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1AiQrCodeGeneratorResponse,
+            cast_to=models.V1AiQrCodeGeneratorCreateResponse,
             request_options=request_options or default_request_options(),
         )