samsar-js 0.48.28 → 0.48.30

package/README.md

@@ -107,6 +107,20 @@ await samsar.createVideoFromImageList({
   ],
 });
 
+// Create the same generated QR outro and per-scene footer CTAs from one CTA link
+await samsar.createVideoFromImageList({
+  image_urls: [
+    { image_url: 'https://example.com/a.jpg', title: 'Blue Lagoon Tour' },
+    { image_url: 'https://example.com/b.jpg', title: 'Sunset Dinner' },
+  ],
+  prompt: 'Travel offer reel with concise scene CTAs',
+  metadata: { brand: 'Guidestination', offer: 'Bookable Bangkok experiences' },
+  video_model: 'RUNWAYML',
+  aspect_ratio: '9:16',
+  express_cta_generation: true,
+  cta_url: 'https://example.com/book',
+});
+
 // Update an existing outro with a new provided outro image URL
 await samsar.updateVideoOutroImage(
   {
@@ -547,11 +561,12 @@ console.log(externalLibrary.data.requests.map((request) => request.request_id));
 
 Video model support notes:
 - `createVideoFromText` image model keys include: `GPTIMAGE2`, `IMAGEN4`, `SEEDREAM`, `NANOBANANA2`, `CUSTOM_TEXT_TO_IMAGE`.
-- `createVideoFromText` supports these video models: `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SEEDANCEI2V` (Seedance 1.5), `KLINGIMGTOVID3PRO`, and `CUSTOM_IMAGE_TO_VIDEO`.
+- `createVideoFromText` supports these video models: `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SEEDANCEI2V` (Seedance 1.5), `KLINGIMGTOVID3PRO`, and `HAPPYHORSEI2V`.
 - `createVideoFromText` accepts either a provided outro (`outro_image_url`) or server-generated QR outro (`generate_outro_image: true` with `cta_url`). It can also render bottom CTA footer QR cards with `add_footer_animation` and `footer_metadata`; one footer item applies to every generated scene, while multiple items map by scene index.
-- `createVideoFromImageList` supports `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SEEDANCEI2V`, `KLINGIMGTOVID3PRO`, and `CUSTOM_IMAGE_TO_VIDEO` via `video_model`; if omitted, it defaults to `RUNWAYML`. Use `aspect_ratio: '16:9'` or `'9:16'`; omitted or invalid values fall back to `16:9`.
+- `createVideoFromImageList` supports `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SEEDANCEI2V`, `KLINGIMGTOVID3PRO`, and `HAPPYHORSEI2V` via `video_model`; if omitted, it defaults to `RUNWAYML`. Use `aspect_ratio: '16:9'` or `'9:16'`; omitted or invalid values fall back to `16:9`.
 - `createVideoFromImageList` accepts either a provided outro (`outro_image_url`) or server-generated QR outro (`generate_outro_image: true` with `cta_url`). Do not combine the two modes in a single request.
 - `createVideoFromImageList` can render per-scene footer QR cards by setting `add_footer_animation: true` and providing one `footer_metadata` item per image scene.
+- `createVideoFromImageList` can also generate QR outro CTA text and each scene footer CTA from a single link by setting `express_cta_generation: true` with `cta_url`. CamelCase `expressCtaGeneration` and compatibility aliases `auto_generate_cta_text` / `generate_cta_texts` are normalized to the same API field.
 - `createVideoFromImageList` accepts `limit_single_narrator: true` to keep all narration under one narrator identity. `add_narrator_avatar: true` automatically enables `limit_single_narrator`, generates an influencer-style human narrator avatar, and overlays it bottom-center or centered in the footer row when footer metadata is present.
 - `updateVideoOutroImage` accepts either a replacement outro image URL (`outro_image_url`, `outroImageUrl`, `new_outro_image_url`) or a generated QR CTA outro (`generate_outro_image: true` with `cta_url`, or just `cta_url` when no outro image URL is supplied). Generated outro updates reuse the existing session image layers for tiling and only queue frame/video regeneration.
 - `updateVideoFooterImage` updates the footer CTA on a cloned session with `cta_text`, `cta_logo`, and/or `cta_url`, or removes all scene footers with `remove_footer: true`. Footer updates queue only frame/video regeneration.
@@ -559,13 +574,13 @@ Video model support notes:
 - Main video methods and external-user methods accept the same generated outro and footer parameters. The API can resolve either internal session ids or external `extreq_...` ids on repeated video routes, so client code can keep using `translateVideo`, `joinVideos`, `addSubtitles`, `removeSubtitles`, `addVideoOutroImage`, `updateVideoOutroImage`, and `updateVideoFooterImage`; the explicit external variants are available when you want to call `/external_users/*` directly. Do not strip the `extreq_` prefix.
 - Completed video status, latest-version, and completed-session list responses expose `has_subtitles` and `result_language` when the session metadata is available.
 - `publishPublication`, `editPublication`, and `revokePublication` manage public feed publications for completed sessions through free `/publications/*` endpoints. They work with account API keys, customer sub-account API keys, and client auth tokens when the session belongs to the authenticated actor.
-- Text-to-video and image-list video pricing use the same per-rendered-second rates for standard express models: `VEO3.1I2V` is 60 credits/sec, `VEO3.1I2VFAST` is 36 credits/sec, `SEEDANCEI2V` is 30 credits/sec, `KLINGIMGTOVID3PRO` is 36 credits/sec, and `RUNWAYML` is 30 credits/sec. Image-list narrator avatar generation adds 4 credits/sec when `add_narrator_avatar` is true.
-- Standard express video models expose a per-second pricing distribution through `EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL`: pipeline 4, inference 4, image gen/edit 2, speech 2, music 2, effects and lipsync 2, and video as the model-specific remainder.
+- Text-to-video and image-list video pricing use the same per-rendered-second rates for standard express models: `VEO3.1I2V` is 60 credits/sec, `VEO3.1I2VFAST` is 36 credits/sec, `SEEDANCEI2V` is 30 credits/sec, `KLINGIMGTOVID3PRO` is 36 credits/sec, `HAPPYHORSEI2V` is 36 credits/sec, and `RUNWAYML` is 30 credits/sec. Image-list narrator avatar generation adds 4 credits/sec when `add_narrator_avatar` is true; express CTA generation adds 1 credit/sec when `express_cta_generation` is true.
+- Standard express video models expose a per-second pricing distribution through `EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL`: pipeline 4, inference 4, image gen/edit 2, speech 2, music 2, effects and lipsync 2, video as the model-specific remainder, and `optionalAddons.express_cta_generation` at 1 credit/sec.
 
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
-- `createV2VideoFromText`, `createV2VideoFromImageList`, `translateV2Video`, `cloneV2Video`, `updateV2VideoOutroImage`, `updateV2VideoFooterImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2StatusDetailed`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
-- Step-controlled video helpers include `createV2StepVideoFromText`, `createV2StepTextToVideo`, `createV2StepVideoFromImage`, `createV2StepImageToVideo`, `getV2StepVideoStatus`, `getV2StepVideoStatusDetailed`, and `processNextV2StepVideo`.
+- `createV2VideoFromText`, `createV2VideoFromImageList`, `translateV2Video`, `cloneV2Video`, `regenerateV2VideoAvatar`, `updateV2VideoOutroImage`, `updateV2VideoFooterImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2StatusDetailed`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
+- Step-controlled video helpers include `createV2StepVideoFromText`, `createV2StepTextToVideo`, `createV2StepVideoFromImage`, `createV2StepImageToVideo`, `getV2StepVideoStatus`, `getV2StepVideoStatusDetailed`, and `processNextV2StepVideo`. They default to 1-step express rendering by sending `auto_render_full_video: true` and `manual_step_stages: []`; pass `{ stepMode: 'two_step' }` or `manual_step_stages: ['ai_video_generation']` to require an explicit second-step approval before image-to-video generation.
 - Programmatic user helpers include `createV2ExternalUser`, `createV2UserRechargeCredits`, `refreshV2UserToken`, `createV2UserAppKey`, `refreshV2UserAppKey`, `getV2UserCredits`, `getV2UserUsageLogs`, and `getV2UserPaymentStatus`.
 - Omit `externalUser` for internal account billing, pass `externalUser` to scope an external user with the account API key, or authenticate the client directly with an external-user auth token/API key. V2 external users can be referenced by `unique_key`; if `unique_key` is omitted during creation, the server uses `external_user_id` as the key.
 - Detailed status adapters return the normal status payload plus a normalized `session` preview shape with `layers`, `audioLayers`, `globalAudioLayers`, and `globalVideos`. Layer timing uses `startTime` and `endTime` so clients can preview generated images, scene clips, and speech before final render completion.
@@ -574,9 +589,8 @@ Upcoming `/v2` omni route adapters:
 const v2Video = await platform.createV2VideoFromImageList({
   image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
   video_model: 'RUNWAYML',
-  generate_outro_image: true,
+  express_cta_generation: true,
   cta_url: 'https://example.com/book',
-  cta_text_top: 'Scan to book',
 });
 
 const v2ExternalVideo = await platform.createV2VideoFromImageList(
@@ -599,6 +613,10 @@ const v2Clone = await platform.cloneV2Video({
   videoSessionId: v2Video.data.request_id!,
 });
 
+const v2AvatarRerender = await platform.regenerateV2VideoAvatar({
+  videoSessionId: v2Video.data.request_id!,
+});
+
 const v2Status = await platform.getV2Status(v2Video.data.request_id!);
 console.log(v2Status.data.status);
 
@@ -606,7 +624,7 @@ const v2Detailed = await platform.getV2StatusDetailed(v2Video.data.request_id!);
 console.log(v2Detailed.data.session?.previewStage, v2Detailed.data.session?.layers?.[0]?.preview?.url);
 ```
 
-Step-controlled video generation pauses after each completed stage until you call `processNextV2StepVideo`:
+Step video generation defaults to a 1-step express render, so it does not pause before image-to-video generation:
 
 ```ts
 const stepVideo = await platform.createV2StepVideoFromText({
@@ -618,12 +636,28 @@ const stepVideo = await platform.createV2StepVideoFromText({
   enable_subtitles: true,
 });
 
-let stepStatus = await platform.getV2StepVideoStatus(stepVideo.data.request_id);
-if (stepStatus.data.step_status === 'COMPLETED') {
-  console.log(stepStatus.data.current_step, stepStatus.data.current_step_resources);
-  const stepDetailed = await platform.getV2StepVideoStatusDetailed(stepVideo.data.request_id);
-  console.log(stepDetailed.data.session?.previewStage, stepDetailed.data.session?.layers?.[0]?.preview?.url);
-  stepStatus = await platform.processNextV2StepVideo(stepVideo.data.request_id);
+const stepDetailed = await platform.getV2StepVideoStatusDetailed(stepVideo.data.request_id);
+console.log(stepDetailed.data.session?.previewStage, stepDetailed.data.session?.layers?.[0]?.preview?.url);
+```
+
+Use 2-step mode only when you want to review generated image/audio assets before starting the image-to-video stage:
+
+```ts
+const twoStepVideo = await platform.createV2StepVideoFromText(
+  {
+    prompt: 'A 20 second launch teaser for a new travel app',
+    image_model: 'GPTIMAGE2',
+    video_model: 'RUNWAYML',
+    duration: 20,
+    aspect_ratio: '16:9',
+    enable_subtitles: true,
+  },
+  { stepMode: 'two_step' },
+);
+
+let stepStatus = await platform.getV2StepVideoStatus(twoStepVideo.data.request_id);
+if (stepStatus.data.waiting_for_process_next || stepStatus.data.can_process_next) {
+  stepStatus = await platform.processNextV2StepVideo(twoStepVideo.data.request_id);
 }
 
 const stepImageVideo = await platform.createV2StepVideoFromImage({

package/dist/express-video-pricing.d.ts

@@ -9,7 +9,12 @@ export declare const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND: {
 export type ExpressVideoPricingDistribution = typeof EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND & {
     video: number;
     total: number;
+    optionalAddons: ExpressVideoOptionalAddons;
 };
+export declare const EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND: {
+    readonly express_cta_generation: 1;
+};
+export type ExpressVideoOptionalAddons = typeof EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND;
 export declare const EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND: number;
 export declare const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL: {
     readonly 'VEO3.1I2V': 60;
@@ -17,6 +22,7 @@ export declare const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL: {
     readonly SEEDANCEI2V: 30;
     readonly KLINGIMGTOVID3PRO: 36;
     readonly KLINGIMGTOVIDTURBO: 36;
+    readonly HAPPYHORSEI2V: 36;
     readonly RUNWAYML: 30;
 };
 export declare const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL: Record<string, ExpressVideoPricingDistribution>;

package/dist/express-video-pricing.js

@@ -6,6 +6,9 @@ export const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND = {
     music: 2,
     effects_and_lipsync: 2,
 };
+export const EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND = {
+    express_cta_generation: 1,
+};
 export const EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND = Object.values(EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND).reduce((total, value) => total + value, 0);
 export const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL = {
     'VEO3.1I2V': 60,
@@ -13,6 +16,7 @@ export const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL = {
     SEEDANCEI2V: 30,
     KLINGIMGTOVID3PRO: 36,
     KLINGIMGTOVIDTURBO: 36,
+    HAPPYHORSEI2V: 36,
     RUNWAYML: 30,
 };
 export const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL = Object.fromEntries(Object.entries(EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL)
@@ -22,6 +26,7 @@ export const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL = Object.fro
         ...EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND,
         video: total - EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND,
         total,
+        optionalAddons: EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND,
     },
 ]));
 export function getExpressVideoCreditsPerSecond(model) {

package/dist/index.d.ts

@@ -36,7 +36,14 @@ export interface FontOptions {
     language?: string;
     family?: string;
 }
-export interface CreateVideoFromTextInput {
+export type V2StepGenerationMode = 'one_step' | 'two_step';
+export interface V2StepGenerationOptions {
+    auto_render_full_video?: boolean;
+    autoRenderFullVideo?: boolean;
+    manual_step_stages?: Array<V2StepVideoStage | string>;
+    manualStepStages?: Array<V2StepVideoStage | string>;
+}
+export interface CreateVideoFromTextInput extends V2StepGenerationOptions {
     prompt: string;
     image_model: string;
     video_model: string;
@@ -111,7 +118,7 @@ export interface FooterMetadataItem {
     footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
-export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'CUSTOM_IMAGE_TO_VIDEO';
+export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'HAPPYHORSEI2V';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -139,7 +146,7 @@ export interface ImageListToVideoItem {
     label?: string;
     [key: string]: unknown;
 }
-export interface CreateVideoFromImageListInput {
+export interface CreateVideoFromImageListInput extends V2StepGenerationOptions {
     image_urls: Array<string | ImageListToVideoItem>;
     metadata?: Record<string, unknown>;
     prompt?: string;
@@ -172,6 +179,12 @@ export interface CreateVideoFromImageListInput {
     outroFocusArea?: OutroFocusArea | null;
     generate_outro_image?: boolean;
     generateOutroImage?: boolean;
+    express_cta_generation?: boolean;
+    expressCtaGeneration?: boolean;
+    auto_generate_cta_text?: boolean;
+    autoGenerateCtaText?: boolean;
+    generate_cta_texts?: boolean;
+    generateCtaTexts?: boolean;
     cta_url?: string;
     ctaUrl?: string;
     cta_text_top?: string;
@@ -1411,6 +1424,9 @@ export interface V2RequestOptions extends SamsarRequestOptions {
     externalUser?: V2ExternalUserIdentity | null;
     webhookUrl?: string;
 }
+export interface V2StepVideoRequestOptions extends V2RequestOptions, V2StepGenerationOptions {
+    stepMode?: V2StepGenerationMode;
+}
 export type V2StepVideoStage = 'prompt_generation' | 'image_generation' | 'speech_generation' | 'music_generation' | 'audio_generation' | 'ai_video_generation' | 'lip_sync_generation' | 'sound_effect_generation' | 'narrator_avatar_generation' | 'delete_reflow' | 'timeline_reflowed' | 'transcript_generation' | 'frame_generation' | 'video_generation';
 export type V2StepVideoStatus = 'INIT' | 'PENDING' | 'COMPLETED' | 'FAILED' | string;
 export interface VideoSessionPreviewAsset {
@@ -1541,7 +1557,11 @@ export interface V2StepVideoState {
     current_step?: V2StepVideoStage | string | null;
     current_step_label?: string | null;
     next_step?: V2StepVideoStage | string | null;
+    manual_step_stages?: Array<V2StepVideoStage | string>;
+    auto_advance_step_stages?: Array<V2StepVideoStage | string>;
     waiting_for_process_next?: boolean;
+    requires_user_action?: boolean;
+    can_process_next?: boolean;
     updated_at?: string | null;
     [key: string]: unknown;
 }
@@ -1944,16 +1964,17 @@ export declare class SamsarClient {
     }): Promise<SamsarResult<CreateLoginTokenResponse | ExternalCreateLoginTokenResponse>>;
     createV2VideoFromText(input: CreateVideoFromTextInput, options?: V2RequestOptions): Promise<SamsarResult<CreateVideoResponse | ExternalRequestResponse>>;
     createV2VideoFromImageList(input: CreateVideoFromImageListInput, options?: V2RequestOptions): Promise<SamsarResult<CreateVideoFromImageListResponse | ExternalRequestResponse>>;
-    createV2StepVideoFromText(input: CreateVideoFromTextInput, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
-    createV2StepTextToVideo(input: CreateVideoFromTextInput, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
-    createV2StepVideoFromImage(input: CreateV2StepImageToVideoInput, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
-    createV2StepImageToVideo(input: CreateV2StepImageToVideoInput, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepVideoFromText(input: CreateVideoFromTextInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepTextToVideo(input: CreateVideoFromTextInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepVideoFromImage(input: CreateV2StepImageToVideoInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepImageToVideo(input: CreateV2StepImageToVideoInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
     getV2StepVideoStatus(requestId: string, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoStatusResponse>>;
     getV2StepVideoStatusDetailed(requestId: string, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoDetailedStatusResponse>>;
     getV2StepVideoDetailedStatus(requestId: string, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoDetailedStatusResponse>>;
     processNextV2StepVideo(requestId: string, options?: V2RequestOptions): Promise<SamsarResult<V2StepVideoStatusResponse>>;
     translateV2Video(input: TranslateVideoInput, options?: V2RequestOptions): Promise<SamsarResult<TranslateVideoResponse | ExternalRequestResponse>>;
     cloneV2Video(input: CloneVideoInput, options?: V2RequestOptions): Promise<SamsarResult<CloneVideoResponse>>;
+    regenerateV2VideoAvatar(input: CloneVideoInput, options?: V2RequestOptions): Promise<SamsarResult<CloneVideoResponse | ExternalRequestResponse>>;
     uploadV2ImageData(imageData: string[], options?: V2RequestOptions): Promise<SamsarResult<{
         image_urls: string[];
     }>>;

package/dist/index.js

@@ -4,6 +4,7 @@ const DEBUG = (() => {
     const env = globalThis?.process?.env;
     return env?.SAMSAR_SDK_DEBUG === '1';
 })();
+const DEFAULT_V2_STEP_MANUAL_STAGES = ['ai_video_generation'];
 export class SamsarRequestError extends Error {
     constructor(message, init) {
         super(message);
@@ -40,6 +41,85 @@ function assertOptionalBoolean(value, fieldName, context = 'createVideoFromImage
         throw new Error(`${fieldName} must be a boolean for ${context}`);
     }
 }
+function getFirstDefinedInputValue(raw, aliases) {
+    for (const alias of aliases) {
+        if (Object.prototype.hasOwnProperty.call(raw, alias)) {
+            return raw[alias];
+        }
+    }
+    return undefined;
+}
+function normalizeV2StepGenerationMode(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase().replace(/\s+/g, '_');
+    if (['one_step', 'one-step', '1_step', '1-step', 'express', 'auto', 'automatic'].includes(normalized)) {
+        return 'one_step';
+    }
+    if (['two_step', 'two-step', '2_step', '2-step', 'manual'].includes(normalized)) {
+        return 'two_step';
+    }
+    return null;
+}
+function normalizeV2StepBoolean(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    throw new Error(`${fieldName} must be a boolean for step video generation`);
+}
+function normalizeV2ManualStepStages(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === false || value === null) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value
+            .filter((stage) => typeof stage === 'string' && stage.trim().length > 0)
+            .map((stage) => stage.trim());
+    }
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map((stage) => stage.trim())
+            .filter(Boolean);
+    }
+    if (typeof value === 'object') {
+        return Object.entries(value)
+            .filter(([, enabled]) => enabled === true || enabled === 'true' || enabled === 1 || enabled === '1')
+            .map(([stage]) => stage.trim())
+            .filter(Boolean);
+    }
+    throw new Error('manual_step_stages must be an array, comma-separated string, stage map, null, or false');
+}
+function buildV2StepGenerationFields(input, options) {
+    const optionRecord = (options ?? {});
+    const stepMode = normalizeV2StepGenerationMode(optionRecord.stepMode);
+    const optionAutoRender = normalizeV2StepBoolean(getFirstDefinedInputValue(optionRecord, ['auto_render_full_video', 'autoRenderFullVideo']), 'auto_render_full_video');
+    const inputAutoRender = normalizeV2StepBoolean(getFirstDefinedInputValue(input, ['auto_render_full_video', 'autoRenderFullVideo']), 'auto_render_full_video');
+    const optionManualStages = normalizeV2ManualStepStages(getFirstDefinedInputValue(optionRecord, ['manual_step_stages', 'manualStepStages']));
+    const inputManualStages = normalizeV2ManualStepStages(getFirstDefinedInputValue(input, ['manual_step_stages', 'manualStepStages']));
+    let autoRenderFullVideo = stepMode ? stepMode === 'one_step' : optionAutoRender ?? inputAutoRender;
+    if (autoRenderFullVideo === undefined) {
+        autoRenderFullVideo = optionManualStages !== undefined || inputManualStages !== undefined
+            ? false
+            : true;
+    }
+    const manualStepStages = autoRenderFullVideo
+        ? []
+        : optionManualStages ?? inputManualStages ?? [...DEFAULT_V2_STEP_MANUAL_STAGES];
+    return {
+        auto_render_full_video: autoRenderFullVideo,
+        autoRenderFullVideo,
+        manual_step_stages: manualStepStages,
+        manualStepStages: manualStepStages,
+    };
+}
 function normalizeCreateVideoFromTextInput(input) {
     const raw = input;
     const normalized = { ...input };
@@ -96,6 +176,17 @@ function normalizeCreateVideoFromImageListInput(input) {
         ['add_outro_focus_area', ['add_outro_focus_area', 'addOutroFocusArea']],
         ['outro_focust_area', ['outro_focust_area', 'outro_focus_area', 'outroFocustArea', 'outroFocusArea']],
         ['generate_outro_image', ['generate_outro_image', 'generateOutroImage']],
+        [
+            'express_cta_generation',
+            [
+                'express_cta_generation',
+                'expressCtaGeneration',
+                'auto_generate_cta_text',
+                'autoGenerateCtaText',
+                'generate_cta_texts',
+                'generateCtaTexts',
+            ],
+        ],
         ['cta_url', ['cta_url', 'ctaUrl']],
         ['cta_text_top', ['cta_text_top', 'ctaTextTop']],
         ['cta_text_bottom', ['cta_text_bottom', 'ctaTextBottom']],
@@ -117,12 +208,24 @@ function normalizeCreateVideoFromImageListInput(input) {
     assertOptionalBoolean(normalized.add_outro_animation, 'add_outro_animation');
     assertOptionalBoolean(normalized.add_outro_focus_area, 'add_outro_focus_area');
     assertOptionalBoolean(normalized.generate_outro_image, 'generate_outro_image');
+    assertOptionalBoolean(normalized.express_cta_generation, 'express_cta_generation');
     assertOptionalBoolean(normalized.add_footer_animation, 'add_footer_animation');
     assertOptionalBoolean(normalized.limit_single_narrator, 'limit_single_narrator');
     assertOptionalBoolean(normalized.add_narrator_avatar, 'add_narrator_avatar');
     if (normalized.add_narrator_avatar === true) {
         normalized.limit_single_narrator = true;
     }
+    if (normalized.express_cta_generation === true) {
+        const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
+        if (!ctaUrl) {
+            throw new Error('cta_url is required when express_cta_generation is true for createVideoFromImageList');
+        }
+        normalized.cta_url = ctaUrl;
+        normalized.generate_outro_image = true;
+        normalized.add_outro_animation = true;
+        normalized.add_outro_focus_area = true;
+        normalized.add_footer_animation = true;
+    }
     if (normalized.generate_outro_image === true) {
         const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
         if (!ctaUrl) {
@@ -606,8 +709,13 @@ export class SamsarClient {
     }
     async createV2StepVideoFromText(input, options) {
         const normalizedInput = normalizeCreateVideoFromTextInput(input);
+        const stepGenerationFields = buildV2StepGenerationFields(normalizedInput, options);
         return this.postV2('video/step/text_to_video', {
-            input: normalizedInput,
+            ...stepGenerationFields,
+            input: {
+                ...normalizedInput,
+                ...stepGenerationFields,
+            },
             webhookUrl: options?.webhookUrl,
         }, options);
     }
@@ -616,8 +724,13 @@ export class SamsarClient {
     }
     async createV2StepVideoFromImage(input, options) {
         const normalizedInput = normalizeCreateV2StepImageToVideoInput(input);
+        const stepGenerationFields = buildV2StepGenerationFields(normalizedInput, options);
         return this.postV2('video/step/image_to_video', {
-            input: normalizedInput,
+            ...stepGenerationFields,
+            input: {
+                ...normalizedInput,
+                ...stepGenerationFields,
+            },
             webhookUrl: options?.webhookUrl,
         }, options);
     }
@@ -662,6 +775,13 @@ export class SamsarClient {
             webhookUrl: options?.webhookUrl,
         }, options);
     }
+    async regenerateV2VideoAvatar(input, options) {
+        const normalizedInput = normalizeCloneVideoInput(input, 'regenerateV2VideoAvatar');
+        return this.postV2('video/regenerate_avatar', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
     async uploadV2ImageData(imageData, options) {
         if (!Array.isArray(imageData) || imageData.length === 0) {
             throw new Error('imageData must be a non-empty array of data URLs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "samsar-js",
-  "version": "0.48.28",
+  "version": "0.48.30",
   "description": "TypeScript client for the Samsar Processor API routes.",
   "type": "module",
   "main": "dist/index.js",