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

magic-hour-sdk-bot[bot] · sdk-github-actions[bot] · davidhu2000 · web-flow · commit c0b4a888a348 · 2025-09-20T12:19:21.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": "efe25d79-fd74-485d-ab71-dbbcd9d68b8d",
+  "id": "31df0519-cea5-43da-929f-50f1bfbc429b",
   "tracked_paths": [
     {
       "editable": true,
@@ -941,6 +941,14 @@
       "editable": false,
       "path": "src/types/v1-lip-sync-create-body-assets.ts"
     },
+    {
+      "editable": false,
+      "path": "src/types/v1-lip-sync-create-body-style-generation-mode-enum.ts"
+    },
+    {
+      "editable": false,
+      "path": "src/types/v1-lip-sync-create-body-style.ts"
+    },
     {
       "editable": false,
       "path": "src/types/v1-lip-sync-create-body.ts"
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "magic-hour",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
diff --git a/src/environment.ts b/src/environment.ts
@@ -1,4 +1,4 @@
 export enum Environment {
   Environment = "https://api.magichour.ai",
-  MockServer = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.40.0",
+  MockServer = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.41.0",
 }
diff --git a/src/resources/v1/ai-clothes-changer/README.md b/src/resources/v1/ai-clothes-changer/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Clothes Changer Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-face-editor/README.md b/src/resources/v1/ai-face-editor/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Face Editor Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-gif-generator/README.md b/src/resources/v1/ai-gif-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Gif Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-headshot-generator/README.md b/src/resources/v1/ai-headshot-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Headshot Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-image-editor/README.md b/src/resources/v1/ai-image-editor/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Image Editor Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-image-generator/README.md b/src/resources/v1/ai-image-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Image Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-image-upscaler/README.md b/src/resources/v1/ai-image-upscaler/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Image Upscaler Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-meme-generator/README.md b/src/resources/v1/ai-meme-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Meme Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-photo-editor/README.md b/src/resources/v1/ai-photo-editor/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Photo Editor Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-qr-code-generator/README.md b/src/resources/v1/ai-qr-code-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Qr Code Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/ai-talking-photo/README.md b/src/resources/v1/ai-talking-photo/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### AI Talking Photo Generate Workflow <a name="generate"></a>
 
@@ -66,8 +67,8 @@ Create a talking photo from an image and audio or text input.
 | `endSeconds` | ✓ | The end time of the input audio in seconds. The maximum duration allowed is 60 seconds. | `15.0` |
 | `startSeconds` | ✓ | 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 | `{"generationMode": "expressive", "intensity": 1.5}` |
-| `└─ generationMode` | ✗ | 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 | `{"generationMode": "pro", "intensity": 1.5}` |
+| `└─ generationMode` | ✗ | 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` |
 
 #### Example Snippet
diff --git a/src/resources/v1/animation/README.md b/src/resources/v1/animation/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Animation Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/auto-subtitle-generator/README.md b/src/resources/v1/auto-subtitle-generator/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Auto Subtitle Generator Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/face-detection/README.md b/src/resources/v1/face-detection/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Face Detection Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/face-swap-photo/README.md b/src/resources/v1/face-swap-photo/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Face Swap Photo Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/face-swap/README.md b/src/resources/v1/face-swap/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Face Swap Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/files/README.md b/src/resources/v1/files/README.md
@@ -1,6 +1,7 @@
 # v1.files
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Upload File <a name="upload-file"></a>
diff --git a/src/resources/v1/image-background-remover/README.md b/src/resources/v1/image-background-remover/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Image Background Remover Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/image-projects/README.md b/src/resources/v1/image-projects/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Check results <a name="check-result"></a>
diff --git a/src/resources/v1/image-to-video/README.md b/src/resources/v1/image-to-video/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Image To Video Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/lip-sync/README.md b/src/resources/v1/lip-sync/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Lip Sync Generate Workflow <a name="generate"></a>
 
@@ -75,6 +76,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` |
 | `maxFpsLimit` | ✗ | ✗ | 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 | `{"generationMode": "lite"}` |
+| `└─ generationMode` | ✗ | — | 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` |
 
 #### Example Snippet
diff --git a/src/resources/v1/lip-sync/request-types.ts b/src/resources/v1/lip-sync/request-types.ts
@@ -6,6 +6,11 @@ import {
   Schemas$V1LipSyncCreateBodyAssets,
   V1LipSyncCreateBodyAssets,
 } from "magic-hour/types/v1-lip-sync-create-body-assets";
+import {
+  External$V1LipSyncCreateBodyStyle,
+  Schemas$V1LipSyncCreateBodyStyle,
+  V1LipSyncCreateBodyStyle,
+} from "magic-hour/types/v1-lip-sync-create-body-style";
 
 /**
  * CreateRequest
@@ -41,6 +46,10 @@ export type CreateRequest = {
    * 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.
    */
   startSeconds: number;
+  /**
+   * Attributes used to dictate the style of the output
+   */
+  style?: V1LipSyncCreateBodyStyle | undefined;
   /**
    * `width` is deprecated and no longer influences the output video's resolution.
    *
@@ -65,6 +74,7 @@ export type External$CreateRequest = {
   max_fps_limit?: number | undefined;
   name?: string | undefined;
   start_seconds: number;
+  style?: External$V1LipSyncCreateBodyStyle | undefined;
   width?: number | null | undefined;
 };
 
@@ -83,6 +93,7 @@ const SchemaIn$CreateRequest: z.ZodType<
     max_fps_limit: z.number().optional(),
     name: z.string().optional(),
     start_seconds: z.number(),
+    style: Schemas$V1LipSyncCreateBodyStyle.in.optional(),
     width: z.number().int().nullable().optional(),
   })
   .transform((obj) => {
@@ -93,6 +104,7 @@ const SchemaIn$CreateRequest: z.ZodType<
       max_fps_limit: "maxFpsLimit",
       name: "name",
       start_seconds: "startSeconds",
+      style: "style",
       width: "width",
     });
   });
@@ -113,6 +125,7 @@ const SchemaOut$CreateRequest: z.ZodType<
     maxFpsLimit: z.number().optional(),
     name: z.string().optional(),
     startSeconds: z.number(),
+    style: Schemas$V1LipSyncCreateBodyStyle.out.optional(),
     width: z.number().int().nullable().optional(),
   })
   .transform((obj) => {
@@ -123,6 +136,7 @@ const SchemaOut$CreateRequest: z.ZodType<
       maxFpsLimit: "max_fps_limit",
       name: "name",
       startSeconds: "start_seconds",
+      style: "style",
       width: "width",
     });
   });
diff --git a/src/resources/v1/photo-colorizer/README.md b/src/resources/v1/photo-colorizer/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Photo Colorizer Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/text-to-video/README.md b/src/resources/v1/text-to-video/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Text To Video Generate Workflow <a name="generate"></a>
 
diff --git a/src/resources/v1/video-projects/README.md b/src/resources/v1/video-projects/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 
 ### Check results <a name="check-result"></a>
diff --git a/src/resources/v1/video-to-video/README.md b/src/resources/v1/video-to-video/README.md
@@ -3,6 +3,7 @@
 ## Module Functions
 
 
+
 <!-- CUSTOM DOCS START -->
 ### Video To Video Generate Workflow <a name="generate"></a>
 
diff --git a/src/types/index.ts b/src/types/index.ts
@@ -106,6 +106,8 @@ export { V1ImageToVideoCreateResponse } from "./v1-image-to-video-create-respons
 export { V1LipSyncCreateBody } from "./v1-lip-sync-create-body";
 export { V1LipSyncCreateBodyAssets } from "./v1-lip-sync-create-body-assets";
 export { V1LipSyncCreateBodyAssetsVideoSourceEnum } from "./v1-lip-sync-create-body-assets-video-source-enum";
+export { V1LipSyncCreateBodyStyle } from "./v1-lip-sync-create-body-style";
+export { V1LipSyncCreateBodyStyleGenerationModeEnum } from "./v1-lip-sync-create-body-style-generation-mode-enum";
 export { V1LipSyncCreateResponse } from "./v1-lip-sync-create-response";
 export { V1PhotoColorizerCreateBody } from "./v1-photo-colorizer-create-body";
 export { V1PhotoColorizerCreateBodyAssets } from "./v1-photo-colorizer-create-body-assets";
diff --git a/src/types/v1-ai-talking-photo-create-body-style-generation-mode-enum.ts b/src/types/v1-ai-talking-photo-create-body-style-generation-mode-enum.ts
@@ -1,10 +1,13 @@
 /**
  * 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`)
  */
 export type V1AiTalkingPhotoCreateBodyStyleGenerationModeEnum =
   | "expressive"
   | "pro"
-  | "stable";
+  | "stable"
+  | "standard";
diff --git a/src/types/v1-ai-talking-photo-create-body-style.ts b/src/types/v1-ai-talking-photo-create-body-style.ts
@@ -7,11 +7,13 @@ import * as z from "zod";
 export type V1AiTalkingPhotoCreateBodyStyle = {
   /**
    * 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`)
    */
-  generationMode?: ("expressive" | "pro" | "stable") | undefined;
+  generationMode?: ("expressive" | "pro" | "stable" | "standard") | undefined;
   /**
    * 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.
@@ -26,7 +28,7 @@ export type V1AiTalkingPhotoCreateBodyStyle = {
  * we expect to come in as network data
  */
 export type External$V1AiTalkingPhotoCreateBodyStyle = {
-  generation_mode?: ("expressive" | "pro" | "stable") | undefined;
+  generation_mode?: ("expressive" | "pro" | "stable" | "standard") | undefined;
   intensity?: number | undefined;
 };
 
@@ -39,7 +41,9 @@ const SchemaIn$V1AiTalkingPhotoCreateBodyStyle: z.ZodType<
   unknown
 > = z
   .object({
-    generation_mode: z.enum(["expressive", "pro", "stable"]).optional(),
+    generation_mode: z
+      .enum(["expressive", "pro", "stable", "standard"])
+      .optional(),
     intensity: z.number().optional(),
   })
   .transform((obj) => {
@@ -59,7 +63,9 @@ const SchemaOut$V1AiTalkingPhotoCreateBodyStyle: z.ZodType<
   V1AiTalkingPhotoCreateBodyStyle // the object to be transformed
 > = z
   .object({
-    generationMode: z.enum(["expressive", "pro", "stable"]).optional(),
+    generationMode: z
+      .enum(["expressive", "pro", "stable", "standard"])
+      .optional(),
     intensity: z.number().optional(),
   })
   .transform((obj) => {
diff --git a/src/types/v1-audio-projects-get-response.ts b/src/types/v1-audio-projects-get-response.ts
diff --git a/src/types/v1-lip-sync-create-body-style-generation-mode-enum.ts b/src/types/v1-lip-sync-create-body-style-generation-mode-enum.ts
diff --git a/src/types/v1-lip-sync-create-body-style.ts b/src/types/v1-lip-sync-create-body-style.ts
diff --git a/src/types/v1-lip-sync-create-body.ts b/src/types/v1-lip-sync-create-body.ts
diff --git a/test/v1-ai-talking-photo.test.ts b/test/v1-ai-talking-photo.test.ts
diff --git a/test/v1-lip-sync.test.ts b/test/v1-lip-sync.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "magic-hour",`
`3`		`- "version": "0.40.0",`
	`3`	`+ "version": "0.41.0",`
`4`	`4`	`"main": "./dist/index.js",`
`5`	`5`	`"types": "./dist/index.d.ts",`
`6`	`6`	`"exports": {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`export enum Environment {`
`2`	`2`	`Environment = "https://api.magichour.ai",`
`3`		`- MockServer = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.40.0",`
	`3`	`+ MockServer = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.41.0",`
`4`	`4`	`}`