magic_hour 0.29.0__tar.gz → 0.30.1__tar.gz

{magic_hour-0.29.0 → magic_hour-0.30.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: magic_hour
-Version: 0.29.0
+Version: 0.30.1
 Summary: Python SDK for Magic Hour API
 Requires-Python: >=3.8,<4.0
 Classifier: Programming Language :: Python :: 3
@@ -111,6 +111,11 @@ client = AsyncClient(token="my api key")
 
 * [create](magic_hour/resources/v1/auto_subtitle_generator/README.md#create) - Auto Subtitle Generator
 
+### [v1.face_detection](magic_hour/resources/v1/face_detection/README.md)
+
+* [create](magic_hour/resources/v1/face_detection/README.md#create) - Face Detection
+* [get](magic_hour/resources/v1/face_detection/README.md#get) - Get face detection details
+
 ### [v1.face_swap](magic_hour/resources/v1/face_swap/README.md)
 
 * [create](magic_hour/resources/v1/face_swap/README.md#create) - Face Swap video

{magic_hour-0.29.0 → magic_hour-0.30.1}/README.md

@@ -93,6 +93,11 @@ client = AsyncClient(token="my api key")
 
 * [create](magic_hour/resources/v1/auto_subtitle_generator/README.md#create) - Auto Subtitle Generator
 
+### [v1.face_detection](magic_hour/resources/v1/face_detection/README.md)
+
+* [create](magic_hour/resources/v1/face_detection/README.md#create) - Face Detection
+* [get](magic_hour/resources/v1/face_detection/README.md#get) - Get face detection details
+
 ### [v1.face_swap](magic_hour/resources/v1/face_swap/README.md)
 
 * [create](magic_hour/resources/v1/face_swap/README.md#create) - Face Swap video

{magic_hour-0.29.0 → magic_hour-0.30.1}/magic_hour/environment.py

@@ -6,7 +6,7 @@ class Environment(enum.Enum):
     """Pre-defined base URLs for the API"""
 
     ENVIRONMENT = "https://api.magichour.ai"
-    MOCK_SERVER = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.29.0"
+    MOCK_SERVER = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.30.1"
 
 
 def _get_base_url(

{magic_hour-0.29.0 → magic_hour-0.30.1}/magic_hour/resources/v1/client.py

@@ -48,6 +48,10 @@ from magic_hour.resources.v1.auto_subtitle_generator import (
     AsyncAutoSubtitleGeneratorClient,
     AutoSubtitleGeneratorClient,
 )
+from magic_hour.resources.v1.face_detection import (
+    AsyncFaceDetectionClient,
+    FaceDetectionClient,
+)
 from magic_hour.resources.v1.face_swap import AsyncFaceSwapClient, FaceSwapClient
 from magic_hour.resources.v1.face_swap_photo import (
     AsyncFaceSwapPhotoClient,
@@ -90,6 +94,7 @@ class V1Client:
         self._base_client = base_client
         self.image_projects = ImageProjectsClient(base_client=self._base_client)
         self.video_projects = VideoProjectsClient(base_client=self._base_client)
+        self.face_detection = FaceDetectionClient(base_client=self._base_client)
         self.ai_clothes_changer = AiClothesChangerClient(base_client=self._base_client)
         self.ai_face_editor = AiFaceEditorClient(base_client=self._base_client)
         self.ai_gif_generator = AiGifGeneratorClient(base_client=self._base_client)
@@ -127,6 +132,7 @@ class AsyncV1Client:
         self._base_client = base_client
         self.image_projects = AsyncImageProjectsClient(base_client=self._base_client)
         self.video_projects = AsyncVideoProjectsClient(base_client=self._base_client)
+        self.face_detection = AsyncFaceDetectionClient(base_client=self._base_client)
         self.ai_clothes_changer = AsyncAiClothesChangerClient(
             base_client=self._base_client
         )

magic_hour-0.30.1/magic_hour/resources/v1/face_detection/README.md

@@ -0,0 +1,91 @@
+
+### Get face detection details <a name="get"></a>
+
+Get the details of a face detection task.
+
+**API Endpoint**: `GET /v1/face-detection/{id}`
+
+#### Parameters
+
+| Parameter | Required | Description | Example |
+|-----------|:--------:|-------------|--------|
+| `id` | ✓ | The id of the task | `"string"` |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.face_detection.get(id="string")
+
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.face_detection.get(id="string")
+
+```
+
+#### Response
+
+##### Type
+[V1FaceDetectionGetResponse](/magic_hour/types/models/v1_face_detection_get_response.py)
+
+##### Example
+`{"credits_charged": 123, "faces": [{"path": "api-assets/id/0-0.png", "url": "https://videos.magichour.ai/api-assets/id/0-0.png"}], "id": "string", "status": "complete"}`
+
+### Face Detection <a name="create"></a>
+
+Detect faces in an image or video. 
+
+Note: Face detection is free to use for the near future. Pricing may change in the future.
+
+**API Endpoint**: `POST /v1/face-detection`
+
+#### Parameters
+
+| Parameter | Required | Description | Example |
+|-----------|:--------:|-------------|--------|
+| `assets` | ✓ | Provide the assets for face detection | `{"target_file_path": "api-assets/id/1234.png"}` |
+| `confidence_score` | ✗ | Confidence threshold for filtering detected faces.  * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.  * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections. | `0.5` |
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.face_detection.create(
+    assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+)
+
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.face_detection.create(
+    assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+)
+
+```
+
+#### Response
+
+##### Type
+[V1FaceDetectionCreateResponse](/magic_hour/types/models/v1_face_detection_create_response.py)
+
+##### Example
+`{"credits_charged": 123, "id": "string"}`

magic_hour-0.30.1/magic_hour/resources/v1/face_detection/__init__.py

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

magic_hour-0.30.1/magic_hour/resources/v1/face_detection/client.py

@@ -0,0 +1,193 @@
+import typing
+
+from magic_hour.core import (
+    AsyncBaseClient,
+    RequestOptions,
+    SyncBaseClient,
+    default_request_options,
+    to_encodable,
+    type_utils,
+)
+from magic_hour.types import models, params
+
+
+class FaceDetectionClient:
+    def __init__(self, *, base_client: SyncBaseClient):
+        self._base_client = base_client
+
+    def get(
+        self, *, id: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> models.V1FaceDetectionGetResponse:
+        """
+        Get face detection details
+
+        Get the details of a face detection task.
+
+        GET /v1/face-detection/{id}
+
+        Args:
+            id: The id of the task
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        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.face_detection.get(id="string")
+        ```
+        """
+        return self._base_client.request(
+            method="GET",
+            path=f"/v1/face-detection/{id}",
+            auth_names=["bearerAuth"],
+            cast_to=models.V1FaceDetectionGetResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+    def create(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1FaceDetectionCreateResponse:
+        """
+        Face Detection
+
+        Detect faces in an image or video.
+
+        Note: Face detection is free to use for the near future. Pricing may change in the future.
+
+        POST /v1/face-detection
+
+        Args:
+            confidence_score: Confidence threshold for filtering detected faces.
+        * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.
+        * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
+            assets: Provide the assets for face detection
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        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.face_detection.create(
+            assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"confidence_score": confidence_score, "assets": assets},
+            dump_with=params._SerializerV1FaceDetectionCreateBody,
+        )
+        return self._base_client.request(
+            method="POST",
+            path="/v1/face-detection",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1FaceDetectionCreateResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+
+class AsyncFaceDetectionClient:
+    def __init__(self, *, base_client: AsyncBaseClient):
+        self._base_client = base_client
+
+    async def get(
+        self, *, id: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> models.V1FaceDetectionGetResponse:
+        """
+        Get face detection details
+
+        Get the details of a face detection task.
+
+        GET /v1/face-detection/{id}
+
+        Args:
+            id: The id of the task
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        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.face_detection.get(id="string")
+        ```
+        """
+        return await self._base_client.request(
+            method="GET",
+            path=f"/v1/face-detection/{id}",
+            auth_names=["bearerAuth"],
+            cast_to=models.V1FaceDetectionGetResponse,
+            request_options=request_options or default_request_options(),
+        )
+
+    async def create(
+        self,
+        *,
+        assets: params.V1FaceDetectionCreateBodyAssets,
+        confidence_score: typing.Union[
+            typing.Optional[float], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> models.V1FaceDetectionCreateResponse:
+        """
+        Face Detection
+
+        Detect faces in an image or video.
+
+        Note: Face detection is free to use for the near future. Pricing may change in the future.
+
+        POST /v1/face-detection
+
+        Args:
+            confidence_score: Confidence threshold for filtering detected faces.
+        * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.
+        * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
+            assets: Provide the assets for face detection
+            request_options: Additional options to customize the HTTP request
+
+        Returns:
+            200
+
+        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.face_detection.create(
+            assets={"target_file_path": "api-assets/id/1234.png"}, confidence_score=0.5
+        )
+        ```
+        """
+        _json = to_encodable(
+            item={"confidence_score": confidence_score, "assets": assets},
+            dump_with=params._SerializerV1FaceDetectionCreateBody,
+        )
+        return await self._base_client.request(
+            method="POST",
+            path="/v1/face-detection",
+            auth_names=["bearerAuth"],
+            json=_json,
+            cast_to=models.V1FaceDetectionCreateResponse,
+            request_options=request_options or default_request_options(),
+        )

{magic_hour-0.29.0 → magic_hour-0.30.1}/magic_hour/types/models/__init__.py

@@ -15,6 +15,11 @@ from .v1_animation_create_response import V1AnimationCreateResponse
 from .v1_auto_subtitle_generator_create_response import (
     V1AutoSubtitleGeneratorCreateResponse,
 )
+from .v1_face_detection_create_response import V1FaceDetectionCreateResponse
+from .v1_face_detection_get_response import V1FaceDetectionGetResponse
+from .v1_face_detection_get_response_faces_item import (
+    V1FaceDetectionGetResponseFacesItem,
+)
 from .v1_face_swap_create_response import V1FaceSwapCreateResponse
 from .v1_face_swap_photo_create_response import V1FaceSwapPhotoCreateResponse
 from .v1_files_upload_urls_create_response import V1FilesUploadUrlsCreateResponse
@@ -56,6 +61,9 @@ __all__ = [
     "V1AiTalkingPhotoCreateResponse",
     "V1AnimationCreateResponse",
     "V1AutoSubtitleGeneratorCreateResponse",
+    "V1FaceDetectionCreateResponse",
+    "V1FaceDetectionGetResponse",
+    "V1FaceDetectionGetResponseFacesItem",
     "V1FaceSwapCreateResponse",
     "V1FaceSwapPhotoCreateResponse",
     "V1FilesUploadUrlsCreateResponse",

magic_hour-0.30.1/magic_hour/types/models/v1_face_detection_create_response.py

@@ -0,0 +1,25 @@
+import pydantic
+
+
+class V1FaceDetectionCreateResponse(pydantic.BaseModel):
+    """
+    V1FaceDetectionCreateResponse
+    """
+
+    model_config = pydantic.ConfigDict(
+        arbitrary_types_allowed=True,
+        populate_by_name=True,
+    )
+
+    credits_charged: int = pydantic.Field(
+        alias="credits_charged",
+    )
+    """
+    The credits charged for the task.
+    """
+    id: str = pydantic.Field(
+        alias="id",
+    )
+    """
+    The id of the task
+    """

magic_hour-0.30.1/magic_hour/types/models/v1_face_detection_get_response.py

@@ -0,0 +1,45 @@
+import pydantic
+import typing
+import typing_extensions
+
+from .v1_face_detection_get_response_faces_item import (
+    V1FaceDetectionGetResponseFacesItem,
+)
+
+
+class V1FaceDetectionGetResponse(pydantic.BaseModel):
+    """
+    V1FaceDetectionGetResponse
+    """
+
+    model_config = pydantic.ConfigDict(
+        arbitrary_types_allowed=True,
+        populate_by_name=True,
+    )
+
+    credits_charged: int = pydantic.Field(
+        alias="credits_charged",
+    )
+    """
+    The credits charged for the task.
+    """
+    faces: typing.List[V1FaceDetectionGetResponseFacesItem] = pydantic.Field(
+        alias="faces",
+    )
+    """
+    The faces detected in the image or video. The list is populated as faces are detected.
+    """
+    id: str = pydantic.Field(
+        alias="id",
+    )
+    """
+    The id of the task
+    """
+    status: typing_extensions.Literal["complete", "error", "queued", "rendering"] = (
+        pydantic.Field(
+            alias="status",
+        )
+    )
+    """
+    The status of the detection.
+    """

magic_hour-0.30.1/magic_hour/types/models/v1_face_detection_get_response_faces_item.py

@@ -0,0 +1,25 @@
+import pydantic
+
+
+class V1FaceDetectionGetResponseFacesItem(pydantic.BaseModel):
+    """
+    V1FaceDetectionGetResponseFacesItem
+    """
+
+    model_config = pydantic.ConfigDict(
+        arbitrary_types_allowed=True,
+        populate_by_name=True,
+    )
+
+    path: str = pydantic.Field(
+        alias="path",
+    )
+    """
+    The path to the face image. This should be used in face swap photo/video API calls as `.assets.face_mappings.original_face`
+    """
+    url: str = pydantic.Field(
+        alias="url",
+    )
+    """
+    The url to the face image. This is used to render the image in your applications.
+    """

{magic_hour-0.29.0 → magic_hour-0.30.1}/magic_hour/types/params/__init__.py

@@ -138,6 +138,14 @@ from .v1_auto_subtitle_generator_create_body_style_custom_config import (
     V1AutoSubtitleGeneratorCreateBodyStyleCustomConfig,
     _SerializerV1AutoSubtitleGeneratorCreateBodyStyleCustomConfig,
 )
+from .v1_face_detection_create_body import (
+    V1FaceDetectionCreateBody,
+    _SerializerV1FaceDetectionCreateBody,
+)
+from .v1_face_detection_create_body_assets import (
+    V1FaceDetectionCreateBodyAssets,
+    _SerializerV1FaceDetectionCreateBodyAssets,
+)
 from .v1_face_swap_create_body import (
     V1FaceSwapCreateBody,
     _SerializerV1FaceSwapCreateBody,
@@ -257,6 +265,8 @@ __all__ = [
     "V1AutoSubtitleGeneratorCreateBodyAssets",
     "V1AutoSubtitleGeneratorCreateBodyStyle",
     "V1AutoSubtitleGeneratorCreateBodyStyleCustomConfig",
+    "V1FaceDetectionCreateBody",
+    "V1FaceDetectionCreateBodyAssets",
     "V1FaceSwapCreateBody",
     "V1FaceSwapCreateBodyAssets",
     "V1FaceSwapPhotoCreateBody",
@@ -313,6 +323,8 @@ __all__ = [
     "_SerializerV1AutoSubtitleGeneratorCreateBodyAssets",
     "_SerializerV1AutoSubtitleGeneratorCreateBodyStyle",
     "_SerializerV1AutoSubtitleGeneratorCreateBodyStyleCustomConfig",
+    "_SerializerV1FaceDetectionCreateBody",
+    "_SerializerV1FaceDetectionCreateBodyAssets",
     "_SerializerV1FaceSwapCreateBody",
     "_SerializerV1FaceSwapCreateBodyAssets",
     "_SerializerV1FaceSwapPhotoCreateBody",

magic_hour-0.30.1/magic_hour/types/params/v1_face_detection_create_body.py

@@ -0,0 +1,44 @@
+import pydantic
+import typing
+import typing_extensions
+
+from .v1_face_detection_create_body_assets import (
+    V1FaceDetectionCreateBodyAssets,
+    _SerializerV1FaceDetectionCreateBodyAssets,
+)
+
+
+class V1FaceDetectionCreateBody(typing_extensions.TypedDict):
+    """
+    V1FaceDetectionCreateBody
+    """
+
+    assets: typing_extensions.Required[V1FaceDetectionCreateBodyAssets]
+    """
+    Provide the assets for face detection
+    """
+
+    confidence_score: typing_extensions.NotRequired[float]
+    """
+    Confidence threshold for filtering detected faces. 
+    * Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives. 
+    * Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.
+    """
+
+
+class _SerializerV1FaceDetectionCreateBody(pydantic.BaseModel):
+    """
+    Serializer for V1FaceDetectionCreateBody handling case conversions
+    and file omissions as dictated by the API
+    """
+
+    model_config = pydantic.ConfigDict(
+        populate_by_name=True,
+    )
+
+    assets: _SerializerV1FaceDetectionCreateBodyAssets = pydantic.Field(
+        alias="assets",
+    )
+    confidence_score: typing.Optional[float] = pydantic.Field(
+        alias="confidence_score", default=None
+    )

magic_hour-0.30.1/magic_hour/types/params/v1_face_detection_create_body_assets.py

@@ -0,0 +1,28 @@
+import pydantic
+import typing_extensions
+
+
+class V1FaceDetectionCreateBodyAssets(typing_extensions.TypedDict):
+    """
+    Provide the assets for face detection
+    """
+
+    target_file_path: typing_extensions.Required[str]
+    """
+    This is the image or video where the face will be detected. This value can be either the `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls), or the url of the file.
+    """
+
+
+class _SerializerV1FaceDetectionCreateBodyAssets(pydantic.BaseModel):
+    """
+    Serializer for V1FaceDetectionCreateBodyAssets handling case conversions
+    and file omissions as dictated by the API
+    """
+
+    model_config = pydantic.ConfigDict(
+        populate_by_name=True,
+    )
+
+    target_file_path: str = pydantic.Field(
+        alias="target_file_path",
+    )

{magic_hour-0.29.0 → magic_hour-0.30.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "magic_hour"
-version = "0.29.0"
+version = "0.30.1"
 description = "Python SDK for Magic Hour API"
 readme = "README.md"
 authors = []