samsar-js 0.48.27 → 0.48.28

package/README.md

@@ -547,9 +547,9 @@ 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: `VEO3.1I2V`, `VEO3.1I2VFAST`, `SEEDANCEI2V` (Seedance 2.0), `KLINGIMGTOVID3PRO`, `RUNWAYML`, and `CUSTOM_IMAGE_TO_VIDEO`.
+- `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`, `VEO3.1I2VFAST`, `SEEDANCEI2V`, `KLINGIMGTOVID3PRO`, `RUNWAYML`, and `CUSTOM_IMAGE_TO_VIDEO` via `video_model`; if omitted, it defaults to `VEO3.1I2V`. 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.
@@ -564,10 +564,11 @@ Video model support notes:
 
 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.
-- Step-controlled video helpers include `createV2StepVideoFromText`, `createV2StepTextToVideo`, `createV2StepVideoFromImage`, `createV2StepImageToVideo`, `getV2StepVideoStatus`, and `processNextV2StepVideo`.
+- `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({
@@ -600,6 +601,9 @@ 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`:
@@ -617,6 +621,8 @@ const stepVideo = await platform.createV2StepVideoFromText({
 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);
 }
 

package/dist/index.d.ts

@@ -111,7 +111,7 @@ export interface FooterMetadataItem {
     footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
-export type ImageListToVideoModel = 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'RUNWAYML' | 'CUSTOM_IMAGE_TO_VIDEO';
+export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'CUSTOM_IMAGE_TO_VIDEO';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -1411,8 +1411,129 @@ export interface V2RequestOptions extends SamsarRequestOptions {
     externalUser?: V2ExternalUserIdentity | null;
     webhookUrl?: string;
 }
-export type V2StepVideoStage = 'prompt_generation' | 'image_generation' | 'speech_generation' | 'music_generation' | 'ai_video_generation' | 'lip_sync_generation' | 'sound_effect_generation' | 'video_generation';
+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;
@@ -1443,6 +1564,10 @@ export interface V2StepVideoStatusResponse extends GlobalStatusResponse {
     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;
@@ -1824,6 +1949,8 @@ export declare class SamsarClient {
     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>>;
@@ -1836,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.
      */
@@ -2211,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

@@ -631,6 +631,16 @@ export class SamsarClient {
         }
         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) {
@@ -695,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.
      */
@@ -1960,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).
      */

package/package.json

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