samsar-js 0.48.14 → 0.48.16

package/README.md

@@ -34,11 +34,11 @@ const samsar = new SamsarClient({ apiKey: process.env.SAMSAR_API_KEY! });
 const video = await samsar.createVideoFromText(
   {
     prompt: 'A drone shot of a beach at sunrise',
-    image_model: 'GPTIMAGE1',
+    image_model: 'GPTIMAGE2',
     video_model: 'RUNWAYML',
     duration: 30,
     font_key: 'Poppins',
-    enable_subtitles: false,
+    enable_subtitles: true,
   },
   { webhookUrl: 'https://example.com/webhook' },
 );
@@ -49,13 +49,48 @@ const videoFromImages = await samsar.createVideoFromImageList(
     image_urls: ['https://example.com/a.jpg', 'https://example.com/b.jpg'],
     prompt: 'Cinematic sequence with smooth transitions',
     metadata: { project: 'demo' },
+    video_model: 'RUNWAYML',
+    aspect_ratio: '16:9',
     language: 'en',
     font_key: 'Poppins',
-    enable_subtitles: false,
+    enable_subtitles: true,
   },
   { webhookUrl: 'https://example.com/webhook' },
 );
 
+// Create a video with a provided outro image
+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',
+  aspect_ratio: '16:9',
+  outro_image_url: 'https://cdn.example.com/outro.png',
+  add_outro_animation: true,
+  add_outro_focus_area: true,
+  outro_focust_area: { x: 680, y: 296, width: 432, height: 432 },
+});
+
+// Create a video and generate the QR outro server-side from the input images
+await samsar.createVideoFromImageList({
+  image_urls: [
+    { image_url: 'https://example.com/a.jpg', title: 'Blue Lagoon Tour' },
+    { image_url: 'https://example.com/b.jpg', title: 'Sunset Dinner' },
+  ],
+  prompt: 'Travel offer reel with a scannable booking outro',
+  video_model: 'RUNWAYML',
+  aspect_ratio: '9:16',
+  generate_outro_image: true,
+  cta_url: 'https://example.com/book',
+  cta_text_top: 'Scan to book',
+  cta_text_bottom: 'Limited availability',
+  cta_logo: 'https://cdn.example.com/logo-white.png',
+  add_footer_animation: true,
+  footer_metadata: [
+    { url: 'https://example.com/blue-lagoon', title: 'Blue Lagoon Tour' },
+    { url: 'https://example.com/sunset-dinner', title: 'Sunset Dinner' },
+  ],
+});
+
 // Translate an existing video session into another language
 const translated = await samsar.translateVideo(
   {
@@ -217,7 +252,9 @@ const replaced = await samsar.replaceBrandingFromImage({
 // Extend image set
 const images = await samsar.extendImageList({
   image_urls: ['https://example.com/extra.jpg'],
+  prompt: 'Create a cinematic travel header banner',
   num_images: 4,
+  aspect_ratio: '16:9',
 });
 
 // Create a reusable receipt template from one sample receipt image (free endpoint)
@@ -322,7 +359,7 @@ await platform.setExternalAssistantSystemPrompt(
 // Create a render attributed to that external user
 const externalRender = await platform.createExternalVideoFromText(externalUser, {
   prompt: 'A sleek teaser for a futuristic running shoe',
-  image_model: 'GPTIMAGE1',
+  image_model: 'GPTIMAGE2',
   video_model: 'RUNWAYML',
   duration: 10,
   enable_subtitles: true,
@@ -389,9 +426,12 @@ console.log(externalLibrary.data.requests.map((request) => request.request_id));
 ```
 
 Video model support notes:
-- `createVideoFromText` image model keys include: `GPTIMAGE1`, `IMAGEN4`, `SEEDREAM`, `HUNYUAN`, `NANOBANANA2`.
-- `createVideoFromText` supports all express video models: `RUNWAYML`, `KLINGIMGTOVID3PRO`, `HAILUO`, `HAILUOPRO`, `SEEDANCEI2V`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `SORA2`, `SORA2PRO`.
-- `createVideoFromImageList` uses a fixed Veo2.1 pipeline model (`VEO3.1I2V`) and does not accept a `video_model` override.
+- `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`.
+- `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` 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.
+- 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.
 
 Each method returns `{ data, status, headers, creditsCharged, creditsRemaining, raw }`. Non-2xx responses throw `SamsarRequestError` containing status, body, and credit headers (if present).
 

package/dist/index.d.ts

@@ -64,6 +64,12 @@ export interface OutroFocusArea {
     width: number;
     height: number;
 }
+export interface FooterMetadataItem {
+    url: string;
+    title?: string;
+}
+export type ImageListToVideoAspectRatio = '16:9' | '9:16';
+export type ImageListToVideoModel = 'VEO3.1I2V' | 'SEEDANCEI2V' | 'KLING3.0' | 'KLINGIMGTOVID3PRO' | 'RUNWAYML';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -79,12 +85,25 @@ export interface ImageListToVideoItem {
     fromEnhancedList?: boolean;
     skip_enhancement?: boolean;
     skipEnhancement?: boolean;
+    source?: string;
+    title?: string;
+    image_title?: string;
+    imageTitle?: string;
+    image_text?: string;
+    imageText?: string;
+    activity_title?: string;
+    activityTitle?: string;
+    name?: string;
+    label?: string;
     [key: string]: unknown;
 }
 export interface CreateVideoFromImageListInput {
     image_urls: Array<string | ImageListToVideoItem>;
     metadata?: Record<string, unknown>;
     prompt?: string;
+    video_model?: ImageListToVideoModel;
+    aspect_ratio?: ImageListToVideoAspectRatio;
+    aspectRatio?: ImageListToVideoAspectRatio;
     language?: string;
     languageString?: string | null;
     font_key?: string;
@@ -98,9 +117,29 @@ export interface CreateVideoFromImageListInput {
     sessionId?: string;
     sessionID?: string;
     outro_image_url?: string;
+    outroImageUrl?: string;
     add_outro_animation?: boolean;
+    addOutroAnimation?: boolean;
     add_outro_focus_area?: boolean;
+    addOutroFocusArea?: boolean;
     outro_focust_area?: OutroFocusArea | null;
+    outro_focus_area?: OutroFocusArea | null;
+    outroFocustArea?: OutroFocusArea | null;
+    outroFocusArea?: OutroFocusArea | null;
+    generate_outro_image?: boolean;
+    generateOutroImage?: boolean;
+    cta_url?: string;
+    ctaUrl?: string;
+    cta_text_top?: string;
+    ctaTextTop?: string;
+    cta_text_bottom?: string;
+    ctaTextBottom?: string;
+    cta_logo?: string;
+    ctaLogo?: string;
+    add_footer_animation?: boolean;
+    addFooterAnimation?: boolean;
+    footer_metadata?: FooterMetadataItem[];
+    footerMetadata?: FooterMetadataItem[];
     [key: string]: unknown;
 }
 export interface TranscriptBuilderPayload {
@@ -688,6 +727,7 @@ export interface ExtendImageListRequest {
     num_images: number;
     prompt?: string;
     metadata?: Record<string, unknown>;
+    aspect_ratio?: string;
 }
 export interface ExtendImageListResponse {
     status?: string;
@@ -700,6 +740,7 @@ export interface ExtendImageListResponse {
     metadata?: Record<string, unknown>;
     prompt?: string;
     num_images?: number;
+    aspect_ratio?: string;
     userId?: string;
     creditsCharged?: number;
     remainingCredits?: number;

package/dist/index.js

@@ -15,6 +15,72 @@ export class SamsarRequestError extends Error {
         this.creditsRemaining = init.creditsRemaining;
     }
 }
+function resolveAliasedInputValue(raw, aliases, canonicalName) {
+    let resolved;
+    let hasResolved = false;
+    for (const alias of aliases) {
+        const value = raw[alias];
+        if (value === undefined) {
+            continue;
+        }
+        if (!hasResolved) {
+            resolved = value;
+            hasResolved = true;
+            continue;
+        }
+        if (value !== resolved) {
+            throw new Error(`${canonicalName} was provided with conflicting alias values.`);
+        }
+    }
+    return hasResolved ? resolved : undefined;
+}
+function assertOptionalBoolean(value, fieldName) {
+    if (value !== undefined && typeof value !== 'boolean') {
+        throw new Error(`${fieldName} must be a boolean for createVideoFromImageList`);
+    }
+}
+function normalizeCreateVideoFromImageListInput(input) {
+    const raw = input;
+    if (!Array.isArray(input.image_urls) || input.image_urls.length === 0) {
+        throw new Error('image_urls must be a non-empty array for createVideoFromImageList');
+    }
+    const normalized = { ...input };
+    const aliases = [
+        ['session_id', ['session_id', 'sessionId', 'sessionID']],
+        ['aspect_ratio', ['aspect_ratio', 'aspectRatio']],
+        ['outro_image_url', ['outro_image_url', 'outroImageUrl']],
+        ['add_outro_animation', ['add_outro_animation', 'addOutroAnimation']],
+        ['add_outro_focus_area', ['add_outro_focus_area', 'addOutroFocusArea']],
+        ['outro_focust_area', ['outro_focust_area', 'outro_focus_area', 'outroFocustArea', 'outroFocusArea']],
+        ['generate_outro_image', ['generate_outro_image', 'generateOutroImage']],
+        ['cta_url', ['cta_url', 'ctaUrl']],
+        ['cta_text_top', ['cta_text_top', 'ctaTextTop']],
+        ['cta_text_bottom', ['cta_text_bottom', 'ctaTextBottom']],
+        ['cta_logo', ['cta_logo', 'ctaLogo']],
+        ['enable_subtitles', ['enable_subtitles', 'enableSubtitles']],
+        ['font_key', ['font_key', 'fontKey']],
+    ];
+    for (const [canonicalName, aliasList] of aliases) {
+        const value = resolveAliasedInputValue(raw, aliasList, canonicalName);
+        if (value !== undefined) {
+            normalized[canonicalName] = value;
+        }
+    }
+    assertOptionalBoolean(normalized.enable_subtitles, 'enable_subtitles');
+    assertOptionalBoolean(normalized.add_outro_animation, 'add_outro_animation');
+    assertOptionalBoolean(normalized.add_outro_focus_area, 'add_outro_focus_area');
+    assertOptionalBoolean(normalized.generate_outro_image, 'generate_outro_image');
+    if (normalized.generate_outro_image === true) {
+        const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
+        if (!ctaUrl) {
+            throw new Error('cta_url is required when generate_outro_image is true for createVideoFromImageList');
+        }
+    }
+    else if (normalized.add_outro_focus_area === true && normalized.add_outro_animation !== true) {
+        throw new Error('add_outro_focus_area requires add_outro_animation to be true for createVideoFromImageList');
+    }
+    return normalized;
+}
 export class SamsarClient {
     constructor(options) {
         if (!options?.apiKey) {
@@ -44,8 +110,9 @@ export class SamsarClient {
      * Create a video from a list of image URLs with optional prompt/metadata via the image_list_to_video route.
      */
     async createVideoFromImageList(input, options) {
+        const normalizedInput = normalizeCreateVideoFromImageListInput(input);
         const body = {
-            input,
+            input: normalizedInput,
             webhookUrl: options?.webhookUrl,
         };
         const response = await this.post('video/image_list_to_video', body, options);
@@ -99,9 +166,10 @@ export class SamsarClient {
      * Create an image-list-to-video request attributed to an external user while billing against the shared API key.
      */
     async createExternalVideoFromImageList(externalUser, input, options) {
+        const normalizedInput = normalizeCreateVideoFromImageListInput(input);
         const body = {
             external_user: normalizeExternalUserIdentity(externalUser),
-            input,
+            input: normalizedInput,
             webhookUrl: options?.webhookUrl,
         };
         return this.post('external_users/image_list_to_video', body, options);

package/package.json

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