magic_hour 0.41.0__tar.gz → 0.42.0__tar.gz

{magic_hour-0.41.0 → magic_hour-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: magic_hour
-Version: 0.41.0
+Version: 0.42.0
 Summary: Python SDK for Magic Hour API
 Requires-Python: >=3.8,<4.0
 Classifier: Programming Language :: Python :: 3
@@ -226,6 +226,7 @@ download_urls = result.downloads
 ### [v1.ai_voice_generator](magic_hour/resources/v1/ai_voice_generator/README.md)
 
 * [create](magic_hour/resources/v1/ai_voice_generator/README.md#create) - AI Voice Generator
+* [generate](magic_hour/resources/v1/ai_voice_generator/README.md#generate) - Ai Voice Generator Generate Workflow
 
 ### [v1.animation](magic_hour/resources/v1/animation/README.md)
 
@@ -234,6 +235,7 @@ download_urls = result.downloads
 
 ### [v1.audio_projects](magic_hour/resources/v1/audio_projects/README.md)
 
+* [check-result](magic_hour/resources/v1/audio_projects/README.md#check-result) - Check results
 * [delete](magic_hour/resources/v1/audio_projects/README.md#delete) - Delete audio
 * [get](magic_hour/resources/v1/audio_projects/README.md#get) - Get audio details
 

{magic_hour-0.41.0 → magic_hour-0.42.0}/README.md

@@ -211,6 +211,7 @@ download_urls = result.downloads
 ### [v1.ai_voice_generator](magic_hour/resources/v1/ai_voice_generator/README.md)
 
 * [create](magic_hour/resources/v1/ai_voice_generator/README.md#create) - AI Voice Generator
+* [generate](magic_hour/resources/v1/ai_voice_generator/README.md#generate) - Ai Voice Generator Generate Workflow
 
 ### [v1.animation](magic_hour/resources/v1/animation/README.md)
 
@@ -219,6 +220,7 @@ download_urls = result.downloads
 
 ### [v1.audio_projects](magic_hour/resources/v1/audio_projects/README.md)
 
+* [check-result](magic_hour/resources/v1/audio_projects/README.md#check-result) - Check results
 * [delete](magic_hour/resources/v1/audio_projects/README.md#delete) - Delete audio
 * [get](magic_hour/resources/v1/audio_projects/README.md#get) - Get audio details
 

{magic_hour-0.41.0 → magic_hour-0.42.0}/magic_hour/helpers/download.py

@@ -23,6 +23,7 @@ def download_files_sync(
     downloads: Union[
         List[models.V1ImageProjectsGetResponseDownloadsItem],
         List[models.V1VideoProjectsGetResponseDownloadsItem],
+        List[models.V1AudioProjectsGetResponseDownloadsItem],
     ],
     download_directory: Union[str, None] = None,
 ) -> List[str]:
@@ -51,6 +52,7 @@ async def download_files_async(
     downloads: Union[
         List[models.V1ImageProjectsGetResponseDownloadsItem],
         List[models.V1VideoProjectsGetResponseDownloadsItem],
+        List[models.V1AudioProjectsGetResponseDownloadsItem],
     ],
     download_directory: Union[str, None] = None,
 ) -> List[str]:

{magic_hour-0.41.0 → magic_hour-0.42.0}/magic_hour/resources/v1/ai_voice_generator/README.md

@@ -2,6 +2,62 @@
 
 ## 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(
+    style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+    name="Voice Generator audio",
+    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(
+    style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+    name="Voice Generator audio",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
 ### AI Voice Generator <a name="create"></a>
 
 Generate speech from text. Each character costs 0.05 credits. The cost is rounded up to the nearest whole number.

magic_hour-0.42.0/magic_hour/resources/v1/ai_voice_generator/client.py

@@ -0,0 +1,241 @@
+import typing
+
+from magic_hour.helpers.logger import get_sdk_logger
+from magic_hour.resources.v1.audio_projects.client import (
+    AsyncAudioProjectsClient,
+    AudioProjectsClient,
+)
+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 AiVoiceGeneratorClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def generate(
+        self,
+        *,
+        style: params.V1AiVoiceGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate AI voice (alias for create with additional functionality).
+
+        Generate speech from text. Each character costs 0.05 credits. The cost is rounded up to the nearest whole number.
+
+        Args:
+            style: The content used to generate speech.
+            name: The name of audio. This value is mainly used for your own identification of the audio.
+            wait_for_completion: Whether to wait for the audio 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:
+            V1AudioProjectsGetResponseWithDownloads: The response from the AI Voice Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.ai_voice_generator.generate(
+            style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+            name="Generated Voice",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Voice Generator response: {create_response}")
+
+        audio_projects_client = AudioProjectsClient(base_client=self._base_client)
+        response = audio_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,
+        *,
+        style: params.V1AiVoiceGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiVoiceGeneratorCreateResponse:
+        """
+        AI Voice Generator
+
+        Generate speech from text. Each character costs 0.05 credits. The cost is rounded up to the nearest whole number.
+
+        POST /v1/ai-voice-generator
+
+        Args:
+            name: The name of audio. This value is mainly used for your own identification of the audio.
+            style: The content used to generate speech.
+            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_voice_generator.create(
+            style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+            name="Voice Generator audio",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"name": name, "style": style},
+            dump_with=params._SerializerV1AiVoiceGeneratorCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/ai-voice-generator",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiVoiceGeneratorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncAiVoiceGeneratorClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def generate(
+        self,
+        *,
+        style: params.V1AiVoiceGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        wait_for_completion: bool = True,
+        download_outputs: bool = True,
+        download_directory: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ):
+        """
+        Generate AI voice (alias for create with additional functionality).
+
+        Generate speech from text. Each character costs 0.05 credits. The cost is rounded up to the nearest whole number.
+
+        Args:
+            style: The content used to generate speech.
+            name: The name of audio. This value is mainly used for your own identification of the audio.
+            wait_for_completion: Whether to wait for the audio 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:
+            V1AudioProjectsGetResponseWithDownloads: The response from the AI Voice Generator API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.ai_voice_generator.generate(
+            style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+            name="Generated Voice",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            style=style,
+            name=name,
+            request_options=request_options,
+        )
+        logger.info(f"AI Voice Generator response: {create_response}")
+
+        audio_projects_client = AsyncAudioProjectsClient(base_client=self._base_client)
+        response = await audio_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,
+        *,
+        style: params.V1AiVoiceGeneratorCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1AiVoiceGeneratorCreateResponse:
+        """
+        AI Voice Generator
+
+        Generate speech from text. Each character costs 0.05 credits. The cost is rounded up to the nearest whole number.
+
+        POST /v1/ai-voice-generator
+
+        Args:
+            name: The name of audio. This value is mainly used for your own identification of the audio.
+            style: The content used to generate speech.
+            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_voice_generator.create(
+            style={"prompt": "Hello, how are you?", "voice_name": "Elon Musk"},
+            name="Voice Generator audio",
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"name": name, "style": style},
+            dump_with=params._SerializerV1AiVoiceGeneratorCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/ai-voice-generator",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1AiVoiceGeneratorCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

{magic_hour-0.41.0 → magic_hour-0.42.0}/magic_hour/resources/v1/audio_projects/README.md

@@ -2,6 +2,53 @@
 
 ## Module Functions
 
+<!-- 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 audio project. This value is returned by all of the POST APIs that create an audio. | `"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.audio_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.audio_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+```
+
+<!-- CUSTOM DOCS END -->
 ### Delete audio <a name="delete"></a>
 
 Permanently delete the rendered audio file(s). This action is not reversible, please be sure before deleting.

magic_hour-0.42.0/magic_hour/resources/v1/audio_projects/__init__.py

@@ -0,0 +1,12 @@
+from .client import (
+    AsyncAudioProjectsClient,
+    AudioProjectsClient,
+    V1AudioProjectsGetResponseWithDownloads,
+)
+
+
+__all__ = [
+    "AsyncAudioProjectsClient",
+    "AudioProjectsClient",
+    "V1AudioProjectsGetResponseWithDownloads",
+]

{magic_hour-0.41.0 → magic_hour-0.42.0}/magic_hour/resources/v1/audio_projects/client.py

@@ -1,5 +1,10 @@
+import os
+import pydantic
+import time
 import typing
 
+from magic_hour.helpers.download import download_files_async, download_files_sync
+from magic_hour.helpers.logger import get_sdk_logger
 from magic_hour.types import models
 from make_api_request import (
     AsyncBaseClient,
@@ -9,10 +14,83 @@ from make_api_request import (
 )
 
 
+logger = get_sdk_logger(__name__)
+
+
+class V1AudioProjectsGetResponseWithDownloads(models.V1AudioProjectsGetResponse):
+    downloaded_paths: typing.Optional[typing.List[str]] = pydantic.Field(
+        default=None, alias="downloaded_paths"
+    )
+    """
+    The paths to the downloaded files.
+
+    This field is only populated if `download_outputs` is True and the audio project is complete.
+    """
+
+
 class AudioProjectsClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def check_result(
+        self,
+        id: str,
+        wait_for_completion: bool,
+        download_outputs: bool,
+        download_directory: typing.Optional[str] = None,
+    ) -> V1AudioProjectsGetResponseWithDownloads:
+        """
+        Check the result of an audio project with optional waiting and downloading.
+
+        This method retrieves the status of an audio project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the audio project
+            wait_for_completion: Whether to wait for the audio 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
+
+        Returns:
+            V1AudioProjectsGetResponseWithDownloads: The audio project response with optional
+                downloaded file paths included
+        """
+        api_response = self.get(id=id)
+        if not wait_for_completion:
+            response = V1AudioProjectsGetResponseWithDownloads(
+                **api_response.model_dump()
+            )
+            return response
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        status = api_response.status
+
+        while status not in ["complete", "error", "canceled"]:
+            api_response = self.get(id=id)
+            status = api_response.status
+            time.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(
+                f"Audio project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1AudioProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1AudioProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = download_files_sync(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1AudioProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None:
@@ -95,6 +173,65 @@ class AsyncAudioProjectsClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def check_result(
+        self,
+        id: str,
+        wait_for_completion: bool,
+        download_outputs: bool,
+        download_directory: typing.Optional[str] = None,
+    ) -> V1AudioProjectsGetResponseWithDownloads:
+        """
+        Check the result of an audio project with optional waiting and downloading.
+
+        This method retrieves the status of an audio project and optionally waits for completion
+        and downloads the output files.
+
+        Args:
+            id: Unique ID of the audio project
+            wait_for_completion: Whether to wait for the audio 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
+
+        Returns:
+            V1AudioProjectsGetResponseWithDownloads: The audio project response with optional
+                downloaded file paths included
+        """
+        api_response = await self.get(id=id)
+        if not wait_for_completion:
+            response = V1AudioProjectsGetResponseWithDownloads(
+                **api_response.model_dump()
+            )
+            return response
+
+        poll_interval = float(os.getenv("MAGIC_HOUR_POLL_INTERVAL", "0.5"))
+
+        status = api_response.status
+
+        while status not in ["complete", "error", "canceled"]:
+            api_response = await self.get(id=id)
+            status = api_response.status
+            time.sleep(poll_interval)
+
+        if api_response.status != "complete":
+            log = logger.error if api_response.status == "error" else logger.info
+            log(
+                f"Audio project {id} has status {api_response.status}: {api_response.error}"
+            )
+            return V1AudioProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        if not download_outputs:
+            return V1AudioProjectsGetResponseWithDownloads(**api_response.model_dump())
+
+        downloaded_paths = await download_files_async(
+            downloads=api_response.downloads,
+            download_directory=download_directory,
+        )
+
+        return V1AudioProjectsGetResponseWithDownloads(
+            **api_response.model_dump(), downloaded_paths=downloaded_paths
+        )
+
     async def delete(
         self, *, id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> None: