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

magic_hour/resources/v1/image_background_remover/README.md

@@ -1,11 +1,84 @@
+# v1.image_background_remover
 
-### create <a name="create"></a>
-Image Background Remover
+## Module Functions
 
-Remove background from image. Each image costs 5 frames.
+<!-- CUSTOM DOCS START -->
+
+### Image Background Remover 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.image_background_remover.generate(
+    assets={
+        "background_image_file_path": "/path/to/1234.png",
+        "image_file_path": "/path/to/1234.png",
+    },
+    name="Background Remover 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.image_background_remover.generate(
+    assets={
+        "background_image_file_path": "/path/to/1234.png",
+        "image_file_path": "/path/to/1234.png",
+    },
+    name="Background Remover image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### Image Background Remover <a name="create"></a>
+
+Remove background from image. Each image costs 5 credits.
 
 **API Endpoint**: `POST /v1/image-background-remover`
 
+#### Parameters
+
+| Parameter                       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Example                                                                                                 |
+| ------------------------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `assets`                        |    ✓     | Provide the assets for background removal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `{"background_image_file_path": "api-assets/id/1234.png", "image_file_path": "api-assets/id/1234.png"}` |
+| `└─ background_image_file_path` |    ✗     | The image used as the new background for the image_file_path. This image will be resized to match the image in image_file_path. Please make sure the resolution between the images are similar. 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_path`            |    ✓     | The image to remove the background. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). Please refer to the [Input File documentation](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) to learn more.                                                                                                                                                             | `"api-assets/id/1234.png"`                                                                              |
+| `name`                          |    ✗     | The name of image. This value is mainly used for your own identification of the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"Background Remover image"`                                                                            |
+
 #### Synchronous Client
 
 ```python
@@ -14,7 +87,10 @@ from os import getenv
 
 client = Client(token=getenv("API_TOKEN"))
 res = client.v1.image_background_remover.create(
-    assets={"image_file_path": "api-assets/id/1234.png"},
+    assets={
+        "background_image_file_path": "api-assets/id/1234.png",
+        "image_file_path": "api-assets/id/1234.png",
+    },
     name="Background Remover image",
 )
 ```
@@ -27,7 +103,22 @@ from os import getenv
 
 client = AsyncClient(token=getenv("API_TOKEN"))
 res = await client.v1.image_background_remover.create(
-    assets={"image_file_path": "api-assets/id/1234.png"},
+    assets={
+        "background_image_file_path": "api-assets/id/1234.png",
+        "image_file_path": "api-assets/id/1234.png",
+    },
     name="Background Remover image",
 )
 ```
+
+#### Response
+
+##### Type
+
+[V1ImageBackgroundRemoverCreateResponse](/magic_hour/types/models/v1_image_background_remover_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 5, "frame_cost": 5, "id": "cuid-example"}
+```

magic_hour/resources/v1/image_background_remover/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,31 +15,93 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__name__)
 
 
 class ImageBackgroundRemoverClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        assets: params.V1ImageBackgroundRemoverGenerateBodyAssets,
+        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 background removed image (alias for create with additional functionality).
+
+        Remove background from image. Each removal 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 background removal
+            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 Image Background Remover API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.image_background_remover.generate(
+            assets={"image_file_path": "path/to/image.png"},
+            name="Background Removed 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, name=name, request_options=request_options
+        )
+        logger.info(f"Image Background Remover 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.PostV1ImageBackgroundRemoverBodyAssets,
+        assets: params.V1ImageBackgroundRemoverCreateBodyAssets,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1ImageBackgroundRemoverResponse:
+    ) -> models.V1ImageBackgroundRemoverCreateResponse:
         """
         Image Background Remover
 
-        Remove background from image. Each image costs 5 frames.
+        Remove background from image. Each image costs 5 credits.
 
         POST /v1/image-background-remover
 
         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 background removal
             request_options: Additional options to customize the HTTP request
 
@@ -46,21 +115,24 @@ class ImageBackgroundRemoverClient:
         Examples:
         ```py
         client.v1.image_background_remover.create(
-            assets={"image_file_path": "api-assets/id/1234.png"},
+            assets={
+                "background_image_file_path": "api-assets/id/1234.png",
+                "image_file_path": "api-assets/id/1234.png",
+            },
             name="Background Remover image",
         )
         ```
         """
         _json = to_encodable(
             item={"name": name, "assets": assets},
-            dump_with=params._SerializerPostV1ImageBackgroundRemoverBody,
+            dump_with=params._SerializerV1ImageBackgroundRemoverCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/image-background-remover",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1ImageBackgroundRemoverResponse,
+            cast_to=models.V1ImageBackgroundRemoverCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -69,24 +141,84 @@ class AsyncImageBackgroundRemoverClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        assets: params.V1ImageBackgroundRemoverGenerateBodyAssets,
+        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 background removed image (alias for create with additional functionality).
+
+        Remove background from image. Each removal 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 background removal
+            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 Image Background Remover API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.image_background_remover.generate(
+            assets={"image_file_path": "path/to/image.png"},
+            name="Background Removed 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, name=name, request_options=request_options
+        )
+        logger.info(f"Image Background Remover 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.PostV1ImageBackgroundRemoverBodyAssets,
+        assets: params.V1ImageBackgroundRemoverCreateBodyAssets,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1ImageBackgroundRemoverResponse:
+    ) -> models.V1ImageBackgroundRemoverCreateResponse:
         """
         Image Background Remover
 
-        Remove background from image. Each image costs 5 frames.
+        Remove background from image. Each image costs 5 credits.
 
         POST /v1/image-background-remover
 
         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 background removal
             request_options: Additional options to customize the HTTP request
 
@@ -100,20 +232,23 @@ class AsyncImageBackgroundRemoverClient:
         Examples:
         ```py
         await client.v1.image_background_remover.create(
-            assets={"image_file_path": "api-assets/id/1234.png"},
+            assets={
+                "background_image_file_path": "api-assets/id/1234.png",
+                "image_file_path": "api-assets/id/1234.png",
+            },
             name="Background Remover image",
         )
         ```
         """
         _json = to_encodable(
             item={"name": name, "assets": assets},
-            dump_with=params._SerializerPostV1ImageBackgroundRemoverBody,
+            dump_with=params._SerializerV1ImageBackgroundRemoverCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/image-background-remover",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1ImageBackgroundRemoverResponse,
+            cast_to=models.V1ImageBackgroundRemoverCreateResponse,
             request_options=request_options or default_request_options(),
         )

magic_hour/resources/v1/image_projects/README.md

@@ -1,11 +1,66 @@
+# v1.image_projects
 
-### delete <a name="delete"></a>
-Delete image
+## Module Functions
 
-Permanently delete the rendered image. This action is not reversible, please be sure before deleting.
+<!-- CUSTOM DOCS START -->
+
+### Check results <a name="check-result"></a>
+
+Poll the details API to check on the status of the rendering. Optionally can also download the output
+
+#### Parameters
+
+| Parameter             | Required | Description                                                                                          | Example          |
+| --------------------- | :------: | ---------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`                  |    ✓     | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. | `"cuid-example"` |
+| `wait_for_completion` |    ✗     | Whether to wait for the project to complete.                                                         | `True`           |
+| `download_outputs`    |    ✗     | Whether to download the generated files                                                              | `True`           |
+| `download_directory`  |    ✗     | Directory to save downloaded files (defaults to current directory)                                   | `"./outputs"`    |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.image_projects.check_result(
+  id="cuid-example",
+  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.image_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### Delete image <a name="delete"></a>
+
+Permanently delete the rendered image(s). This action is not reversible, please be sure before deleting.
 
 **API Endpoint**: `DELETE /v1/image-projects/{id}`
 
+#### Parameters
+
+| Parameter | Required | Description                                                                                          | Example          |
+| --------- | :------: | ---------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`      |    ✓     | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. | `"cuid-example"` |
+
 #### Synchronous Client
 
 ```python
@@ -13,7 +68,7 @@ from magic_hour import Client
 from os import getenv
 
 client = Client(token=getenv("API_TOKEN"))
-res = client.v1.image_projects.delete(id="cm6pvghix03bvyz0zwash6noj")
+res = client.v1.image_projects.delete(id="cuid-example")
 ```
 
 #### Asynchronous Client
@@ -23,15 +78,15 @@ from magic_hour import AsyncClient
 from os import getenv
 
 client = AsyncClient(token=getenv("API_TOKEN"))
-res = await client.v1.image_projects.delete(id="cm6pvghix03bvyz0zwash6noj")
+res = await client.v1.image_projects.delete(id="cuid-example")
 ```
 
-### get <a name="get"></a>
-Get image details
+### Get image details <a name="get"></a>
 
 Get the details of a image project. The `downloads` field will be empty unless the image was successfully rendered.
 
 The image can be one of the following status
+
 - `draft` - not currently used
 - `queued` - the job is queued and waiting for a GPU
 - `rendering` - the generation is in progress
@@ -39,9 +94,14 @@ The image can be one of the following status
 - `error` - an error occurred during rendering
 - `canceled` - image render is canceled by the user
 
-
 **API Endpoint**: `GET /v1/image-projects/{id}`
 
+#### Parameters
+
+| Parameter | Required | Description                                                                                          | Example          |
+| --------- | :------: | ---------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`      |    ✓     | Unique ID of the image project. This value is returned by all of the POST APIs that create an image. | `"cuid-example"` |
+
 #### Synchronous Client
 
 ```python
@@ -49,7 +109,7 @@ from magic_hour import Client
 from os import getenv
 
 client = Client(token=getenv("API_TOKEN"))
-res = client.v1.image_projects.get(id="cm6pvghix03bvyz0zwash6noj")
+res = client.v1.image_projects.get(id="cuid-example")
 ```
 
 #### Asynchronous Client
@@ -59,5 +119,17 @@ from magic_hour import AsyncClient
 from os import getenv
 
 client = AsyncClient(token=getenv("API_TOKEN"))
-res = await client.v1.image_projects.get(id="cm6pvghix03bvyz0zwash6noj")
+res = await client.v1.image_projects.get(id="cuid-example")
+```
+
+#### Response
+
+##### Type
+
+[V1ImageProjectsGetResponse](/magic_hour/types/models/v1_image_projects_get_response.py)
+
+##### Example
+
+```python
+{"created_at": "1970-01-01T00:00:00", "credits_charged": 5, "downloads": [{"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.png"}], "enabled": True, "error": {"code": "no_source_face", "message": "Please use an image with a detectable face"}, "id": "cuid-example", "image_count": 1, "name": "Example Name", "status": "complete", "total_frame_cost": 5, "type_": "AI_IMAGE"}
 ```

magic_hour/resources/v1/image_projects/__init__.py

@@ -1,4 +1,12 @@
-from .client import AsyncImageProjectsClient, ImageProjectsClient
+from .client import (
+    AsyncImageProjectsClient,
+    ImageProjectsClient,
+    V1ImageProjectsGetResponseWithDownloads,
+)
 
 
-__all__ = ["AsyncImageProjectsClient", "ImageProjectsClient"]
+__all__ = [
+    "AsyncImageProjectsClient",
+    "ImageProjectsClient",
+    "V1ImageProjectsGetResponseWithDownloads",
+]