samsar-js 0.48.26 → 0.48.28

package/README.md

@@ -77,7 +77,7 @@ const videoFromImages = await samsar.createVideoFromImageList(
 await samsar.createVideoFromImageList({
   image_urls: ['https://example.com/a.jpg', 'https://example.com/b.jpg'],
   prompt: 'Product launch teaser with a clean final CTA',
-  video_model: 'KLING3.0',
+  video_model: 'KLINGIMGTOVID3PRO',
   aspect_ratio: '16:9',
   outro_image_url: 'https://cdn.example.com/outro.png',
   add_outro_animation: true,
@@ -94,6 +94,7 @@ await samsar.createVideoFromImageList({
   prompt: 'Travel offer reel with a scannable booking outro',
   video_model: 'RUNWAYML',
   aspect_ratio: '9:16',
+  add_narrator_avatar: true,
   generate_outro_image: true,
   cta_url: 'https://example.com/book',
   cta_text_top: 'Scan to book',
@@ -434,6 +435,7 @@ const platform = new SamsarClient({
 
 const externalUser = {
   provider: 'whop',
+  unique_key: 'whop:usr_123',
   external_user_id: 'usr_123',
   external_app_id: 'app_abc',
   username: 'roy24x7',
@@ -544,25 +546,29 @@ console.log(externalLibrary.data.requests.map((request) => request.request_id));
 ```
 
 Video model support notes:
-- `createVideoFromText` image model keys include: `GPTIMAGE2`, `IMAGEN4`, `SEEDREAM`, `HUNYUAN`, `NANOBANANA2`.
-- `createVideoFromText` supports all express video models: `RUNWAYML`, `KLINGIMGTOVID3PRO`, `HAILUO`, `HAILUOPRO`, `SEEDANCEI2V` (Seedance 2.0), `VEO3.1I2V`, `VEO3.1I2VFAST`, `SORA2`, `SORA2PRO`.
+- `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` 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 `VEO3.1I2V`, `SEEDANCEI2V`, `KLING3.0`, and `RUNWAYML` via `video_model`; if omitted, it defaults to `VEO3.1I2V`. `KLINGIMGTOVID3PRO` is also accepted as a compatibility alias for `KLING3.0`. 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 `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` 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` 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.
 - `cloneVideo` creates a deep copy of a completed session and queues only the final video render so the clone receives a new rendered video path and URL. It does not charge credits.
 - 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.
-- Image-list video pricing is per rendered second: `VEO3.1I2V` and `SEEDANCEI2V` are 75 credits/sec, `KLING3.0` is 50 credits/sec, and `RUNWAYML` is 25 credits/sec.
+- 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.
 
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
-- `createV2VideoFromText`, `createV2VideoFromImageList`, `translateV2Video`, `cloneV2Video`, `updateV2VideoOutroImage`, `updateV2VideoFooterImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
-- Programmatic user billing helpers include `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.
+- `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`.
+- 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.
 
 ```ts
 const v2Video = await platform.createV2VideoFromImageList({
@@ -576,7 +582,7 @@ const v2Video = await platform.createV2VideoFromImageList({
 const v2ExternalVideo = await platform.createV2VideoFromImageList(
   {
     image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
-    video_model: 'KLING3.0',
+    video_model: 'KLINGIMGTOVID3PRO',
   },
   { externalUser },
 );
@@ -595,6 +601,61 @@ const v2Clone = await platform.cloneV2Video({
 
 const v2Status = await platform.getV2Status(v2Video.data.request_id!);
 console.log(v2Status.data.status);
+
+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`:
+
+```ts
+const stepVideo = 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,
+});
+
+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 stepImageVideo = await platform.createV2StepVideoFromImage({
+  image_url: 'https://cdn.example.com/product-frame.png',
+  prompt: 'Turn this product frame into a cinematic ad',
+  video_model: 'KLINGIMGTOVID3PRO',
+  aspect_ratio: '16:9',
+});
+console.log(stepImageVideo.data.step?.current_step);
+```
+
+Create and reference a V2 external user:
+
+```ts
+const createdExternalUser = await platform.createV2ExternalUser({
+  unique_key: 'wallet:0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  email: 'member@example.com',
+  display_name: 'Member Name',
+});
+
+const v2RegisteredExternalVideo = await platform.createV2VideoFromImageList(
+  {
+    image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
+    video_model: 'RUNWAYML',
+  },
+  {
+    externalUser: {
+      unique_key: createdExternalUser.data.unique_key!,
+    },
+  },
+);
+console.log(v2RegisteredExternalVideo.data.request_id);
 ```
 
 Programmatic user recharge and OAuth-style refresh token rotation:

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

@@ -0,0 +1,24 @@
+export declare const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND: {
+    readonly pipeline: 4;
+    readonly inference: 4;
+    readonly image_gen_edit: 2;
+    readonly speech: 2;
+    readonly music: 2;
+    readonly effects_and_lipsync: 2;
+};
+export type ExpressVideoPricingDistribution = typeof EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND & {
+    video: number;
+    total: number;
+};
+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;
+    readonly 'VEO3.1I2VFAST': 36;
+    readonly SEEDANCEI2V: 30;
+    readonly KLINGIMGTOVID3PRO: 36;
+    readonly KLINGIMGTOVIDTURBO: 36;
+    readonly RUNWAYML: 30;
+};
+export declare const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL: Record<string, ExpressVideoPricingDistribution>;
+export declare function getExpressVideoCreditsPerSecond(model: string | null | undefined): 60 | 36 | 30;
+export declare function getExpressVideoPricingDistributionPerSecond(model: string | null | undefined): ExpressVideoPricingDistribution;

package/dist/express-video-pricing.js

@@ -0,0 +1,34 @@
+export const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND = {
+    pipeline: 4,
+    inference: 4,
+    image_gen_edit: 2,
+    speech: 2,
+    music: 2,
+    effects_and_lipsync: 2,
+};
+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,
+    'VEO3.1I2VFAST': 36,
+    SEEDANCEI2V: 30,
+    KLINGIMGTOVID3PRO: 36,
+    KLINGIMGTOVIDTURBO: 36,
+    RUNWAYML: 30,
+};
+export const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL = Object.fromEntries(Object.entries(EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL)
+    .map(([model, total]) => [
+    model,
+    {
+        ...EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND,
+        video: total - EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND,
+        total,
+    },
+]));
+export function getExpressVideoCreditsPerSecond(model) {
+    const modelKey = typeof model === 'string' ? model.trim().toUpperCase() : '';
+    return EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL[modelKey] ?? null;
+}
+export function getExpressVideoPricingDistributionPerSecond(model) {
+    const modelKey = typeof model === 'string' ? model.trim().toUpperCase() : '';
+    return EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL[modelKey] ?? null;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL, EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND, EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND, EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL, getExpressVideoCreditsPerSecond, getExpressVideoPricingDistributionPerSecond, } from './express-video-pricing.js';
+export type { ExpressVideoPricingDistribution } from './express-video-pricing.js';
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 type QueryValue = string | number | boolean | null | undefined;
 type QueryParams = Record<string, QueryValue>;
@@ -109,7 +111,7 @@ export interface FooterMetadataItem {
     footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
-export type ImageListToVideoModel = 'VEO3.1I2V' | 'SEEDANCEI2V' | 'KLING3.0' | 'KLINGIMGTOVID3PRO' | 'RUNWAYML';
+export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'CUSTOM_IMAGE_TO_VIDEO';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -182,6 +184,10 @@ export interface CreateVideoFromImageListInput {
     addFooterAnimation?: boolean;
     footer_metadata?: FooterMetadataItem[];
     footerMetadata?: FooterMetadataItem[];
+    limit_single_narrator?: boolean;
+    limitSingleNarrator?: boolean;
+    add_narrator_avatar?: boolean;
+    addNarratorAvatar?: boolean;
     [key: string]: unknown;
 }
 export interface TranscriptBuilderPayload {
@@ -203,6 +209,12 @@ export interface CreateVideoFromImageListResponse {
     remainingCredits?: number | null;
     [key: string]: unknown;
 }
+export interface CreateV2StepImageToVideoInput extends Omit<CreateVideoFromImageListInput, 'image_urls'> {
+    image_urls?: Array<string | ImageListToVideoItem>;
+    image_url?: string;
+    imageUrl?: string;
+    image?: string;
+}
 export interface TranslateVideoInput {
     videoSessionId?: string;
     video_session_id?: string;
@@ -552,6 +564,7 @@ export interface SupportedTextToVideoModelOption {
     label: string;
     value: string;
     basePrice: number | null;
+    pricingDistribution?: Record<string, number> | null;
     [key: string]: unknown;
 }
 export interface EnhanceMessageRequest {
@@ -1197,6 +1210,8 @@ export interface GlobalStatusResponse {
 }
 export interface ExternalUserIdentity {
     provider: string;
+    unique_key?: string;
+    uniqueKey?: string;
     external_user_id?: string;
     externalUserId?: string;
     external_app_id?: string;
@@ -1222,6 +1237,7 @@ export interface ExternalUserSummary {
     id?: string | null;
     provider?: string;
     external_user_id?: string;
+    unique_key?: string | null;
     external_app_id?: string | null;
     external_company_id?: string | null;
     email?: string | null;
@@ -1392,9 +1408,173 @@ export interface ExternalRequestsListResponse {
     [key: string]: unknown;
 }
 export interface V2RequestOptions extends SamsarRequestOptions {
-    externalUser?: ExternalUserIdentity | null;
+    externalUser?: V2ExternalUserIdentity | null;
     webhookUrl?: string;
 }
+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 {
+    status?: V2StepVideoStatus;
+    url?: string | null;
+    editStatus?: string | null;
+    description?: string | null;
+    [key: string]: unknown;
+}
+export interface VideoSessionLayerPreview {
+    stage?: V2StepVideoStage | 'user_video' | string;
+    type?: 'image' | 'video' | 'audio' | string;
+    url?: string | null;
+    [key: string]: unknown;
+}
+export interface VideoSessionPreviewLayer {
+    index: number;
+    id?: string | null;
+    startTime: number;
+    endTime?: number | null;
+    duration?: number | null;
+    status?: string | null;
+    prompt?: string | null;
+    videoPrompt?: string | null;
+    aiVideoType?: string | null;
+    baseImageType?: string | null;
+    soundEffectPrompt?: string | null;
+    image?: VideoSessionPreviewAsset;
+    aiVideo?: VideoSessionPreviewAsset | null;
+    lipSyncVideo?: VideoSessionPreviewAsset | null;
+    soundEffectVideo?: VideoSessionPreviewAsset | null;
+    userVideo?: VideoSessionPreviewAsset | null;
+    preview?: VideoSessionLayerPreview | null;
+    [key: string]: unknown;
+}
+export interface VideoSessionPreviewAudioLayer {
+    index: number;
+    id?: string | null;
+    type?: string;
+    status?: V2StepVideoStatus;
+    startTime: number;
+    endTime?: number | null;
+    duration?: number | null;
+    sourceTrimStartTime?: number | null;
+    prompt?: string | null;
+    url?: string | null;
+    remoteAudioLinks?: string[];
+    volume?: number | null;
+    isEnabled?: boolean | null;
+    defaultSelected?: boolean | null;
+    speaker?: string | null;
+    provider?: string | null;
+    speakerCharacterName?: string | null;
+    lyrics?: string | null;
+    connectedLayerId?: string | null;
+    connectedLayerIndex?: number | null;
+    audioBindingMode?: string | null;
+    bindToLayer?: boolean | null;
+    addSubtitles?: boolean | null;
+    subtitleFont?: string | null;
+    subtitleWordAnimation?: string | null;
+    transcriptAlignment?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export interface VideoSessionPreviewGlobalVideo {
+    index: number;
+    id?: string | null;
+    type?: 'video' | string;
+    source?: string | null;
+    title?: string | null;
+    status?: V2StepVideoStatus;
+    startTime: number;
+    endTime?: number | null;
+    duration?: number | null;
+    url?: string | null;
+    framesPerSecond?: number | null;
+    [key: string]: unknown;
+}
+export interface VideoSessionPreviewResult {
+    url?: string | null;
+    remoteURL?: string | null;
+    videoLink?: string | null;
+    hasSubtitles?: boolean;
+    hasFooter?: boolean;
+    language?: string | null;
+    [key: string]: unknown;
+}
+export interface VideoStatusDetailedSession {
+    id?: string | null;
+    requestId?: string | null;
+    type?: 'video' | string;
+    routeType?: 'express' | 'step' | string;
+    aspectRatio?: string | null;
+    framesPerSecond?: number | null;
+    duration?: number;
+    language?: string | null;
+    languageString?: string | null;
+    hasSubtitles?: boolean;
+    hasFooter?: boolean;
+    inputPrompt?: string | null;
+    generationType?: string | null;
+    provider?: string | null;
+    currentStage?: V2StepVideoStage | string;
+    previewStage?: V2StepVideoStage | string;
+    completedStages?: Array<V2StepVideoStage | string>;
+    stages?: Record<string, V2StepVideoStatus | unknown>;
+    layers?: VideoSessionPreviewLayer[];
+    audioLayers?: VideoSessionPreviewAudioLayer[];
+    globalAudioLayers?: VideoSessionPreviewAudioLayer[];
+    globalVideos?: VideoSessionPreviewGlobalVideo[];
+    result?: VideoSessionPreviewResult;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    [key: string]: unknown;
+}
+export interface GlobalStatusDetailedResponse extends GlobalStatusResponse {
+    status_detail_schema?: 'video_session_preview.v1' | string;
+    session?: VideoStatusDetailedSession | null;
+}
+export interface ExternalStatusDetailedResponse extends ExternalStatusResponse {
+    status_detail_schema?: 'video_session_preview.v1' | string;
+    session?: VideoStatusDetailedSession | null;
+}
+export interface V2StepVideoState {
+    enabled?: boolean;
+    route_type?: 'text_to_video' | 'image_to_video' | string | null;
+    status?: V2StepVideoStatus;
+    current_step?: V2StepVideoStage | string | null;
+    current_step_label?: string | null;
+    next_step?: V2StepVideoStage | string | null;
+    waiting_for_process_next?: boolean;
+    updated_at?: string | null;
+    [key: string]: unknown;
+}
+export interface V2StepVideoResourceBlock {
+    step?: V2StepVideoStage | string;
+    label?: string;
+    status?: V2StepVideoStatus;
+    completed_at?: string | null;
+    resources?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface V2StepVideoStatusResponse extends GlobalStatusResponse {
+    step_status?: V2StepVideoStatus;
+    current_step?: V2StepVideoStage | string | null;
+    current_step_label?: string | null;
+    next_step?: V2StepVideoStage | string | null;
+    waiting_for_process_next?: boolean;
+    process_next_url?: string;
+    step?: V2StepVideoState;
+    current_step_resources?: V2StepVideoResourceBlock | null;
+    completed_step_resources?: Record<string, V2StepVideoResourceBlock>;
+}
+export interface V2StepVideoDetailedStatusResponse extends V2StepVideoStatusResponse {
+    status_detail_schema?: 'video_session_preview.v1' | string;
+    session?: VideoStatusDetailedSession | null;
+}
+export interface V2StepVideoCreateResponse extends CreateVideoResponse {
+    status?: V2StepVideoStatus;
+    step?: V2StepVideoState;
+}
+export interface V2ExternalUserIdentity extends Omit<ExternalUserIdentity, 'provider'> {
+    provider?: string;
+}
 export interface V2SessionResponse {
     account_type?: 'internal' | 'external' | string;
     auth_type?: string;
@@ -1450,6 +1630,27 @@ export interface V2UserTokenResponse {
     refreshTokenExpiresAt?: string;
     [key: string]: unknown;
 }
+export interface V2CreateExternalUserRequest extends V2ExternalUserIdentity {
+    external_user?: V2ExternalUserIdentity | null;
+    externalUser?: V2ExternalUserIdentity | null;
+}
+export interface V2CreateExternalUserReference {
+    provider?: string | null;
+    unique_key?: string | null;
+    external_user_id?: string | null;
+    external_app_id?: string | null;
+    [key: string]: unknown;
+}
+export interface V2CreateExternalUserResponse {
+    unique_key?: string | null;
+    provider?: string | null;
+    external_user_id?: string | null;
+    external_app_id?: string | null;
+    external_user?: ExternalUserSummary | null;
+    externalUser?: ExternalUserSummary | null;
+    reference?: V2CreateExternalUserReference;
+    [key: string]: unknown;
+}
 export interface V2UserAppKeyRequest {
     secret?: string;
     appSecret?: string;
@@ -1592,6 +1793,7 @@ export interface VerifiedClientSessionResponse {
     avatarUrl?: string | null;
     provider?: string | null;
     externalUserId?: string | null;
+    uniqueKey?: string | null;
     externalAppId?: string | null;
     externalCompanyId?: string | null;
     generationCredits?: number;
@@ -1728,6 +1930,7 @@ export declare class SamsarClient {
         limit?: number;
     }): Promise<SamsarResult<UsageLogsResponse>>;
     listV2Requests(options?: V2RequestOptions): Promise<SamsarResult<V2RequestsListResponse>>;
+    createV2ExternalUser(payload: V2CreateExternalUserRequest, options?: V2RequestOptions): Promise<SamsarResult<V2CreateExternalUserResponse>>;
     createV2UserRechargeCredits(payload: V2UserRechargeCreditsRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserRechargeCreditsResponse>>;
     refreshV2UserToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
     refreshV2UserAuthToken(payload: string | V2UserTokenRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserTokenResponse>>;
@@ -1741,6 +1944,14 @@ 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>>;
+    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>>;
     uploadV2ImageData(imageData: string[], options?: V2RequestOptions): Promise<SamsarResult<{
@@ -1752,6 +1963,12 @@ export declare class SamsarClient {
     getV2Status(requestId: string, options?: V2RequestOptions & {
         queryParams?: QueryParams;
     }): Promise<SamsarResult<GlobalStatusResponse | ExternalStatusResponse>>;
+    getV2StatusDetailed(requestId: string, options?: V2RequestOptions & {
+        queryParams?: QueryParams;
+    }): Promise<SamsarResult<GlobalStatusDetailedResponse | ExternalStatusDetailedResponse>>;
+    getV2DetailedStatus(requestId: string, options?: V2RequestOptions & {
+        queryParams?: QueryParams;
+    }): Promise<SamsarResult<GlobalStatusDetailedResponse | ExternalStatusDetailedResponse>>;
     /**
      * Create a new video generation job from text.
      */
@@ -2127,6 +2344,12 @@ export declare class SamsarClient {
     getExternalStatus(requestId: string, options?: SamsarRequestOptions & {
         queryParams?: QueryParams;
     }): Promise<SamsarResult<ExternalStatusResponse>>;
+    /**
+     * Retrieve external-user status plus normalized video-session preview data.
+     */
+    getExternalStatusDetailed(requestId: string, options?: SamsarRequestOptions & {
+        queryParams?: QueryParams;
+    }): Promise<SamsarResult<ExternalStatusDetailedResponse>>;
     /**
      * Retrieve the status of an image request (maps to GET /image/status).
      */

package/dist/index.js

@@ -1,4 +1,5 @@
 const DEFAULT_BASE_URL = 'https://api.samsar.one/v1';
+export { EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL, EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND, EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND, EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL, getExpressVideoCreditsPerSecond, getExpressVideoPricingDistributionPerSecond, } from './express-video-pricing.js';
 const DEBUG = (() => {
     const env = globalThis?.process?.env;
     return env?.SAMSAR_SDK_DEBUG === '1';
@@ -101,6 +102,8 @@ function normalizeCreateVideoFromImageListInput(input) {
         ['cta_logo', ['cta_logo', 'ctaLogo']],
         ['add_footer_animation', ['add_footer_animation', 'addFooterAnimation']],
         ['footer_metadata', ['footer_metadata', 'footerMetadata']],
+        ['limit_single_narrator', ['limit_single_narrator', 'limitSingleNarrator']],
+        ['add_narrator_avatar', ['add_narrator_avatar', 'addNarratorAvatar']],
         ['enable_subtitles', ['enable_subtitles', 'enableSubtitles']],
         ['font_key', ['font_key', 'fontKey']],
     ];
@@ -115,6 +118,11 @@ function normalizeCreateVideoFromImageListInput(input) {
     assertOptionalBoolean(normalized.add_outro_focus_area, 'add_outro_focus_area');
     assertOptionalBoolean(normalized.generate_outro_image, 'generate_outro_image');
     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.generate_outro_image === true) {
         const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
         if (!ctaUrl) {
@@ -126,6 +134,23 @@ function normalizeCreateVideoFromImageListInput(input) {
     }
     return normalized;
 }
+function normalizeCreateV2StepImageToVideoInput(input) {
+    const raw = input;
+    const normalized = { ...input };
+    if (!Array.isArray(input.image_urls) || input.image_urls.length === 0) {
+        const imageUrl = getTrimmedString(raw.image_url) ??
+            getTrimmedString(raw.imageUrl) ??
+            getTrimmedString(raw.image);
+        if (!imageUrl) {
+            throw new Error('image_url or image_urls is required for createV2StepVideoFromImage');
+        }
+        normalized.image_urls = [imageUrl];
+    }
+    delete normalized.image_url;
+    delete normalized.imageUrl;
+    delete normalized.image;
+    return normalizeCreateVideoFromImageListInput(normalized);
+}
 function normalizeTranslateVideoInput(input, context = 'translateVideo') {
     const raw = input;
     const videoSessionId = raw.videoSessionId ??
@@ -416,7 +441,9 @@ export class SamsarClient {
      */
     async getV2(path, options) {
         const query = {
-            ...(options?.externalUser ? buildExternalUserQuery(options.externalUser) : {}),
+            ...(options?.externalUser
+                ? buildExternalUserQuery(options.externalUser, { requireProvider: false })
+                : {}),
             ...(options?.query ?? {}),
         };
         return this.get(this.buildV2Url(path), { ...(options ?? {}), query });
@@ -451,6 +478,27 @@ export class SamsarClient {
     async listV2Requests(options) {
         return this.getV2('requests', options);
     }
+    async createV2ExternalUser(payload, options) {
+        const input = payload ?? {};
+        const nestedExternalUser = (input.external_user ?? input.externalUser ?? {});
+        const uniqueKey = getTrimmedString(nestedExternalUser.unique_key ??
+            nestedExternalUser.uniqueKey ??
+            input.unique_key ??
+            input.uniqueKey);
+        const externalUserId = getTrimmedString(nestedExternalUser.external_user_id ??
+            nestedExternalUser.externalUserId ??
+            input.external_user_id ??
+            input.externalUserId);
+        const referenceKey = uniqueKey ?? externalUserId;
+        if (!referenceKey) {
+            throw new Error('unique_key or external_user_id is required');
+        }
+        return this.postV2('user/create_external_user', {
+            ...input,
+            unique_key: referenceKey,
+            ...(externalUserId ? { external_user_id: externalUserId } : {}),
+        }, options);
+    }
     async createV2UserRechargeCredits(payload, options) {
         const amount = Number(payload?.amount);
         if (!Number.isFinite(amount) || amount <= 0) {
@@ -556,6 +604,50 @@ export class SamsarClient {
             webhookUrl: options?.webhookUrl,
         }, options);
     }
+    async createV2StepVideoFromText(input, options) {
+        const normalizedInput = normalizeCreateVideoFromTextInput(input);
+        return this.postV2('video/step/text_to_video', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async createV2StepTextToVideo(input, options) {
+        return this.createV2StepVideoFromText(input, options);
+    }
+    async createV2StepVideoFromImage(input, options) {
+        const normalizedInput = normalizeCreateV2StepImageToVideoInput(input);
+        return this.postV2('video/step/image_to_video', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
+    async createV2StepImageToVideo(input, options) {
+        return this.createV2StepVideoFromImage(input, options);
+    }
+    async getV2StepVideoStatus(requestId, options) {
+        const normalizedRequestId = getTrimmedString(requestId);
+        if (!normalizedRequestId) {
+            throw new Error('requestId is required');
+        }
+        return this.getV2(`video/step/${encodeURIComponent(normalizedRequestId)}/status`, options);
+    }
+    async getV2StepVideoStatusDetailed(requestId, options) {
+        const normalizedRequestId = getTrimmedString(requestId);
+        if (!normalizedRequestId) {
+            throw new Error('requestId is required');
+        }
+        return this.getV2(`video/step/${encodeURIComponent(normalizedRequestId)}/status_detailed`, options);
+    }
+    async getV2StepVideoDetailedStatus(requestId, options) {
+        return this.getV2StepVideoStatusDetailed(requestId, options);
+    }
+    async processNextV2StepVideo(requestId, options) {
+        const normalizedRequestId = getTrimmedString(requestId);
+        if (!normalizedRequestId) {
+            throw new Error('requestId is required');
+        }
+        return this.postV2(`video/step/${encodeURIComponent(normalizedRequestId)}/process_next`, {}, options);
+    }
     async translateV2Video(input, options) {
         const normalizedInput = normalizeTranslateVideoInput(input, 'translateV2Video');
         return this.postV2('translate_video', {
@@ -602,7 +694,9 @@ export class SamsarClient {
     }
     async getV2Status(requestId, options) {
         const queryParams = {
-            ...(options?.externalUser ? buildExternalUserQuery(options.externalUser) : {}),
+            ...(options?.externalUser
+                ? buildExternalUserQuery(options.externalUser, { requireProvider: false })
+                : {}),
             ...(options?.queryParams ?? {}),
         };
         return this.getStatus(requestId, {
@@ -611,6 +705,22 @@ export class SamsarClient {
             queryParams,
         });
     }
+    async getV2StatusDetailed(requestId, options) {
+        const queryParams = {
+            ...(options?.externalUser
+                ? buildExternalUserQuery(options.externalUser, { requireProvider: false })
+                : {}),
+            ...(options?.queryParams ?? {}),
+        };
+        return this.getStatus(requestId, {
+            ...options,
+            path: this.buildV2Url('status_detailed'),
+            queryParams,
+        });
+    }
+    async getV2DetailedStatus(requestId, options) {
+        return this.getV2StatusDetailed(requestId, options);
+    }
     /**
      * Create a new video generation job from text.
      */
@@ -1876,6 +1986,16 @@ export class SamsarClient {
         });
         return response;
     }
+    /**
+     * Retrieve external-user status plus normalized video-session preview data.
+     */
+    async getExternalStatusDetailed(requestId, options) {
+        const response = await this.getStatus(requestId, {
+            ...options,
+            path: 'external_users/status_detailed',
+        });
+        return response;
+    }
     /**
      * Retrieve the status of an image request (maps to GET /image/status).
      */
@@ -2015,9 +2135,29 @@ export class SamsarClient {
         if (!options?.externalUser) {
             return body;
         }
+        const externalUser = normalizeExternalUserIdentity(options.externalUser, {
+            requireProvider: false,
+        });
+        if (!externalUser.provider) {
+            const referenceKey = externalUser.unique_key ?? externalUser.external_user_id;
+            return {
+                ...body,
+                unique_key: referenceKey,
+                ...(externalUser.external_user_id ? { external_user_id: externalUser.external_user_id } : {}),
+                ...(externalUser.external_app_id ? { external_app_id: externalUser.external_app_id } : {}),
+                ...(externalUser.external_company_id ? { external_company_id: externalUser.external_company_id } : {}),
+                ...(externalUser.external_account_id ? { external_account_id: externalUser.external_account_id } : {}),
+                ...(externalUser.email ? { email: externalUser.email } : {}),
+                ...(externalUser.username ? { username: externalUser.username } : {}),
+                ...(externalUser.display_name ? { display_name: externalUser.display_name } : {}),
+                ...(externalUser.avatar_url ? { avatar_url: externalUser.avatar_url } : {}),
+                ...(externalUser.user_type ? { user_type: externalUser.user_type } : {}),
+                ...(externalUser.metadata ? { metadata: externalUser.metadata } : {}),
+            };
+        }
         return {
             ...body,
-            external_user: normalizeExternalUserIdentity(options.externalUser),
+            external_user: externalUser,
         };
     }
     buildV2Url(path) {
@@ -2066,6 +2206,13 @@ function parseNumber(value) {
     const num = value !== undefined ? Number(value) : NaN;
     return Number.isFinite(num) ? num : undefined;
 }
+function getTrimmedString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
 function removeEmptyHeaders(headers) {
     const normalized = {};
     for (const [key, value] of Object.entries(headers)) {
@@ -2075,15 +2222,22 @@ function removeEmptyHeaders(headers) {
     }
     return normalized;
 }
-function normalizeExternalUserIdentity(externalUser) {
-    const externalUserId = externalUser.external_user_id ??
-        externalUser.externalUserId;
-    if (!externalUser?.provider || !externalUserId) {
-        throw new Error('externalUser.provider and externalUser.external_user_id are required');
+function normalizeExternalUserIdentity(externalUser, { requireProvider = true } = {}) {
+    const provider = getTrimmedString(externalUser.provider);
+    const uniqueKey = getTrimmedString(externalUser.unique_key ??
+        externalUser.uniqueKey);
+    const externalUserId = getTrimmedString(externalUser.external_user_id) ??
+        getTrimmedString(externalUser.externalUserId) ??
+        uniqueKey;
+    if ((requireProvider && !provider) || !externalUserId) {
+        throw new Error(requireProvider
+            ? 'externalUser.provider and externalUser.external_user_id or externalUser.unique_key are required'
+            : 'externalUser.external_user_id or externalUser.unique_key is required');
     }
     return {
-        provider: externalUser.provider,
+        ...(provider ? { provider } : {}),
         external_user_id: externalUserId,
+        ...(uniqueKey ? { unique_key: uniqueKey } : {}),
         ...(externalUser.external_app_id || externalUser.externalAppId
             ? { external_app_id: externalUser.external_app_id ?? externalUser.externalAppId }
             : {}),
@@ -2112,11 +2266,12 @@ function normalizeExternalUserIdentity(externalUser) {
         ...(externalUser.metadata ? { metadata: externalUser.metadata } : {}),
     };
 }
-function buildExternalUserQuery(externalUser) {
-    const normalized = normalizeExternalUserIdentity(externalUser);
+function buildExternalUserQuery(externalUser, { requireProvider = true } = {}) {
+    const normalized = normalizeExternalUserIdentity(externalUser, { requireProvider });
     return {
         provider: normalized.provider,
         external_user_id: normalized.external_user_id,
+        unique_key: normalized.unique_key ?? undefined,
         external_app_id: normalized.external_app_id ?? undefined,
         external_company_id: normalized.external_company_id ?? undefined,
         external_account_id: normalized.external_account_id ?? undefined,

package/package.json

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