samsar-js 0.48.22 → 0.48.24

package/README.md

@@ -131,6 +131,23 @@ await samsar.updateVideoOutroImage(
   { webhookUrl: 'https://example.com/webhook' },
 );
 
+// Update the footer CTA on an existing video session
+await samsar.updateVideoFooterImage(
+  {
+    videoSessionId: videoFromImages.data.session_id ?? videoFromImages.data.request_id!,
+    cta_text: 'Scan to book',
+    cta_logo: 'https://cdn.example.com/logo-white.png',
+    cta_url: 'https://example.com/book',
+  },
+  { webhookUrl: 'https://example.com/webhook' },
+);
+
+// Remove the footer from a cloned rerender
+await samsar.updateVideoFooterImage({
+  videoSessionId: videoFromImages.data.session_id ?? videoFromImages.data.request_id!,
+  remove_footer: true,
+});
+
 // Translate an existing video session into another language
 const translated = await samsar.translateVideo(
   {
@@ -161,9 +178,17 @@ const noSubtitles = await samsar.removeSubtitles(
   { webhookUrl: 'https://example.com/webhook' },
 );
 
+// Clone a session and add subtitle/transcript text overlays
+const withSubtitles = await samsar.addSubtitles(
+  {
+    videoSessionId: noSubtitles.data.session_id ?? noSubtitles.data.request_id!,
+  },
+  { webhookUrl: 'https://example.com/webhook' },
+);
+
 // Cancel an in-progress render
 const cancelled = await samsar.cancelRender({
-  videoSessionId: noSubtitles.data.session_id ?? noSubtitles.data.request_id!,
+  videoSessionId: withSubtitles.data.session_id ?? withSubtitles.data.request_id!,
 });
 console.log(cancelled.data.status, cancelled.data.cancelled);
 
@@ -331,15 +356,18 @@ const rollup = await samsar.enhanceAndGenerateRollupBanner({
 
 // Check status by request_id (defaults to /v1/status)
 const status = await samsar.getStatus(video.data.request_id);
+if (status.data.status === 'COMPLETED') {
+  console.log(status.data.result_url, status.data.has_subtitles, status.data.result_language);
+}
 
 // Fetch the latest render URL for a session (when available)
 const latest = await samsar.fetchLatestVideoVersion(video.data.session_id ?? video.data.request_id);
-console.log(latest.data.result_url ?? latest.data.status);
+console.log(latest.data.result_url ?? latest.data.status, latest.data.has_subtitles, latest.data.result_language);
 
 // List completed video sessions for this API key
 const completedSessions = await samsar.listCompletedVideoSessions();
 completedSessions.data.forEach((session) => {
-  console.log(session.session_id, session.langauge, session.result_url);
+  console.log(session.session_id, session.result_language ?? session.langauge, session.has_subtitles, session.result_url);
 });
 
 // Publish, edit, or revoke a completed session in the public publication feed (free endpoints)
@@ -434,6 +462,15 @@ const externalOutroUpdate = await platform.updateExternalVideoOutroImage(externa
 });
 console.log(externalOutroUpdate.data.request_id);
 
+// Update or remove an external user's existing footer CTA.
+const externalFooterUpdate = await platform.updateExternalVideoFooterImage(externalUser, {
+  request_id: externalRender.data.request_id,
+  cta_text: 'Scan to shop',
+  cta_logo: 'https://cdn.example.com/logo-white.png',
+  cta_url: 'https://example.com/shop',
+});
+console.log(externalFooterUpdate.data.request_id);
+
 // Repeated video routes accept the returned extreq_ id or the normalized external id.
 // The API resolves ownership through external request mappings and GlobalSession records.
 
@@ -505,13 +542,15 @@ Video model support notes:
 - `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.
 - `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.
-- 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`, `addVideoOutroImage`, and `updateVideoOutroImage`; the explicit external variants are available when you want to call `/external_users/*` directly. Do not strip the `extreq_` prefix.
+- `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.
+- 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.
 
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
-- `createV2VideoFromText`, `createV2VideoFromImageList`, `updateV2VideoOutroImage`, `addV2VideoOutroImage`, `getV2Status`, `getV2Credits`, `listV2Requests`, and `createV2Session` call the new omni route surface.
+- `createV2VideoFromText`, `createV2VideoFromImageList`, `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.
 

package/dist/index.d.ts

@@ -51,6 +51,8 @@ export interface CreateVideoFromTextInput {
     languageString?: string | null;
     enable_subtitles?: boolean;
     enableSubtitles?: boolean;
+    add_subtitles?: boolean;
+    addSubtitles?: boolean;
     session_id?: string;
     sessionId?: string;
     sessionID?: string;
@@ -93,8 +95,18 @@ export interface OutroFocusArea {
     height: number;
 }
 export interface FooterMetadataItem {
-    url: string;
+    url?: string;
+    cta_url?: string;
+    ctaUrl?: string;
     title?: string;
+    text?: string;
+    cta_text?: string;
+    ctaText?: string;
+    cta_logo?: string;
+    ctaLogo?: string;
+    logoUrl?: string;
+    logoImagePath?: string;
+    footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
 export type ImageListToVideoModel = 'VEO3.1I2V' | 'SEEDANCEI2V' | 'KLING3.0' | 'KLINGIMGTOVID3PRO' | 'RUNWAYML';
@@ -141,6 +153,8 @@ export interface CreateVideoFromImageListInput {
     font?: FontOptions;
     enable_subtitles?: boolean;
     enableSubtitles?: boolean;
+    add_subtitles?: boolean;
+    addSubtitles?: boolean;
     session_id?: string;
     sessionId?: string;
     sessionID?: string;
@@ -266,6 +280,39 @@ export interface UpdateVideoOutroImageResponse {
     remainingCredits?: number | null;
     [key: string]: unknown;
 }
+export interface UpdateVideoFooterImageInput {
+    videoSessionId?: string;
+    video_session_id?: string;
+    videoSessionID?: string;
+    session_id?: string;
+    sessionId?: string;
+    sessionID?: string;
+    request_id?: string;
+    requestId?: string;
+    source_request_id?: string;
+    sourceRequestId?: string;
+    external_request_id?: string;
+    externalRequestId?: string;
+    external_session_id?: string;
+    externalSessionId?: string;
+    remove_footer?: boolean;
+    removeFooter?: boolean;
+    cta_text?: string;
+    ctaText?: string;
+    cta_logo?: string;
+    ctaLogo?: string;
+    cta_url?: string;
+    ctaUrl?: string;
+    [key: string]: unknown;
+}
+export interface UpdateVideoFooterImageResponse {
+    request_id?: string;
+    session_id?: string;
+    sessionID?: string;
+    creditsCharged?: number;
+    remainingCredits?: number | null;
+    [key: string]: unknown;
+}
 export interface AddVideoOutroImageInput {
     videoSessionId?: string;
     video_session_id?: string;
@@ -339,6 +386,10 @@ export interface RemoveSubtitlesResponse {
     remainingCredits?: number | null;
     [key: string]: unknown;
 }
+export interface AddSubtitlesInput extends RemoveSubtitlesInput {
+}
+export interface AddSubtitlesResponse extends RemoveSubtitlesResponse {
+}
 export interface CancelRenderInput {
     videoSessionId?: string;
     video_session_id?: string;
@@ -362,6 +413,8 @@ export interface CancelRenderResponse {
 export interface FetchLatestVideoVersionResponse {
     session_id: string;
     result_url?: string;
+    has_subtitles?: boolean | null;
+    result_language?: string | null;
     status?: string;
     message?: string;
     [key: string]: unknown;
@@ -370,6 +423,8 @@ export interface CompletedVideoSession {
     session_id: string;
     langauge: string;
     language?: string;
+    result_language?: string;
+    has_subtitles?: boolean | null;
     result_url: string;
     [key: string]: unknown;
 }
@@ -1103,6 +1158,8 @@ export interface GlobalStatusResponse {
     type?: 'image' | 'video' | string;
     provider?: string | null;
     result_url?: string | null;
+    has_subtitles?: boolean | null;
+    result_language?: string | null;
     thumbnail_url?: string | null;
     result_urls?: string[];
     videoLink?: string | null;
@@ -1664,6 +1721,7 @@ export declare class SamsarClient {
         image_urls: string[];
     }>>;
     updateV2VideoOutroImage(input: UpdateVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<UpdateVideoOutroImageResponse | ExternalRequestResponse>>;
+    updateV2VideoFooterImage(input: UpdateVideoFooterImageInput, options?: V2RequestOptions): Promise<SamsarResult<UpdateVideoFooterImageResponse | ExternalRequestResponse>>;
     addV2VideoOutroImage(input: AddVideoOutroImageInput, options?: V2RequestOptions): Promise<SamsarResult<AddVideoOutroImageResponse | ExternalRequestResponse>>;
     getV2Status(requestId: string, options?: V2RequestOptions & {
         queryParams?: QueryParams;
@@ -1758,6 +1816,13 @@ export declare class SamsarClient {
     removeSubtitles(input: RemoveSubtitlesInput, options?: {
         webhookUrl?: string;
     } & SamsarRequestOptions): Promise<SamsarResult<RemoveSubtitlesResponse>>;
+    /**
+     * Add subtitle/transcript text overlays by cloning an existing session and re-running
+     * transcription + frame + video generation on the new session.
+     */
+    addSubtitles(input: AddSubtitlesInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<AddSubtitlesResponse>>;
     /**
      * Cancel an in-progress render for an existing video session.
      */
@@ -1776,6 +1841,20 @@ export declare class SamsarClient {
     updateExternalVideoOutroImage(externalUser: ExternalUserIdentity, input: UpdateVideoOutroImageInput, options?: {
         webhookUrl?: string;
     } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
+    /**
+     * Update or remove the footer for an existing video session by cloning it into a new session and
+     * re-running frame/video generation.
+     */
+    updateVideoFooterImage(input: UpdateVideoFooterImageInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<UpdateVideoFooterImageResponse>>;
+    /**
+     * Update or remove the footer for an external-user video request through
+     * /external_users/update_footer_image.
+     */
+    updateExternalVideoFooterImage(externalUser: ExternalUserIdentity, input: UpdateVideoFooterImageInput, options?: {
+        webhookUrl?: string;
+    } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
     /**
      * Add or replace the outro image for an existing video session by cloning it into a new session and
      * re-running frame/video generation.
@@ -1791,11 +1870,13 @@ export declare class SamsarClient {
     } & SamsarRequestOptions): Promise<SamsarResult<ExternalRequestResponse>>;
     /**
      * Fetch the latest available render URL for a given video session id.
+     * Completed responses include result_url, has_subtitles, and result_language.
      * Maps to GET /video/fetch_latest_version?session_id={sessionId}.
      */
     fetchLatestVideoVersion(sessionId: string, options?: SamsarRequestOptions): Promise<SamsarResult<FetchLatestVideoVersionResponse>>;
     /**
      * List completed video sessions for the authenticated API key.
+     * Each item includes result_url plus session metadata such as has_subtitles and result_language.
      * Maps to GET /video/list_completed_video_sessions.
      */
     listCompletedVideoSessions(options?: SamsarRequestOptions & {
@@ -2001,6 +2082,7 @@ export declare class SamsarClient {
      * Retrieve the status of an asynchronous request by request_id.
      * Defaults to GET /status?request_id={requestId}, but the path can be overridden.
      * Normalizes the response to expose status/result_url for both image and video flows.
+     * Completed video responses can also include has_subtitles and result_language.
      */
     getStatus(requestId: string, options?: SamsarRequestOptions & {
         path?: string;

package/dist/index.js

@@ -216,6 +216,61 @@ function normalizeUpdateVideoOutroImageInput(input, context = 'updateVideoOutroI
         ...(rawOutroFocusArea !== undefined ? { outro_focust_area: rawOutroFocusArea } : {}),
     };
 }
+function normalizeUpdateVideoFooterImageInput(input, context = 'updateVideoFooterImage') {
+    const raw = input;
+    const videoSessionId = raw.videoSessionId ??
+        raw.video_session_id ??
+        raw.videoSessionID ??
+        raw.session_id ??
+        raw.sessionId ??
+        raw.sessionID ??
+        raw.request_id ??
+        raw.requestId ??
+        raw.source_request_id ??
+        raw.sourceRequestId ??
+        raw.external_request_id ??
+        raw.externalRequestId ??
+        raw.external_session_id ??
+        raw.externalSessionId;
+    const rawRemoveFooter = raw.remove_footer ??
+        raw.removeFooter;
+    const ctaText = raw.cta_text ??
+        raw.ctaText;
+    const ctaLogo = raw.cta_logo ??
+        raw.ctaLogo;
+    const ctaUrl = raw.cta_url ??
+        raw.ctaUrl;
+    const removeFooter = rawRemoveFooter === true;
+    if (!videoSessionId) {
+        throw new Error(`videoSessionId is required for ${context}`);
+    }
+    if (rawRemoveFooter !== undefined && typeof rawRemoveFooter !== 'boolean') {
+        throw new Error(`remove_footer must be a boolean for ${context}`);
+    }
+    if (ctaText !== undefined && typeof ctaText !== 'string') {
+        throw new Error(`cta_text must be a string for ${context}`);
+    }
+    if (ctaLogo !== undefined && typeof ctaLogo !== 'string') {
+        throw new Error(`cta_logo must be a string for ${context}`);
+    }
+    if (ctaUrl !== undefined && typeof ctaUrl !== 'string') {
+        throw new Error(`cta_url must be a string for ${context}`);
+    }
+    const normalizedCtaText = typeof ctaText === 'string' ? ctaText.trim() : '';
+    const normalizedCtaLogo = typeof ctaLogo === 'string' ? ctaLogo.trim() : '';
+    const normalizedCtaUrl = typeof ctaUrl === 'string' ? ctaUrl.trim() : '';
+    if (!removeFooter && !normalizedCtaText && !normalizedCtaLogo && !normalizedCtaUrl) {
+        throw new Error(`At least one of cta_text, cta_logo, or cta_url is required for ${context} unless remove_footer is true`);
+    }
+    return {
+        ...input,
+        videoSessionId: String(videoSessionId),
+        remove_footer: removeFooter,
+        ...(normalizedCtaText ? { cta_text: normalizedCtaText } : {}),
+        ...(normalizedCtaLogo ? { cta_logo: normalizedCtaLogo } : {}),
+        ...(normalizedCtaUrl ? { cta_url: normalizedCtaUrl } : {}),
+    };
+}
 function normalizeSessionPublicationInput(input, context) {
     if (typeof input !== 'string' && (!input || typeof input !== 'object' || Array.isArray(input))) {
         throw new Error(`input must be a session id or object for ${context}`);
@@ -452,6 +507,13 @@ export class SamsarClient {
             webhookUrl: options?.webhookUrl,
         }, options);
     }
+    async updateV2VideoFooterImage(input, options) {
+        const normalizedInput = normalizeUpdateVideoFooterImageInput(input, 'updateV2VideoFooterImage');
+        return this.postV2('update_footer_image', {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
     async addV2VideoOutroImage(input, options) {
         return this.postV2('add_outro_image', {
             input,
@@ -791,6 +853,51 @@ export class SamsarClient {
         }
         return response;
     }
+    /**
+     * Add subtitle/transcript text overlays by cloning an existing session and re-running
+     * transcription + frame + video generation on the new session.
+     */
+    async addSubtitles(input, options) {
+        const raw = input;
+        const videoSessionId = raw.videoSessionId ??
+            raw.video_session_id ??
+            raw.videoSessionID ??
+            raw.session_id ??
+            raw.sessionId ??
+            raw.sessionID ??
+            raw.request_id ??
+            raw.requestId;
+        if (!videoSessionId) {
+            throw new Error('videoSessionId is required for addSubtitles');
+        }
+        const body = {
+            input: {
+                ...input,
+                videoSessionId: String(videoSessionId),
+            },
+            webhookUrl: options?.webhookUrl,
+        };
+        const response = await this.post('video/add_subtitles', body, options);
+        const data = response.data;
+        if (data && typeof data === 'object') {
+            const sessionId = typeof data.sessionID === 'string'
+                ? data.sessionID
+                : typeof data.session_id === 'string'
+                    ? data.session_id
+                    : typeof data.request_id === 'string'
+                        ? data.request_id
+                        : undefined;
+            const normalizedSessionId = sessionId ? String(sessionId) : undefined;
+            const normalizedData = {
+                ...data,
+                sessionID: data.sessionID ?? normalizedSessionId ?? '',
+                session_id: data.session_id ?? normalizedSessionId,
+                request_id: data.request_id ?? normalizedSessionId,
+            };
+            return { ...response, data: normalizedData };
+        }
+        return response;
+    }
     /**
      * Cancel an in-progress render for an existing video session.
      */
@@ -878,6 +985,50 @@ export class SamsarClient {
         };
         return this.post('external_users/update_outro_image', body, options);
     }
+    /**
+     * Update or remove the footer for an existing video session by cloning it into a new session and
+     * re-running frame/video generation.
+     */
+    async updateVideoFooterImage(input, options) {
+        const normalizedInput = normalizeUpdateVideoFooterImageInput(input, 'updateVideoFooterImage');
+        const body = {
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        };
+        const response = await this.post('video/update_footer_image', body, options);
+        const data = response.data;
+        if (data && typeof data === 'object') {
+            const sessionId = typeof data.sessionID === 'string'
+                ? data.sessionID
+                : typeof data.session_id === 'string'
+                    ? data.session_id
+                    : typeof data.request_id === 'string'
+                        ? data.request_id
+                        : undefined;
+            const normalizedSessionId = sessionId ? String(sessionId) : undefined;
+            const normalizedData = {
+                ...data,
+                sessionID: data.sessionID ?? normalizedSessionId ?? '',
+                session_id: data.session_id ?? normalizedSessionId,
+                request_id: data.request_id ?? normalizedSessionId,
+            };
+            return { ...response, data: normalizedData };
+        }
+        return response;
+    }
+    /**
+     * Update or remove the footer for an external-user video request through
+     * /external_users/update_footer_image.
+     */
+    async updateExternalVideoFooterImage(externalUser, input, options) {
+        const normalizedInput = normalizeUpdateVideoFooterImageInput(input, 'updateExternalVideoFooterImage');
+        const body = {
+            external_user: normalizeExternalUserIdentity(externalUser),
+            input: normalizedInput,
+            webhookUrl: options?.webhookUrl,
+        };
+        return this.post('external_users/update_footer_image', body, options);
+    }
     /**
      * Add or replace the outro image for an existing video session by cloning it into a new session and
      * re-running frame/video generation.
@@ -1033,6 +1184,7 @@ export class SamsarClient {
     }
     /**
      * Fetch the latest available render URL for a given video session id.
+     * Completed responses include result_url, has_subtitles, and result_language.
      * Maps to GET /video/fetch_latest_version?session_id={sessionId}.
      */
     async fetchLatestVideoVersion(sessionId, options) {
@@ -1050,6 +1202,7 @@ export class SamsarClient {
     }
     /**
      * List completed video sessions for the authenticated API key.
+     * Each item includes result_url plus session metadata such as has_subtitles and result_language.
      * Maps to GET /video/list_completed_video_sessions.
      */
     async listCompletedVideoSessions(options) {
@@ -1581,6 +1734,7 @@ export class SamsarClient {
      * Retrieve the status of an asynchronous request by request_id.
      * Defaults to GET /status?request_id={requestId}, but the path can be overridden.
      * Normalizes the response to expose status/result_url for both image and video flows.
+     * Completed video responses can also include has_subtitles and result_language.
      */
     async getStatus(requestId, options) {
         if (!requestId) {

package/package.json

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