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

magic_hour/resources/v1/ai_talking_photo/README.md

@@ -0,0 +1,137 @@
+# v1.ai_talking_photo
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Ai Talking Photo 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_talking_photo.generate(
+    assets={
+        "audio_file_path": "/path/to/1234.mp3",
+        "image_file_path": "/path/to/1234.png",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Talking Photo 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_talking_photo.generate(
+    assets={
+        "audio_file_path": "/path/to/1234.mp3",
+        "image_file_path": "/path/to/1234.png",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Talking Photo image",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### AI Talking Photo <a name="create"></a>
+
+Create a talking photo from an image and audio or text input.
+
+**API Endpoint**: `POST /v1/ai-talking-photo`
+
+#### Parameters
+
+| Parameter            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Example                                                                                      |
+| -------------------- | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `assets`             |    ✓     | Provide the assets for creating a talking photo                                                                                                                                                                                                                                                                                                                                                                                                                                           | `{"audio_file_path": "api-assets/id/1234.mp3", "image_file_path": "api-assets/id/1234.png"}` |
+| `└─ audio_file_path` |    ✓     | The audio file to sync with the image. 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.mp3"`                                                                   |
+| `└─ image_file_path` |    ✓     | The source image to animate. 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"`                                                                   |
+| `end_seconds`        |    ✓     | The end time of the input audio in seconds. The maximum duration allowed is 60 seconds.                                                                                                                                                                                                                                                                                                                                                                                                   | `15.0`                                                                                       |
+| `start_seconds`      |    ✓     | The start time of the input audio in seconds. The maximum duration allowed is 60 seconds.                                                                                                                                                                                                                                                                                                                                                                                                 | `0.0`                                                                                        |
+| `name`               |    ✗     | The name of image. This value is mainly used for your own identification of the image.                                                                                                                                                                                                                                                                                                                                                                                                    | `"Talking Photo image"`                                                                      |
+| `style`              |    ✗     | Attributes used to dictate the style of the output                                                                                                                                                                                                                                                                                                                                                                                                                                        | `{"generation_mode": "pro", "intensity": 1.5}`                                               |
+| `└─ generation_mode` |    ✗     | Controls overall motion style. * `pro` - Higher fidelity, realistic detail, accurate lip sync, and faster generation. * `standard` - More expressive motion, but lower visual fidelity. * `expressive` - More motion and facial expressiveness; may introduce visual artifacts. (Deprecated: passing this value will be treated as `standard`) * `stable` - Reduced motion for cleaner output; may result in minimal animation. (Deprecated: passing this value will be treated as `pro`) | `"pro"`                                                                                      |
+| `└─ intensity`       |    ✗     | Note: this value is only applicable when generation_mode is `expressive`. The value can include up to 2 decimal places. * Lower values yield more stability but can suppress mouth movement. * Higher values increase motion and expressiveness, with a higher risk of distortion.                                                                                                                                                                                                        | `1.5`                                                                                        |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.ai_talking_photo.create(
+    assets={
+        "audio_file_path": "api-assets/id/1234.mp3",
+        "image_file_path": "api-assets/id/1234.png",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Talking Photo image",
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_talking_photo.create(
+    assets={
+        "audio_file_path": "api-assets/id/1234.mp3",
+        "image_file_path": "api-assets/id/1234.png",
+    },
+    end_seconds=15.0,
+    start_seconds=0.0,
+    name="Talking Photo image",
+)
+```
+
+#### Response
+
+##### Type
+
+[V1AiTalkingPhotoCreateResponse](/magic_hour/types/models/v1_ai_talking_photo_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 450, "estimated_frame_cost": 450, "id": "cuid-example"}
+```

magic_hour/resources/v1/ai_talking_photo/__init__.py

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

magic_hour/resources/v1/ai_talking_photo/client.py

@@ -0,0 +1,326 @@
+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.video_projects.client import (
+    AsyncVideoProjectsClient,
+    VideoProjectsClient,
+)
+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 AiTalkingPhotoClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def generate(
+        self,
+        *,
+        assets: params.V1AiTalkingPhotoGenerateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1AiTalkingPhotoCreateBodyStyle], 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 talking photo (alias for create with additional functionality).
+
+        Create a talking photo from an image and audio or text input. Each generation costs credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: Attributes used to dictate the style of the output
+            assets: Provide the assets for creating a talking photo
+            end_seconds: The end time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            start_seconds: The start time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            wait_for_completion: Whether to wait for the video 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:
+            V1VideoProjectsGetResponseWithDownloads: The response from the AI Talking Photo API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_talking_photo.generate(
+            assets={
+                "audio_file_path": "path/to/audio.mp3",
+                "image_file_path": "path/to/image.png",
+            },
+            end_seconds=30.0,
+            start_seconds=5.0,
+            style={"enhancement": "high"},
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = FilesClient(base_client=self._base_client)
+
+        audio_file_path = assets["audio_file_path"]
+        image_file_path = assets["image_file_path"]
+        assets["audio_file_path"] = file_client.upload_file(file=audio_file_path)
+        assets["image_file_path"] = file_client.upload_file(file=image_file_path)
+
+        create_response = self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            name=name,
+            style=style,
+            request_options=request_options,
+        )
+        logger.info(f"AI Talking Photo response: {create_response}")
+
+        video_projects_client = VideoProjectsClient(base_client=self._base_client)
+        response = video_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.V1AiTalkingPhotoCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1AiTalkingPhotoCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiTalkingPhotoCreateResponse:
+        """
+        AI Talking Photo
+
+        Create a talking photo from an image and audio or text input.
+
+        POST /v1/ai-talking-photo
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: Attributes used to dictate the style of the output
+            assets: Provide the assets for creating a talking photo
+            end_seconds: The end time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            start_seconds: The start time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            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_talking_photo.create(
+            assets={
+                "audio_file_path": "api-assets/id/1234.mp3",
+                "image_file_path": "api-assets/id/1234.png",
+            },
+            end_seconds=15.0,
+            start_seconds=0.0,
+            name="Talking Photo image",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={
+                "name": name,
+                "style": style,
+                "assets": assets,
+                "end_seconds": end_seconds,
+                "start_seconds": start_seconds,
+            },
+            dump_with=params._SerializerV1AiTalkingPhotoCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/ai-talking-photo",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiTalkingPhotoCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncAiTalkingPhotoClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def generate(
+        self,
+        *,
+        assets: params.V1AiTalkingPhotoGenerateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1AiTalkingPhotoCreateBodyStyle], 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 talking photo (alias for create with additional functionality).
+
+        Create a talking photo from an image and audio or text input. Each generation costs credits.
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: Attributes used to dictate the style of the output
+            assets: Provide the assets for creating a talking photo
+            end_seconds: The end time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            start_seconds: The start time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            wait_for_completion: Whether to wait for the video 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:
+            V1VideoProjectsGetResponseWithDownloads: The response from the AI Talking Photo API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_talking_photo.generate(
+            assets={
+                "audio_file_path": "path/to/audio.mp3",
+                "image_file_path": "path/to/image.png",
+            },
+            end_seconds=30.0,
+            start_seconds=5.0,
+            style={"enhancement": "high"},
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        file_client = AsyncFilesClient(base_client=self._base_client)
+
+        audio_file_path = assets["audio_file_path"]
+        image_file_path = assets["image_file_path"]
+        assets["audio_file_path"] = await file_client.upload_file(file=audio_file_path)
+        assets["image_file_path"] = await file_client.upload_file(file=image_file_path)
+
+        create_response = await self.create(
+            assets=assets,
+            end_seconds=end_seconds,
+            start_seconds=start_seconds,
+            name=name,
+            style=style,
+            request_options=request_options,
+        )
+        logger.info(f"AI Talking Photo response: {create_response}")
+
+        video_projects_client = AsyncVideoProjectsClient(base_client=self._base_client)
+        response = await video_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.V1AiTalkingPhotoCreateBodyAssets,
+        end_seconds: float,
+        start_seconds: float,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1AiTalkingPhotoCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiTalkingPhotoCreateResponse:
+        """
+        AI Talking Photo
+
+        Create a talking photo from an image and audio or text input.
+
+        POST /v1/ai-talking-photo
+
+        Args:
+            name: The name of image. This value is mainly used for your own identification of the image.
+            style: Attributes used to dictate the style of the output
+            assets: Provide the assets for creating a talking photo
+            end_seconds: The end time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            start_seconds: The start time of the input audio in seconds. The maximum duration allowed is 60 seconds.
+            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_talking_photo.create(
+            assets={
+                "audio_file_path": "api-assets/id/1234.mp3",
+                "image_file_path": "api-assets/id/1234.png",
+            },
+            end_seconds=15.0,
+            start_seconds=0.0,
+            name="Talking Photo image",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={
+                "name": name,
+                "style": style,
+                "assets": assets,
+                "end_seconds": end_seconds,
+                "start_seconds": start_seconds,
+            },
+            dump_with=params._SerializerV1AiTalkingPhotoCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/ai-talking-photo",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiTalkingPhotoCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

magic_hour/resources/v1/ai_voice_cloner/README.md

@@ -0,0 +1,62 @@
+# v1.ai_voice_cloner
+
+## Module Functions
+
+### AI Voice Cloner <a name="create"></a>
+
+Clone a voice from an audio sample and generate speech.
+
+- Each character costs 0.05 credits.
+- The cost is rounded up to the nearest whole number
+
+**API Endpoint**: `POST /v1/ai-voice-cloner`
+
+#### Parameters
+
+| Parameter            | Required | Description                                                                                                                                                                                                                                                                                                                                                                           | Example                                         |
+| -------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `assets`             |    ✓     | Provide the assets for voice cloning.                                                                                                                                                                                                                                                                                                                                                 | `{"audio_file_path": "api-assets/id/1234.mp3"}` |
+| `└─ audio_file_path` |    ✓     | The audio used to clone the voice. 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.mp3"`                      |
+| `style`              |    ✓     |                                                                                                                                                                                                                                                                                                                                                                                       | `{"prompt": "Hello, this is my cloned voice."}` |
+| `└─ prompt`          |    ✓     | Text used to generate speech from the cloned voice. The character limit is 1000 characters.                                                                                                                                                                                                                                                                                           | `"Hello, this is my cloned voice."`             |
+| `name`               |    ✗     | The name of audio. This value is mainly used for your own identification of the audio.                                                                                                                                                                                                                                                                                                | `"Voice Cloner audio"`                          |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.ai_voice_cloner.create(
+    assets={"audio_file_path": "api-assets/id/1234.mp3"},
+    style={"prompt": "Hello, this is my cloned voice."},
+    name="Voice Cloner audio",
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_voice_cloner.create(
+    assets={"audio_file_path": "api-assets/id/1234.mp3"},
+    style={"prompt": "Hello, this is my cloned voice."},
+    name="Voice Cloner audio",
+)
+```
+
+#### Response
+
+##### Type
+
+[V1AiVoiceClonerCreateResponse](/magic_hour/types/models/v1_ai_voice_cloner_create_response.py)
+
+##### Example
+
+```python
+{"credits_charged": 1, "id": "cuid-example"}
+```

magic_hour/resources/v1/ai_voice_cloner/__init__.py

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