feat: add check results function to audio projects (#101)

davidhu2000 · web-flow · commit b99c03234045 · 2025-09-20T11:40:21.000-07:00
diff --git a/README.md b/README.md
@@ -219,6 +219,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
 
diff --git a/magic_hour/helpers/download.py b/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]:
diff --git a/magic_hour/resources/v1/audio_projects/README.md b/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.
diff --git a/magic_hour/resources/v1/audio_projects/__init__.py b/magic_hour/resources/v1/audio_projects/__init__.py
@@ -1,4 +1,12 @@
-from .client import AsyncAudioProjectsClient, AudioProjectsClient
+from .client import (
+    AsyncAudioProjectsClient,
+    V1AudioProjectsGetResponseWithDownloads,
+    AudioProjectsClient,
+)
 
 
-__all__ = ["AsyncAudioProjectsClient", "AudioProjectsClient"]
+__all__ = [
+    "AsyncAudioProjectsClient",
+    "V1AudioProjectsGetResponseWithDownloads",
+    "AudioProjectsClient",
+]
diff --git a/magic_hour/resources/v1/audio_projects/client.py b/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 @@
 )
 
 
+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:
diff --git a/magic_hour/resources/v1/audio_projects/client_test.py b/magic_hour/resources/v1/audio_projects/client_test.py
