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

magic_hour/resources/v1/ai_image_editor/README.md

@@ -0,0 +1,125 @@
+# v1.ai_image_editor
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Image 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_image_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    style={"prompt": "Give me sunglasses"},
+    name="Ai Image 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_image_editor.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    style={"prompt": "Give me sunglasses"},
+    name="Ai Image Editor image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### AI Image Editor <a name="create"></a>
+
+Edit images with AI. Each edit costs 50 credits.
+
+**API Endpoint**: `POST /v1/ai-image-editor`
+
+#### Parameters
+
+| Parameter             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Example                                                                                                                   |
+| --------------------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `assets`              |    ✓     | Provide the assets for image edit                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `{"image_file_path": "api-assets/id/1234.png", "image_file_paths": ["api-assets/id/1234.png", "api-assets/id/1235.png"]}` |
+| `└─ image_file_path`  |    ✗     | Deprecated: Please use `image_file_paths` instead as edits with multiple images are now supported. The image used in the edit. 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"`                                                                                                |
+| `└─ image_file_paths` |    ✗     | The image(s) used in the edit, maximum of 10 images. 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", "api-assets/id/1235.png"]`                                                                    |
+| `style`               |    ✓     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `{"model": "Nano Banana", "prompt": "Give me sunglasses"}`                                                                |
+| `└─ model`            |    ✗     | The AI model to use for image editing. * `Nano Banana` - Precise, realistic edits with consistent results * `Seedream` - Creative, imaginative images with artistic freedom * `default` - Use the model we recommend, which will change over time. This is recommended unless you need a specific model. This is the default behavior.                                                                                                                                            | `"Nano Banana"`                                                                                                           |
+| `└─ prompt`           |    ✓     | The prompt used to edit the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"Give me sunglasses"`                                                                                                    |
+| `name`                |    ✗     | The name of image. This value is mainly used for your own identification of the image.                                                                                                                                                                                                                                                                                                                                                                                            | `"Ai Image Editor image"`                                                                                                 |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.ai_image_editor.create(
+    assets={
+        "image_file_path": "api-assets/id/1234.png",
+        "image_file_paths": ["api-assets/id/1234.png", "api-assets/id/1235.png"],
+    },
+    style={"model": "Nano Banana", "prompt": "Give me sunglasses"},
+    name="Ai Image Editor image",
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_image_editor.create(
+    assets={
+        "image_file_path": "api-assets/id/1234.png",
+        "image_file_paths": ["api-assets/id/1234.png", "api-assets/id/1235.png"],
+    },
+    style={"model": "Nano Banana", "prompt": "Give me sunglasses"},
+    name="Ai Image Editor image",
+)
+```
+
+#### Response
+
+##### Type
+
+[V1AiImageEditorCreateResponse](/magic_hour/types/models/v1_ai_image_editor_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 50, "frame_cost": 50, "id": "cuid-example"}
+```

magic_hour/resources/v1/ai_image_editor/__init__.py

@@ -0,0 +1,4 @@
+from .client import AiImageEditorClient, AsyncAiImageEditorClient
+
+
+__all__ = ["AiImageEditorClient", "AsyncAiImageEditorClient"]

magic_hour/resources/v1/ai_image_editor/client.py

@@ -0,0 +1,290 @@
+import typing
+
+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,
+    default_request_options,
+    to_encodable,
+    type_utils,
+)
+
+
+logger = get_sdk_logger(__name__)
+
+
+class AiImageEditorClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def generate(
+        self,
+        *,
+        assets: params.V1AiImageEditorGenerateBodyAssets,
+        style: params.V1AiImageEditorCreateBodyStyle,
+        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 edited image (alias for create with additional functionality).
+
+        Edit image 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 image editor
+            style: Image 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 Image Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_image_editor.generate(
+            assets={"image_file_paths": ["path/to/image.png", "path/to/image2.png"]},
+            style={"prompt": "Add a sunset background"},
+            name="Edited Image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        if "image_file_path" in assets:
+            image_file_path = assets["image_file_path"]
+            assets["image_file_path"] = file_client.upload_file(file=image_file_path)
+
+        if "image_file_paths" in assets:
+            for image_file_path in assets["image_file_paths"]:
+                assets["image_file_paths"] = [
+                    file_client.upload_file(file=image_file_path)
+                    for image_file_path in assets["image_file_paths"]
+                ]
+
+        create_response = self.create(
+            assets=assets, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI Image 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.V1AiImageEditorCreateBodyAssets,
+        style: params.V1AiImageEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiImageEditorCreateResponse:
+        """
+        AI Image Editor
+
+        Edit images with AI. Each edit costs 50 credits.
+
+        POST /v1/ai-image-editor
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for image edit
+            style: V1AiImageEditorCreateBodyStyle
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            Success
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        client.v1.ai_image_editor.create(
+            assets={
+                "image_file_path": "api-assets/id/1234.png",
+                "image_file_paths": [
+                    "api-assets/id/1234.png",
+                    "api-assets/id/1235.png",
+                ],
+            },
+            style={"model": "Nano Banana", "prompt": "Give me sunglasses"},
+            name="Ai Image Editor image",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"name": name, "assets": assets, "style": style},
+            dump_with=params._SerializerV1AiImageEditorCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/ai-image-editor",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiImageEditorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncAiImageEditorClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def generate(
+        self,
+        *,
+        assets: params.V1AiImageEditorGenerateBodyAssets,
+        style: params.V1AiImageEditorCreateBodyStyle,
+        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 edited image (alias for create with additional functionality).
+
+        Edit image 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 image editor
+            style: Image 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 Image Editor API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_image_editor.generate(
+            assets={"image_file_paths": ["path/to/image.png", "path/to/image2.png"]},
+            style={"prompt": "Add a sunset background"},
+            name="Edited Image",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        if "image_file_path" in assets:
+            image_file_path = assets["image_file_path"]
+            assets["image_file_path"] = await file_client.upload_file(
+                file=image_file_path
+            )
+
+        if "image_file_paths" in assets:
+            for image_file_path in assets["image_file_paths"]:
+                assets["image_file_paths"] = [
+                    await file_client.upload_file(file=image_file_path)
+                    for image_file_path in assets["image_file_paths"]
+                ]
+
+        create_response = await self.create(
+            assets=assets, style=style, name=name, request_options=request_options
+        )
+        logger.info(f"AI Image 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.V1AiImageEditorCreateBodyAssets,
+        style: params.V1AiImageEditorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiImageEditorCreateResponse:
+        """
+        AI Image Editor
+
+        Edit images with AI. Each edit costs 50 credits.
+
+        POST /v1/ai-image-editor
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            assets: Provide the assets for image edit
+            style: V1AiImageEditorCreateBodyStyle
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            Success
+
+        Raises:
+            ApiError: A custom exception class that provides additional context
+                for API errors, including the HTTP status code and response body.
+
+        Examples:
+        ```py
+        await client.v1.ai_image_editor.create(
+            assets={
+                "image_file_path": "api-assets/id/1234.png",
+                "image_file_paths": [
+                    "api-assets/id/1234.png",
+                    "api-assets/id/1235.png",
+                ],
+            },
+            style={"model": "Nano Banana", "prompt": "Give me sunglasses"},
+            name="Ai Image Editor image",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"name": name, "assets": assets, "style": style},
+            dump_with=params._SerializerV1AiImageEditorCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/ai-image-editor",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiImageEditorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

magic_hour/resources/v1/ai_image_generator/README.md

@@ -1,11 +1,85 @@
+# v1.ai_image_generator
 
-### create <a name="create"></a>
-AI Images
+## Module Functions
 
-Create an AI image. Each image costs 5 frames.
+<!-- CUSTOM DOCS START -->
+
+### Ai Image 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_image_generator.generate(
+    image_count=1,
+    orientation="landscape",
+    style={"prompt": "Cool image", "tool": "ai-anime-generator"},
+    name="Ai Image 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_generator.generate(
+    image_count=1,
+    orientation="landscape",
+    style={"prompt": "Cool image", "tool": "ai-anime-generator"},
+    name="Ai Image image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### AI Image Generator <a name="create"></a>
+
+Create an AI image. Each standard image costs 5 credits. Pro quality images cost 30 credits.
 
 **API Endpoint**: `POST /v1/ai-image-generator`
 
+#### Parameters
+
+| Parameter         | Required | Description                                                                                                                                                                                                                                                                                                                                        | Example                                                                              |
+| ----------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `image_count`     |    ✓     | Number of images to generate.                                                                                                                                                                                                                                                                                                                      | `1`                                                                                  |
+| `orientation`     |    ✓     | The orientation of the output image(s).                                                                                                                                                                                                                                                                                                            | `"landscape"`                                                                        |
+| `style`           |    ✓     | The art style to use for image generation.                                                                                                                                                                                                                                                                                                         | `{"prompt": "Cool image", "quality_mode": "standard", "tool": "ai-anime-generator"}` |
+| `└─ prompt`       |    ✓     | The prompt used for the image(s).                                                                                                                                                                                                                                                                                                                  | `"Cool image"`                                                                       |
+| `└─ quality_mode` |    ✗     | Controls the quality of the generated image. Defaults to 'standard' if not specified. **Options:** - `standard` - Standard quality generation. Cost: 5 credits per image. - `pro` - Pro quality generation with enhanced details and quality. Cost: 30 credits per image. Note: Pro mode is available for users on Creator, Pro, or Business tier. | `"standard"`                                                                         |
+| `└─ tool`         |    ✗     | The art style to use for image generation. Defaults to 'general' if not provided.                                                                                                                                                                                                                                                                  | `"ai-anime-generator"`                                                               |
+| `name`            |    ✗     | The name of image. This value is mainly used for your own identification of the image.                                                                                                                                                                                                                                                             | `"Ai Image image"`                                                                   |
+
 #### Synchronous Client
 
 ```python
@@ -16,7 +90,11 @@ client = Client(token=getenv("API_TOKEN"))
 res = 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",
 )
 ```
@@ -31,7 +109,23 @@ client = AsyncClient(token=getenv("API_TOKEN"))
 res = 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",
 )
 ```
+
+#### Response
+
+##### Type
+
+[V1AiImageGeneratorCreateResponse](/magic_hour/types/models/v1_ai_image_generator_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 5, "frame_cost": 5, "id": "cuid-example"}
+```