feat: add generation mode to lip sync API, update default for talking photo to pro (#99)

magic-hour-sdk-bot[bot] · sdk-github-actions[bot] · davidhu2000 · web-flow · commit 76c473c8a0de · 2025-09-20T10:25:56.000-07:00
Co-authored-by: sdk-github-actions[bot] &lt;sdk-github-actions[bot]@users.noreply.github.com&gt;
Co-authored-by: David Hu &lt;davidhu314@gmail.com&gt;
diff --git a/.sdk.json b/.sdk.json
@@ -1,5 +1,5 @@
 {
-  "id": "7b8b55a1-18db-45f0-b4c3-6334ece8200a",
+  "id": "46c80140-0884-493b-9bb6-6209cc50d3ee",
   "tracked_paths": [
     {
       "editable": true,
@@ -745,6 +745,10 @@
       "editable": false,
       "path": "magic_hour/types/params/v1_lip_sync_create_body_assets.py"
     },
+    {
+      "editable": false,
+      "path": "magic_hour/types/params/v1_lip_sync_create_body_style.py"
+    },
     {
       "editable": false,
       "path": "magic_hour/types/params/v1_photo_colorizer_create_body.py"
diff --git a/magic_hour/environment.py b/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.40.0"
+    MOCK_SERVER = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.41.0"
 
 
 def _get_base_url(
diff --git a/magic_hour/resources/v1/ai_clothes_changer/README.md b/magic_hour/resources/v1/ai_clothes_changer/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### AI Clothes Changer Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_face_editor/README.md b/magic_hour/resources/v1/ai_face_editor/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Face Editor Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_gif_generator/README.md b/magic_hour/resources/v1/ai_gif_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Gif Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_headshot_generator/README.md b/magic_hour/resources/v1/ai_headshot_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Headshot Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_image_editor/README.md b/magic_hour/resources/v1/ai_image_editor/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Image Editor Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_image_generator/README.md b/magic_hour/resources/v1/ai_image_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Image Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_image_upscaler/README.md b/magic_hour/resources/v1/ai_image_upscaler/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Image Upscaler Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_meme_generator/README.md b/magic_hour/resources/v1/ai_meme_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Meme Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_photo_editor/README.md b/magic_hour/resources/v1/ai_photo_editor/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Photo Editor Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_qr_code_generator/README.md b/magic_hour/resources/v1/ai_qr_code_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Qr Code Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/ai_talking_photo/README.md b/magic_hour/resources/v1/ai_talking_photo/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Ai Talking Photo Generate Workflow <a name="generate"></a>
@@ -85,8 +86,8 @@ Create a talking photo from an image and audio or text input.
 | `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": "expressive", "intensity": 1.5}` |
-| `└─ generation_mode` | ✗ | Controls overall motion style. * `pro` -  Realistic, high fidelity, accurate lip sync, slower. * `expressive` - More motion and facial expressiveness; may introduce visual artifacts. * `stable` -  Reduced motion for cleaner output; may result in minimal animation. (Deprecated: passing this value will be treated as `pro`) | `"expressive"` |
+| `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
diff --git a/magic_hour/resources/v1/animation/README.md b/magic_hour/resources/v1/animation/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Animation Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/auto_subtitle_generator/README.md b/magic_hour/resources/v1/auto_subtitle_generator/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Auto Subtitle Generator Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/face_detection/README.md b/magic_hour/resources/v1/face_detection/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Face Detection Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/face_swap/README.md b/magic_hour/resources/v1/face_swap/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Face Swap Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/face_swap_photo/README.md b/magic_hour/resources/v1/face_swap_photo/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Face Swap Photo Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/files/README.md b/magic_hour/resources/v1/files/README.md
@@ -2,6 +2,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Upload File <a name="upload-file"></a>
diff --git a/magic_hour/resources/v1/image_background_remover/README.md b/magic_hour/resources/v1/image_background_remover/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Image Background Remover Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/image_projects/README.md b/magic_hour/resources/v1/image_projects/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Check results <a name="check-result"></a>
diff --git a/magic_hour/resources/v1/image_to_video/README.md b/magic_hour/resources/v1/image_to_video/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Image To Video Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/lip_sync/README.md b/magic_hour/resources/v1/lip_sync/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Lip Sync Generate Workflow <a name="generate"></a>
@@ -96,6 +97,8 @@ Get more information about this mode at our [product page](https://magichour.ai/
 | `height` | ✗ | ✓ | `height` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
 | `max_fps_limit` | ✗ | ✗ | Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required. | `12.0` |
 | `name` | ✗ | ✗ | The name of video. This value is mainly used for your own identification of the video. | `"Lip Sync video"` |
+| `style` | ✗ | ✗ | Attributes used to dictate the style of the output | `{"generation_mode": "lite"}` |
+| `└─ generation_mode` | ✗ | — | A specific version of our lip sync system, optimized for different needs. * `lite` -  Fast and affordable lip sync - best for simple videos. Costs 1 credit per frame of video. * `standard` -  Natural, accurate lip sync - best for most creators. Costs 1 credit per frame of video. * `pro` -  Premium fidelity with enhanced detail - best for professionals. Costs 2 credits per frame of video.  Note: `standard` and `pro` are only available for users on Creator, Pro, and Business tiers.                | `"lite"` |
 | `width` | ✗ | ✓ | `width` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
 
 #### Synchronous Client
diff --git a/magic_hour/resources/v1/lip_sync/client.py b/magic_hour/resources/v1/lip_sync/client.py
@@ -138,6 +138,9 @@ def create(
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1LipSyncCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
         width: typing.Union[
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -163,6 +166,7 @@ def create(
         This field is retained only for backward compatibility and will be removed in a future release.
             max_fps_limit: Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required.
             name: The name of video. This value is mainly used for your own identification of the video.
+            style: Attributes used to dictate the style of the output
             width: `width` is deprecated and no longer influences the output video's resolution.
 
         Output resolution is determined by the **minimum** of:
@@ -202,6 +206,7 @@ def create(
                 "height": height,
                 "max_fps_limit": max_fps_limit,
                 "name": name,
+                "style": style,
                 "width": width,
                 "assets": assets,
                 "end_seconds": end_seconds,
@@ -339,6 +344,9 @@ async def create(
         name: typing.Union[
             typing.Optional[str], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
+        style: typing.Union[
+            typing.Optional[params.V1LipSyncCreateBodyStyle], type_utils.NotGiven
+        ] = type_utils.NOT_GIVEN,
         width: typing.Union[
             typing.Optional[int], type_utils.NotGiven
         ] = type_utils.NOT_GIVEN,
@@ -364,6 +372,7 @@ async def create(
         This field is retained only for backward compatibility and will be removed in a future release.
             max_fps_limit: Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required.
             name: The name of video. This value is mainly used for your own identification of the video.
+            style: Attributes used to dictate the style of the output
             width: `width` is deprecated and no longer influences the output video's resolution.
 
         Output resolution is determined by the **minimum** of:
@@ -403,6 +412,7 @@ async def create(
                 "height": height,
                 "max_fps_limit": max_fps_limit,
                 "name": name,
+                "style": style,
                 "width": width,
                 "assets": assets,
                 "end_seconds": end_seconds,
diff --git a/magic_hour/resources/v1/photo_colorizer/README.md b/magic_hour/resources/v1/photo_colorizer/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Photo Colorizer Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/text_to_video/README.md b/magic_hour/resources/v1/text_to_video/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Text To Video Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/resources/v1/video_projects/README.md b/magic_hour/resources/v1/video_projects/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Check results <a name="check-result"></a>
diff --git a/magic_hour/resources/v1/video_to_video/README.md b/magic_hour/resources/v1/video_to_video/README.md
@@ -4,6 +4,7 @@
 
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Video To Video Generate Workflow <a name="generate"></a>
diff --git a/magic_hour/types/models/v1_audio_projects_get_response.py b/magic_hour/types/models/v1_audio_projects_get_response.py
@@ -68,5 +68,5 @@ class V1AudioProjectsGetResponse(pydantic.BaseModel):
         alias="type",
     )
     """
-    The type of the audio project. Possible values are VOICE_GENERATOR
+    The type of the audio project. Possible values are VOICE_GENERATOR, VOICE_CHANGER
     """
diff --git a/magic_hour/types/params/__init__.py b/magic_hour/types/params/__init__.py
@@ -245,6 +245,10 @@
     V1LipSyncCreateBodyAssets,
     _SerializerV1LipSyncCreateBodyAssets,
 )
+from .v1_lip_sync_create_body_style import (
+    V1LipSyncCreateBodyStyle,
+    _SerializerV1LipSyncCreateBodyStyle,
+)
 from .v1_lip_sync_generate_body_assets import V1LipSyncGenerateBodyAssets
 from .v1_photo_colorizer_create_body import (
     V1PhotoColorizerCreateBody,
@@ -350,6 +354,7 @@
     "V1ImageToVideoGenerateBodyAssets",
     "V1LipSyncCreateBody",
     "V1LipSyncCreateBodyAssets",
+    "V1LipSyncCreateBodyStyle",
     "V1LipSyncGenerateBodyAssets",
     "V1PhotoColorizerCreateBody",
     "V1PhotoColorizerCreateBodyAssets",
@@ -415,6 +420,7 @@
     "_SerializerV1ImageToVideoCreateBodyStyle",
     "_SerializerV1LipSyncCreateBody",
     "_SerializerV1LipSyncCreateBodyAssets",
+    "_SerializerV1LipSyncCreateBodyStyle",
     "_SerializerV1PhotoColorizerCreateBody",
     "_SerializerV1PhotoColorizerCreateBodyAssets",
     "_SerializerV1TextToVideoCreateBody",
diff --git a/magic_hour/types/params/v1_ai_talking_photo_create_body_style.py b/magic_hour/types/params/v1_ai_talking_photo_create_body_style.py
@@ -9,12 +9,14 @@ class V1AiTalkingPhotoCreateBodyStyle(typing_extensions.TypedDict):
     """
 
     generation_mode: typing_extensions.NotRequired[
-        typing_extensions.Literal["expressive", "pro", "stable"]
+        typing_extensions.Literal["expressive", "pro", "stable", "standard"]
     ]
     """
     Controls overall motion style.
-    * `pro` -  Realistic, high fidelity, accurate lip sync, slower.
-    * `expressive` - More motion and facial expressiveness; may introduce visual artifacts.
+    * `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`)
     """
 
@@ -37,6 +39,6 @@ class _SerializerV1AiTalkingPhotoCreateBodyStyle(pydantic.BaseModel):
     )
 
     generation_mode: typing.Optional[
-        typing_extensions.Literal["expressive", "pro", "stable"]
+        typing_extensions.Literal["expressive", "pro", "stable", "standard"]
     ] = pydantic.Field(alias="generation_mode", default=None)
     intensity: typing.Optional[float] = pydantic.Field(alias="intensity", default=None)
diff --git a/magic_hour/types/params/v1_lip_sync_create_body.py b/magic_hour/types/params/v1_lip_sync_create_body.py
@@ -6,6 +6,10 @@
     V1LipSyncCreateBodyAssets,
     _SerializerV1LipSyncCreateBodyAssets,
 )
+from .v1_lip_sync_create_body_style import (
+    V1LipSyncCreateBodyStyle,
+    _SerializerV1LipSyncCreateBodyStyle,
+)
 
 
 class V1LipSyncCreateBody(typing_extensions.TypedDict):
@@ -49,6 +53,11 @@ class V1LipSyncCreateBody(typing_extensions.TypedDict):
     The start time of the input video in seconds. This value is used to trim the input video. The value must be greater than 0.
     """
 
+    style: typing_extensions.NotRequired[V1LipSyncCreateBodyStyle]
+    """
+    Attributes used to dictate the style of the output
+    """
+
     width: typing_extensions.NotRequired[typing.Optional[int]]
     """
     `width` is deprecated and no longer influences the output video's resolution.
@@ -85,4 +94,7 @@ class _SerializerV1LipSyncCreateBody(pydantic.BaseModel):
     start_seconds: float = pydantic.Field(
         alias="start_seconds",
     )
+    style: typing.Optional[_SerializerV1LipSyncCreateBodyStyle] = pydantic.Field(
+        alias="style", default=None
+    )
     width: typing.Optional[int] = pydantic.Field(alias="width", default=None)
diff --git a/magic_hour/types/params/v1_lip_sync_create_body_style.py b/magic_hour/types/params/v1_lip_sync_create_body_style.py
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tests/test_v1_ai_talking_photo_client.py b/tests/test_v1_ai_talking_photo_client.py
diff --git a/tests/test_v1_lip_sync_client.py b/tests/test_v1_lip_sync_client.py

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "id": "7b8b55a1-18db-45f0-b4c3-6334ece8200a",`
	`2`	`+ "id": "46c80140-0884-493b-9bb6-6209cc50d3ee",`
`3`	`3`	`"tracked_paths": [`
`4`	`4`	`{`
`5`	`5`	`"editable": true,`
`@@ -745,6 +745,10 @@`
`745`	`745`	`"editable": false,`
`746`	`746`	`"path": "magic_hour/types/params/v1_lip_sync_create_body_assets.py"`
`747`	`747`	`},`
	`748`	`+ {`
	`749`	`+ "editable": false,`
	`750`	`+ "path": "magic_hour/types/params/v1_lip_sync_create_body_style.py"`
	`751`	`+ },`
`748`	`752`	`{`
`749`	`753`	`"editable": false,`
`750`	`754`	`"path": "magic_hour/types/params/v1_photo_colorizer_create_body.py"`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`
`5`	`5`
`6`	`6`
	`7`	`+`
`7`	`8`	`<!-- CUSTOM DOCS START -->`
`8`	`9`
`9`	`10`	`### AI Clothes Changer Generate Workflow <a name="generate"></a>`