samsar-js 0.48.31 → 0.48.33

package/README.md

@@ -37,6 +37,10 @@ const video = await samsar.createVideoFromText(
     image_model: 'GPTIMAGE2',
     video_model: 'RUNWAYML',
     duration: 30,
+    backingtrack_model: 'LYRIA3',
+    tts_model: 'OPENAI',
+    speakerOptions: { openAISpeakers: ['nova'] },
+    inference_model: 'gpt-5.5',
     font_key: 'Poppins',
     enable_subtitles: true,
   },
@@ -67,6 +71,10 @@ const videoFromImages = await samsar.createVideoFromImageList(
     video_model: 'RUNWAYML',
     aspect_ratio: '16:9',
     language: 'en',
+    backingtrack_model: 'ELEVENLABS_MUSIC',
+    tts_model: 'ELEVENLABS',
+    speakerOptions: { elevenLabsSpeakers: ['EXAVITQu4vr4xnSDxMaL'] },
+    inference_model: 'gemini-3.1-pro',
     font_key: 'Poppins',
     enable_subtitles: true,
   },
@@ -330,14 +338,9 @@ await samsar.deleteEmbedding({
   source_id: '2',
 });
 
-// Remove branding/watermark
+// Remove visible text
 const cleaned = await samsar.removeBrandingFromImage({ image_url: 'https://example.com/photo.png' });
 
-// Replace branding/watermark (original image, replacement logo/image)
-const replaced = await samsar.replaceBrandingFromImage({
-  image_urls: ['https://example.com/photo.png', 'https://example.com/new-logo.png'],
-});
-
 // Extend image set
 const images = await samsar.extendImageList({
   image_urls: ['https://example.com/extra.jpg'],
@@ -578,10 +581,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 `HAPPYHORSEI2V`.
+- `createVideoFromText` image model keys include: `GPTIMAGE2`, `IMAGEN4`, `SEEDREAM`, `NANOBANANA2`, `NANOBANANAPRO`, `CUSTOM_TEXT_TO_IMAGE`.
+- `createVideoFromText` supports these video models: `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `COSMOS3SUPERI2V`, `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 `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` supports `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `COSMOS3SUPERI2V`, `SEEDANCEI2V`, `KLINGIMGTOVID3PRO`, and `HAPPYHORSEI2V` via `video_model`; if omitted, it defaults to `RUNWAYML`. It also accepts the same `image_model` keys as text-to-video. Use `aspect_ratio: '16:9'` or `'9:16'`; omitted or invalid values fall back to `16:9`.
+- Text and image-list video creation both accept optional `backingtrack_model` / `backing_track_model` / `backingTrackModel` / `music_provider` / `musicProvider`, `tts_model` / `ttsModel` / `tts_provider` / `ttsProvider`, `speakerOptions` / `speaker_options`, and `inference_model` / `inferenceModel`. The adapter normalizes these to `backingtrack_model`, `tts_model`, `speakerOptions`, and `inference_model` in the request payload. Omit `inference_model` to use the account default; supported request values are `gpt-5.5` and `gemini-3.1-pro`. When `tts_model` is set, Samsar limits assignment to the matching speaker list (`openAISpeakers`, `elevenLabsSpeakers`, or `googleSpeakers`; Google TTS requests should include `googleSpeakerDetails`).
+- `video_model_sub_type` is no longer used by the API and is stripped from text and image-list payloads before sending.
 - `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.

package/dist/index.d.ts

@@ -36,6 +36,36 @@ export interface FontOptions {
     language?: string;
     family?: string;
 }
+export type BackingTrackModel = 'LYRIA3' | 'LYRIA2' | 'ELEVENLABS_MUSIC' | 'Lyria 3' | 'Lyria 2' | 'ElevenLabs music' | string;
+export type TTSModel = 'ELEVENLABS' | 'OPENAI' | 'GOOGLE' | 'ElevenLabs' | 'OpenAI' | 'Google TTS' | string;
+export type InferenceModel = 'gpt-5.5' | 'GPT 5.5' | 'gemini-3.1-pro' | 'Gemini 3.1 Pro' | string;
+export interface GoogleTTSSpeakerDetail {
+    provider?: 'GOOGLE' | string;
+    value?: string;
+    voiceId?: string;
+    name?: string;
+    label?: string;
+    languageCode?: string;
+    languageCodes?: string[];
+    Gender?: 'M' | 'F' | '' | string | null;
+    gender?: string;
+    genderCode?: string;
+    ssmlGender?: string;
+    naturalSampleRateHertz?: number | null;
+    voiceType?: string;
+    previewRequiresAuth?: boolean;
+    [key: string]: unknown;
+}
+export interface TTSSpeakerOptions {
+    allowOpenAI?: boolean;
+    allowElevenLabs?: boolean;
+    allowGoogle?: boolean;
+    openAISpeakers?: string[];
+    elevenLabsSpeakers?: string[];
+    googleSpeakers?: string[];
+    googleSpeakerDetails?: GoogleTTSSpeakerDetail[];
+    [key: string]: unknown;
+}
 export type V2StepGenerationMode = 'one_step' | 'two_step';
 export interface V2StepGenerationOptions {
     auto_render_full_video?: boolean;
@@ -50,7 +80,19 @@ export interface CreateVideoFromTextInput extends V2StepGenerationOptions {
     duration: number;
     tone?: string;
     aspect_ratio?: string;
-    video_model_sub_type?: string;
+    backingtrack_model?: BackingTrackModel;
+    backing_track_model?: BackingTrackModel;
+    backingTrackModel?: BackingTrackModel;
+    music_provider?: BackingTrackModel;
+    musicProvider?: BackingTrackModel;
+    tts_model?: TTSModel;
+    ttsModel?: TTSModel;
+    tts_provider?: TTSModel;
+    ttsProvider?: TTSModel;
+    inference_model?: InferenceModel;
+    inferenceModel?: InferenceModel;
+    speakerOptions?: TTSSpeakerOptions;
+    speaker_options?: TTSSpeakerOptions;
     font_key?: string;
     fontKey?: string;
     subtitle_font?: string;
@@ -118,7 +160,7 @@ export interface FooterMetadataItem {
     footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
-export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'HAPPYHORSEI2V';
+export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'COSMOS3SUPERI2V' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'HAPPYHORSEI2V';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -155,6 +197,19 @@ export interface CreateVideoFromImageListInput extends V2StepGenerationOptions {
     aspectRatio?: ImageListToVideoAspectRatio;
     language?: string;
     languageString?: string | null;
+    backingtrack_model?: BackingTrackModel;
+    backing_track_model?: BackingTrackModel;
+    backingTrackModel?: BackingTrackModel;
+    music_provider?: BackingTrackModel;
+    musicProvider?: BackingTrackModel;
+    tts_model?: TTSModel;
+    ttsModel?: TTSModel;
+    tts_provider?: TTSModel;
+    ttsProvider?: TTSModel;
+    inference_model?: InferenceModel;
+    inferenceModel?: InferenceModel;
+    speakerOptions?: TTSSpeakerOptions;
+    speaker_options?: TTSSpeakerOptions;
     font_key?: string;
     fontKey?: string;
     subtitle_font?: string;
@@ -939,22 +994,6 @@ export interface RemoveBrandingFromImageResponse {
     remainingCredits?: number;
     [key: string]: unknown;
 }
-export interface ReplaceBrandingFromImageRequest {
-    image_urls: string[];
-}
-export interface ReplaceBrandingFromImageResponse {
-    status?: string;
-    message?: string;
-    request_id?: string;
-    session_id?: string;
-    global_status_id?: string;
-    case_type?: string;
-    image_urls: string[];
-    userId?: string;
-    creditsCharged?: number;
-    remainingCredits?: number;
-    [key: string]: unknown;
-}
 export interface EnhanceImageRequest {
     image_url: string;
     resolution?: '1k' | '2k' | '3k' | '4k';
@@ -1866,6 +1905,18 @@ export interface CreditsRechargeResponse {
     currency: string;
     [key: string]: unknown;
 }
+export interface V2CreditsRechargeRequest {
+    credits?: number;
+    credits_to_recharge?: number;
+    creditsToRecharge?: number;
+    [key: string]: unknown;
+}
+export interface V2CreditsGrantRequest {
+    credits?: number;
+    credits_to_grant?: number;
+    creditsToGrant?: number;
+    [key: string]: unknown;
+}
 export interface EnableAutoRechargeRequest {
     thresholdCredits?: number;
     amountUsd?: number;
@@ -1970,6 +2021,8 @@ export declare class SamsarClient {
     getV2<T = Record<string, unknown>>(path: string, options?: V2RequestOptions): Promise<SamsarResult<T>>;
     createV2Session(options?: V2RequestOptions): Promise<SamsarResult<V2SessionResponse>>;
     getV2Credits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse | ExternalCreditsBalanceResponse>>;
+    createV2CreditsRecharge(payload: number | V2CreditsRechargeRequest, options?: V2RequestOptions): Promise<SamsarResult<CreditsRechargeResponse | ExternalCreditsRechargeResponse>>;
+    grantV2Credits(payload: number | V2CreditsGrantRequest, options?: V2RequestOptions): Promise<SamsarResult<ExternalCreditsGrantResponse>>;
     getV2UserCredits(options?: V2RequestOptions): Promise<SamsarResult<CreditsBalanceResponse>>;
     getV2UserUsageLogs(options?: V2RequestOptions & {
         page?: number;
@@ -1986,6 +2039,7 @@ export declare class SamsarClient {
     refreshV2UserAppKey(payload?: V2UserAppKeyRefreshRequest, options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
     revokeV2UserAppKey(options?: V2RequestOptions): Promise<SamsarResult<V2UserAppKeyResponse>>;
     getV2UserPaymentStatus(payload: PaymentStatusRequest, options?: V2RequestOptions): Promise<SamsarResult<PaymentStatusResponse>>;
+    getV2PaymentStatus(payload: PaymentStatusRequest, options?: V2RequestOptions): Promise<SamsarResult<PaymentStatusResponse | ExternalPaymentStatusResponse>>;
     createV2LoginToken(options?: V2RequestOptions & {
         redirect?: string;
     }): Promise<SamsarResult<CreateLoginTokenResponse | ExternalCreateLoginTokenResponse>>;
@@ -2014,6 +2068,7 @@ export declare class SamsarClient {
     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>>;
+    joinV2Videos(input: JoinVideosInput, options?: V2RequestOptions): Promise<SamsarResult<JoinVideosResponse | ExternalRequestResponse>>;
     getV2Status(requestId: string, options?: V2RequestOptions & {
         queryParams?: QueryParams;
     }): Promise<SamsarResult<GlobalStatusResponse | ExternalStatusResponse>>;
@@ -2023,6 +2078,10 @@ export declare class SamsarClient {
     getV2DetailedStatus(requestId: string, options?: V2RequestOptions & {
         queryParams?: QueryParams;
     }): Promise<SamsarResult<GlobalStatusDetailedResponse | ExternalStatusDetailedResponse>>;
+    /**
+     * Cancel an in-progress v2 render for an existing video session.
+     */
+    cancelV2Render(input: CancelRenderInput, options?: V2RequestOptions): Promise<SamsarResult<CancelRenderResponse>>;
     /**
      * Create a new video generation job from text.
      */
@@ -2285,13 +2344,9 @@ export declare class SamsarClient {
      */
     getEmbeddingStatus(templateId: string, options?: SamsarRequestOptions): Promise<SamsarResult<EmbeddingStatusResponse>>;
     /**
-     * Remove branding/watermark from an image by URL.
+     * Remove visible text from an image by URL.
      */
     removeBrandingFromImage(payload: RemoveBrandingFromImageRequest, options?: SamsarRequestOptions): Promise<SamsarResult<RemoveBrandingFromImageResponse>>;
-    /**
-     * Replace branding/watermark on an image by providing the original and replacement image URLs.
-     */
-    replaceBrandingFromImage(payload: ReplaceBrandingFromImageRequest, options?: SamsarRequestOptions): Promise<SamsarResult<ReplaceBrandingFromImageResponse>>;
     /**
      * Enhance an image by upscaling it with the specified resolution.
      */

package/dist/index.js

@@ -137,6 +137,10 @@ function normalizeCreateVideoFromTextInput(input) {
         ['cta_logo', ['cta_logo', 'ctaLogo']],
         ['add_footer_animation', ['add_footer_animation', 'addFooterAnimation']],
         ['footer_metadata', ['footer_metadata', 'footerMetadata']],
+        ['backingtrack_model', ['backingtrack_model', 'backing_track_model', 'backingTrackModel', 'music_provider', 'musicProvider']],
+        ['tts_model', ['tts_model', 'ttsModel', 'tts_provider', 'ttsProvider']],
+        ['inference_model', ['inference_model', 'inferenceModel']],
+        ['speakerOptions', ['speakerOptions', 'speaker_options']],
         ['enable_subtitles', ['enable_subtitles', 'enableSubtitles']],
         ['font_key', ['font_key', 'fontKey']],
     ];
@@ -146,6 +150,8 @@ function normalizeCreateVideoFromTextInput(input) {
             normalized[canonicalName] = value;
         }
     }
+    delete normalized.video_model_sub_type;
+    delete normalized.videoModelSubType;
     assertOptionalBoolean(normalized.enable_subtitles, 'enable_subtitles', 'createVideoFromText');
     assertOptionalBoolean(normalized.add_outro_animation, 'add_outro_animation', 'createVideoFromText');
     assertOptionalBoolean(normalized.add_outro_focus_area, 'add_outro_focus_area', 'createVideoFromText');
@@ -193,6 +199,10 @@ function normalizeCreateVideoFromImageListInput(input) {
         ['cta_logo', ['cta_logo', 'ctaLogo']],
         ['add_footer_animation', ['add_footer_animation', 'addFooterAnimation']],
         ['footer_metadata', ['footer_metadata', 'footerMetadata']],
+        ['backingtrack_model', ['backingtrack_model', 'backing_track_model', 'backingTrackModel', 'music_provider', 'musicProvider']],
+        ['tts_model', ['tts_model', 'ttsModel', 'tts_provider', 'ttsProvider']],
+        ['inference_model', ['inference_model', 'inferenceModel']],
+        ['speakerOptions', ['speakerOptions', 'speaker_options']],
         ['limit_single_narrator', ['limit_single_narrator', 'limitSingleNarrator']],
         ['add_narrator_avatar', ['add_narrator_avatar', 'addNarratorAvatar']],
         ['enable_subtitles', ['enable_subtitles', 'enableSubtitles']],
@@ -204,6 +214,8 @@ function normalizeCreateVideoFromImageListInput(input) {
             normalized[canonicalName] = value;
         }
     }
+    delete normalized.video_model_sub_type;
+    delete normalized.videoModelSubType;
     assertOptionalBoolean(normalized.enable_subtitles, 'enable_subtitles');
     assertOptionalBoolean(normalized.add_outro_animation, 'add_outro_animation');
     assertOptionalBoolean(normalized.add_outro_focus_area, 'add_outro_focus_area');
@@ -557,6 +569,32 @@ export class SamsarClient {
     async getV2Credits(options) {
         return this.getV2('credits', options);
     }
+    async createV2CreditsRecharge(payload, options) {
+        const input = typeof payload === 'number' ? { credits: payload } : (payload ?? {});
+        const credits = Number(input.credits ?? input.credits_to_recharge ?? input.creditsToRecharge);
+        if (!Number.isFinite(credits) || credits <= 0 || !Number.isInteger(credits)) {
+            throw new Error('credits must be a positive integer');
+        }
+        return this.postV2('credits/recharge', {
+            input: {
+                ...input,
+                credits,
+            },
+        }, options);
+    }
+    async grantV2Credits(payload, options) {
+        const input = typeof payload === 'number' ? { credits: payload } : (payload ?? {});
+        const credits = Number(input.credits ?? input.credits_to_grant ?? input.creditsToGrant);
+        if (!Number.isFinite(credits) || credits <= 0 || !Number.isInteger(credits)) {
+            throw new Error('credits must be a positive integer');
+        }
+        return this.postV2('credits/grant', {
+            input: {
+                ...input,
+                credits,
+            },
+        }, options);
+    }
     async getV2UserCredits(options) {
         return this.getV2('user/credits', options);
     }
@@ -689,6 +727,24 @@ export class SamsarClient {
             query,
         });
     }
+    async getV2PaymentStatus(payload, options) {
+        const query = {
+            ...(options?.query ?? {}),
+        };
+        if (payload?.checkoutSessionId) {
+            query.checkoutSessionId = payload.checkoutSessionId;
+        }
+        if (payload?.paymentIntentId) {
+            query.paymentIntentId = payload.paymentIntentId;
+        }
+        if (payload?.setupIntentId) {
+            query.setupIntentId = payload.setupIntentId;
+        }
+        return this.getV2('payment_status', {
+            ...(options ?? {}),
+            query,
+        });
+    }
     async createV2LoginToken(options) {
         const body = options?.redirect ? { redirect: options.redirect } : {};
         return this.postV2('create_login_token', body, options);
@@ -828,6 +884,22 @@ export class SamsarClient {
             webhookUrl: options?.webhookUrl,
         }, options);
     }
+    async joinV2Videos(input, options) {
+        const rawIds = input.session_ids ?? input.sessionIds ?? input.video_session_ids ?? input.videoSessionIds;
+        const sessionIds = Array.isArray(rawIds)
+            ? rawIds.map((value) => (typeof value === 'string' ? value.trim() : '')).filter(Boolean)
+            : [];
+        if (sessionIds.length < 2) {
+            throw new Error('at least two session IDs are required for joinV2Videos');
+        }
+        return this.postV2('join_videos', {
+            input: {
+                ...input,
+                session_ids: sessionIds,
+            },
+            webhookUrl: options?.webhookUrl,
+        }, options);
+    }
     async getV2Status(requestId, options) {
         const queryParams = {
             ...(options?.externalUser
@@ -857,6 +929,48 @@ export class SamsarClient {
     async getV2DetailedStatus(requestId, options) {
         return this.getV2StatusDetailed(requestId, options);
     }
+    /**
+     * Cancel an in-progress v2 render for an existing video session.
+     */
+    async cancelV2Render(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 cancelV2Render');
+        }
+        const response = await this.postV2('cancel_render', {
+            input: {
+                ...input,
+                videoSessionId: String(videoSessionId),
+            },
+        }, 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;
+    }
     /**
      * Create a new video generation job from text.
      */
@@ -1757,17 +1871,11 @@ export class SamsarClient {
         });
     }
     /**
-     * Remove branding/watermark from an image by URL.
+     * Remove visible text from an image by URL.
      */
     async removeBrandingFromImage(payload, options) {
         return this.post('image/remove_branding', payload, options);
     }
-    /**
-     * Replace branding/watermark on an image by providing the original and replacement image URLs.
-     */
-    async replaceBrandingFromImage(payload, options) {
-        return this.post('image/replace_branding', payload, options);
-    }
     /**
      * Enhance an image by upscaling it with the specified resolution.
      */

package/package.json

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