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

magic_hour/resources/v1/text_to_video/client.py

@@ -1,7 +1,13 @@
 import typing
 import typing_extensions
 
-from magic_hour.core import (
+from magic_hour.helpers.logger import get_sdk_logger
+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,
@@ -9,39 +15,128 @@ from magic_hour.core import (
     to_encodable,
     type_utils,
 )
-from magic_hour.types import models, params
+
+
+logger = get_sdk_logger(__name__)
 
 
 class TextToVideoClient:
     def __init__(self, *, base_client: SyncBaseClient):
         self._base_client = base_client
 
+    def generate(
+        self,
+        *,
+        end_seconds: float,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1TextToVideoCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            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 text-to-video (alias for create with additional functionality).
+
+        Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+            end_seconds: The total duration of the output video in seconds.
+            orientation: Determines the orientation of the output video
+            style: V1TextToVideoCreateBodyStyle
+            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 Text-to-Video API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = client.v1.text_to_video.generate(
+            end_seconds=5.0,
+            orientation="landscape",
+            style={"prompt": "a dog running through a meadow"},
+            resolution="720p",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = self.create(
+            end_seconds=end_seconds,
+            orientation=orientation,
+            style=style,
+            name=name,
+            resolution=resolution,
+            request_options=request_options,
+        )
+        logger.info(f"Text-to-Video 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,
         *,
         end_seconds: float,
         orientation: typing_extensions.Literal["landscape", "portrait", "square"],
-        style: params.PostV1TextToVideoBodyStyle,
+        style: params.V1TextToVideoCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            type_utils.NotGiven,
+        ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1TextToVideoResponse:
+    ) -> models.V1TextToVideoCreateResponse:
         """
         Text-to-Video
 
         Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
 
-        Get more information about this mode at our [product page](/products/text-to-video).
+        Get more information about this mode at our [product page](https://magichour.ai/products/text-to-video).
 
 
         POST /v1/text-to-video
 
         Args:
-            name: The name of video
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+
+        480p and 720p are available on Creator, Pro, or Business tiers. However, 1080p require Pro or Business tier.
+
+        **Options:**
+        - `480p` - Supports only 5 or 10 second videos. Output: 24fps. Cost: 120 credits per 5 seconds.
+        - `720p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 300 credits per 5 seconds.
+        - `1080p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 600 credits per 5 seconds.
             end_seconds: The total duration of the output video in seconds.
+
+        The value must be greater than or equal to 5 seconds and less than or equal to 60 seconds.
+
+        Note: For 480p resolution, the value must be either 5 or 10.
             orientation: Determines the orientation of the output video
-            style: PostV1TextToVideoBodyStyle
+            style: V1TextToVideoCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -56,26 +151,28 @@ class TextToVideoClient:
         client.v1.text_to_video.create(
             end_seconds=5.0,
             orientation="landscape",
-            style={"prompt": "string"},
+            style={"prompt": "a dog running"},
             name="Text To Video video",
+            resolution="720p",
         )
         ```
         """
         _json = to_encodable(
             item={
                 "name": name,
+                "resolution": resolution,
                 "end_seconds": end_seconds,
                 "orientation": orientation,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1TextToVideoBody,
+            dump_with=params._SerializerV1TextToVideoCreateBody,
         )
         return self._base_client.request(
             method="POST",
             path="/v1/text-to-video",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1TextToVideoResponse,
+            cast_to=models.V1TextToVideoCreateResponse,
             request_options=request_options or default_request_options(),
         )
 
@@ -84,32 +181,119 @@ class AsyncTextToVideoClient:
     def __init__(self, *, base_client: AsyncBaseClient):
         self._base_client = base_client
 
+    async def generate(
+        self,
+        *,
+        end_seconds: float,
+        orientation: typing_extensions.Literal["landscape", "portrait", "square"],
+        style: params.V1TextToVideoCreateBodyStyle,
+        name: typing.Union[
+            typing.Optional[str], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            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 text-to-video (alias for create with additional functionality).
+
+        Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
+
+        Args:
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+            end_seconds: The total duration of the output video in seconds.
+            orientation: Determines the orientation of the output video
+            style: V1TextToVideoCreateBodyStyle
+            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 Text-to-Video API with the downloaded paths if `download_outputs` is True.
+
+        Examples:
+        ```py
+        response = await client.v1.text_to_video.generate(
+            end_seconds=5.0,
+            orientation="landscape",
+            style={"prompt": "a dog running through a meadow"},
+            resolution="720p",
+            wait_for_completion=True,
+            download_outputs=True,
+            download_directory="outputs/",
+        )
+        ```
+        """
+
+        create_response = await self.create(
+            end_seconds=end_seconds,
+            orientation=orientation,
+            style=style,
+            name=name,
+            resolution=resolution,
+            request_options=request_options,
+        )
+        logger.info(f"Text-to-Video 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,
         *,
         end_seconds: float,
         orientation: typing_extensions.Literal["landscape", "portrait", "square"],
-        style: params.PostV1TextToVideoBodyStyle,
+        style: params.V1TextToVideoCreateBodyStyle,
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        resolution: typing.Union[
+            typing.Optional[typing_extensions.Literal["1080p", "480p", "720p"]],
+            type_utils.NotGiven,
+        ] = type_utils.NOT_GIVEN,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> models.PostV1TextToVideoResponse:
+    ) -> models.V1TextToVideoCreateResponse:
         """
         Text-to-Video
 
         Create a Text To Video video. The estimated frame cost is calculated using 30 FPS. This amount is deducted from your account balance when a video is queued. Once the video is complete, the cost will be updated based on the actual number of frames rendered.
 
-        Get more information about this mode at our [product page](/products/text-to-video).
+        Get more information about this mode at our [product page](https://magichour.ai/products/text-to-video).
 
 
         POST /v1/text-to-video
 
         Args:
-            name: The name of video
+            name: The name of video. This value is mainly used for your own identification of the video.
+            resolution: Controls the output video resolution. Defaults to `720p` if not specified.
+
+        480p and 720p are available on Creator, Pro, or Business tiers. However, 1080p require Pro or Business tier.
+
+        **Options:**
+        - `480p` - Supports only 5 or 10 second videos. Output: 24fps. Cost: 120 credits per 5 seconds.
+        - `720p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 300 credits per 5 seconds.
+        - `1080p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 600 credits per 5 seconds.
             end_seconds: The total duration of the output video in seconds.
+
+        The value must be greater than or equal to 5 seconds and less than or equal to 60 seconds.
+
+        Note: For 480p resolution, the value must be either 5 or 10.
             orientation: Determines the orientation of the output video
-            style: PostV1TextToVideoBodyStyle
+            style: V1TextToVideoCreateBodyStyle
             request_options: Additional options to customize the HTTP request
 
         Returns:
@@ -124,25 +308,27 @@ class AsyncTextToVideoClient:
         await client.v1.text_to_video.create(
             end_seconds=5.0,
             orientation="landscape",
-            style={"prompt": "string"},
+            style={"prompt": "a dog running"},
             name="Text To Video video",
+            resolution="720p",
         )
         ```
         """
         _json = to_encodable(
             item={
                 "name": name,
+                "resolution": resolution,
                 "end_seconds": end_seconds,
                 "orientation": orientation,
                 "style": style,
             },
-            dump_with=params._SerializerPostV1TextToVideoBody,
+            dump_with=params._SerializerV1TextToVideoCreateBody,
         )
         return await self._base_client.request(
             method="POST",
             path="/v1/text-to-video",
             auth_names=["bearerAuth"],
             json=_json,
-            cast_to=models.PostV1TextToVideoResponse,
+            cast_to=models.V1TextToVideoCreateResponse,
             request_options=request_options or default_request_options(),
         )

magic_hour/resources/v1/video_projects/README.md

@@ -1,11 +1,66 @@
+# v1.video_projects
 
-### delete <a name="delete"></a>
-Delete video
+## 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 video project. This value is returned by all of the POST APIs that create an video. | `"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.video_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.video_projects.check_result(
+  id="cuid-example",
+  wait_for_completion=True,
+  download_outputs=True,
+  download_directory="outputs",
+)
+```
+
+<!-- CUSTOM DOCS END -->
+
+### Delete video <a name="delete"></a>
 
 Permanently delete the rendered video. This action is not reversible, please be sure before deleting.
 
 **API Endpoint**: `DELETE /v1/video-projects/{id}`
 
+#### Parameters
+
+| Parameter | Required | Description                                                                                         | Example          |
+| --------- | :------: | --------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`      |    ✓     | Unique ID of the video project. This value is returned by all of the POST APIs that create a video. | `"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.video_projects.delete(id="cm6pvghix03bvyz0zwash6noj")
+res = client.v1.video_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.video_projects.delete(id="cm6pvghix03bvyz0zwash6noj")
+res = await client.v1.video_projects.delete(id="cuid-example")
 ```
 
-### get <a name="get"></a>
-Get video details
+### Get video details <a name="get"></a>
 
 Get the details of a video project. The `downloads` field will be empty unless the video was successfully rendered.
 
 The video 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 video can be one of the following status
 - `error` - an error occurred during rendering
 - `canceled` - video render is canceled by the user
 
-
 **API Endpoint**: `GET /v1/video-projects/{id}`
 
+#### Parameters
+
+| Parameter | Required | Description                                                                                         | Example          |
+| --------- | :------: | --------------------------------------------------------------------------------------------------- | ---------------- |
+| `id`      |    ✓     | Unique ID of the video project. This value is returned by all of the POST APIs that create a video. | `"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.video_projects.get(id="cm6pvghix03bvyz0zwash6noj")
+res = client.v1.video_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.video_projects.get(id="cm6pvghix03bvyz0zwash6noj")
+res = await client.v1.video_projects.get(id="cuid-example")
+```
+
+#### Response
+
+##### Type
+
+[V1VideoProjectsGetResponse](/magic_hour/types/models/v1_video_projects_get_response.py)
+
+##### Example
+
+```python
+{"created_at": "1970-01-01T00:00:00", "credits_charged": 450, "download": {"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.mp4"}, "downloads": [{"expires_at": "2024-10-19T05:16:19.027Z", "url": "https://videos.magichour.ai/id/output.mp4"}], "enabled": True, "end_seconds": 15.0, "error": {"code": "no_source_face", "message": "Please use an image with a detectable face"}, "fps": 30.0, "height": 960, "id": "cuid-example", "name": "Example Name", "start_seconds": 0.0, "status": "complete", "total_frame_cost": 450, "type_": "FACE_SWAP", "width": 512}
 ```

magic_hour/resources/v1/video_projects/__init__.py

@@ -1,4 +1,12 @@
-from .client import AsyncVideoProjectsClient, VideoProjectsClient
+from .client import (
+    AsyncVideoProjectsClient,
+    V1VideoProjectsGetResponseWithDownloads,
+    VideoProjectsClient,
+)
 
 
-__all__ = ["AsyncVideoProjectsClient", "VideoProjectsClient"]
+__all__ = [
+    "AsyncVideoProjectsClient",
+    "V1VideoProjectsGetResponseWithDownloads",
+    "VideoProjectsClient",
+]