samsar-js 0.48.29 → 0.48.31

package/README.md

@@ -107,6 +107,20 @@ await samsar.createVideoFromImageList({
   ],
 });
 
+// Create the same generated QR outro and per-scene footer CTAs from one CTA link
+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 concise scene CTAs',
+  metadata: { brand: 'Guidestination', offer: 'Bookable Bangkok experiences' },
+  video_model: 'RUNWAYML',
+  aspect_ratio: '9:16',
+  express_cta_generation: true,
+  cta_url: 'https://example.com/book',
+});
+
 // Update an existing outro with a new provided outro image URL
 await samsar.updateVideoOutroImage(
   {
@@ -332,6 +346,24 @@ const images = await samsar.extendImageList({
   aspect_ratio: '16:9',
 });
 
+// Assign a short SEO-friendly image title
+const imageTitle = await samsar.assignImageTitle({
+  image_url: 'https://example.com/product-photo.png',
+  metadata: {
+    product: 'linen travel shirt',
+    collection: 'spring essentials',
+  },
+});
+console.log(imageTitle.data.content); // "Linen Travel Shirt"
+
+// Binary uploads are also supported in browser/Node 18+ runtimes
+const fileTitle = await samsar.assignImageTitle({
+  image: fileOrBlob,
+  fileName: 'product-photo.png',
+  mimeType: 'image/png',
+  metadata: { product: 'linen travel shirt' },
+});
+
 // Create a reusable receipt template from one sample receipt image (free endpoint)
 const receiptTemplate = await samsar.createReceiptTemplate({
   image_url: 'https://example.com/receipt-template.png',
@@ -547,11 +579,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 `CUSTOM_IMAGE_TO_VIDEO`.
+- `createVideoFromText` supports these video models: `RUNWAYML`, `VEO3.1I2V`, `VEO3.1I2VFAST`, `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 `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` 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` 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.
 - `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.
@@ -559,13 +592,13 @@ Video model support notes:
 - 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.
-- 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.
+- 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, `HAPPYHORSEI2V` 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; express CTA generation adds 1 credit/sec when `express_cta_generation` 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, video as the model-specific remainder, and `optionalAddons.express_cta_generation` at 1 credit/sec.
 
 Upcoming `/v2` omni route adapters:
 - `/v2` is additive; `/v1` is not deprecated.
-- `createV2VideoFromText`, `createV2VideoFromImageList`, `translateV2Video`, `cloneV2Video`, `regenerateV2VideoAvatar`, `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`.
+- `createV2VideoFromText`, `createV2VideoFromImageList`, `assignV2ImageTitle`, `translateV2Video`, `cloneV2Video`, `regenerateV2VideoAvatar`, `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`. They default to 1-step express rendering by sending `auto_render_full_video: true` and `manual_step_stages: []`; pass `{ stepMode: 'two_step' }` or `manual_step_stages: ['ai_video_generation']` to require an explicit second-step approval before image-to-video generation.
 - 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.
@@ -574,9 +607,8 @@ Upcoming `/v2` omni route adapters:
 const v2Video = await platform.createV2VideoFromImageList({
   image_urls: ['https://cdn.example.com/a.png', 'https://cdn.example.com/b.png'],
   video_model: 'RUNWAYML',
-  generate_outro_image: true,
+  express_cta_generation: true,
   cta_url: 'https://example.com/book',
-  cta_text_top: 'Scan to book',
 });
 
 const v2ExternalVideo = await platform.createV2VideoFromImageList(
@@ -587,6 +619,12 @@ const v2ExternalVideo = await platform.createV2VideoFromImageList(
   { externalUser },
 );
 
+const v2ImageTitle = await platform.assignV2ImageTitle({
+  image_url: 'https://cdn.example.com/product-frame.png',
+  metadata: { product: 'travel shirt', channel: 'marketplace' },
+});
+console.log(v2ImageTitle.data.content);
+
 const v2Translated = await platform.translateV2Video({
   videoSessionId: v2Video.data.request_id!,
   language: 'es',
@@ -610,7 +648,7 @@ 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`:
+Step video generation defaults to a 1-step express render, so it does not pause before image-to-video generation:
 
 ```ts
 const stepVideo = await platform.createV2StepVideoFromText({
@@ -622,12 +660,28 @@ const stepVideo = await platform.createV2StepVideoFromText({
   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 stepDetailed = await platform.getV2StepVideoStatusDetailed(stepVideo.data.request_id);
+console.log(stepDetailed.data.session?.previewStage, stepDetailed.data.session?.layers?.[0]?.preview?.url);
+```
+
+Use 2-step mode only when you want to review generated image/audio assets before starting the image-to-video stage:
+
+```ts
+const twoStepVideo = 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,
+  },
+  { stepMode: 'two_step' },
+);
+
+let stepStatus = await platform.getV2StepVideoStatus(twoStepVideo.data.request_id);
+if (stepStatus.data.waiting_for_process_next || stepStatus.data.can_process_next) {
+  stepStatus = await platform.processNextV2StepVideo(twoStepVideo.data.request_id);
 }
 
 const stepImageVideo = await platform.createV2StepVideoFromImage({

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

@@ -9,7 +9,12 @@ export declare const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND: {
 export type ExpressVideoPricingDistribution = typeof EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND & {
     video: number;
     total: number;
+    optionalAddons: ExpressVideoOptionalAddons;
 };
+export declare const EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND: {
+    readonly express_cta_generation: 1;
+};
+export type ExpressVideoOptionalAddons = typeof EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND;
 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;
@@ -17,6 +22,7 @@ export declare const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL: {
     readonly SEEDANCEI2V: 30;
     readonly KLINGIMGTOVID3PRO: 36;
     readonly KLINGIMGTOVIDTURBO: 36;
+    readonly HAPPYHORSEI2V: 36;
     readonly RUNWAYML: 30;
 };
 export declare const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL: Record<string, ExpressVideoPricingDistribution>;

package/dist/express-video-pricing.js

@@ -6,6 +6,9 @@ export const EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND = {
     music: 2,
     effects_and_lipsync: 2,
 };
+export const EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND = {
+    express_cta_generation: 1,
+};
 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,
@@ -13,6 +16,7 @@ export const EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL = {
     SEEDANCEI2V: 30,
     KLINGIMGTOVID3PRO: 36,
     KLINGIMGTOVIDTURBO: 36,
+    HAPPYHORSEI2V: 36,
     RUNWAYML: 30,
 };
 export const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL = Object.fromEntries(Object.entries(EXPRESS_VIDEO_CREDITS_PER_SECOND_BY_MODEL)
@@ -22,6 +26,7 @@ export const EXPRESS_VIDEO_PRICING_DISTRIBUTION_PER_SECOND_BY_MODEL = Object.fro
         ...EXPRESS_VIDEO_FIXED_PRICING_COMPONENTS_PER_SECOND,
         video: total - EXPRESS_VIDEO_FIXED_COMPONENTS_TOTAL_PER_SECOND,
         total,
+        optionalAddons: EXPRESS_VIDEO_OPTIONAL_ADDON_CREDITS_PER_SECOND,
     },
 ]));
 export function getExpressVideoCreditsPerSecond(model) {

package/dist/index.d.ts

@@ -36,7 +36,14 @@ export interface FontOptions {
     language?: string;
     family?: string;
 }
-export interface CreateVideoFromTextInput {
+export type V2StepGenerationMode = 'one_step' | 'two_step';
+export interface V2StepGenerationOptions {
+    auto_render_full_video?: boolean;
+    autoRenderFullVideo?: boolean;
+    manual_step_stages?: Array<V2StepVideoStage | string>;
+    manualStepStages?: Array<V2StepVideoStage | string>;
+}
+export interface CreateVideoFromTextInput extends V2StepGenerationOptions {
     prompt: string;
     image_model: string;
     video_model: string;
@@ -111,7 +118,7 @@ export interface FooterMetadataItem {
     footerLogoImagePath?: string;
 }
 export type ImageListToVideoAspectRatio = '16:9' | '9:16';
-export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'CUSTOM_IMAGE_TO_VIDEO';
+export type ImageListToVideoModel = 'RUNWAYML' | 'VEO3.1I2V' | 'VEO3.1I2VFAST' | 'SEEDANCEI2V' | 'KLINGIMGTOVID3PRO' | 'HAPPYHORSEI2V';
 export interface ImageListToVideoItem {
     image_url?: string;
     imageUrl?: string;
@@ -139,7 +146,7 @@ export interface ImageListToVideoItem {
     label?: string;
     [key: string]: unknown;
 }
-export interface CreateVideoFromImageListInput {
+export interface CreateVideoFromImageListInput extends V2StepGenerationOptions {
     image_urls: Array<string | ImageListToVideoItem>;
     metadata?: Record<string, unknown>;
     prompt?: string;
@@ -172,6 +179,12 @@ export interface CreateVideoFromImageListInput {
     outroFocusArea?: OutroFocusArea | null;
     generate_outro_image?: boolean;
     generateOutroImage?: boolean;
+    express_cta_generation?: boolean;
+    expressCtaGeneration?: boolean;
+    auto_generate_cta_text?: boolean;
+    autoGenerateCtaText?: boolean;
+    generate_cta_texts?: boolean;
+    generateCtaTexts?: boolean;
     cta_url?: string;
     ctaUrl?: string;
     cta_text_top?: string;
@@ -962,6 +975,33 @@ export interface EnhanceImageResponse {
     remainingCredits?: number;
     [key: string]: unknown;
 }
+export type AssignImageTitleMimeType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+export type AssignImageTitleBinaryInput = Blob | ArrayBuffer | Uint8Array;
+export interface AssignImageTitleRequest {
+    image?: string | AssignImageTitleBinaryInput;
+    file?: AssignImageTitleBinaryInput;
+    image_file?: AssignImageTitleBinaryInput;
+    imageFile?: AssignImageTitleBinaryInput;
+    image_url?: string;
+    imageUrl?: string;
+    url?: string;
+    image_data?: string;
+    imageData?: string;
+    image_data_url?: string;
+    imageDataUrl?: string;
+    metadata?: Record<string, unknown> | string;
+    metadata_json?: Record<string, unknown> | string;
+    metadataJson?: Record<string, unknown> | string;
+    fileName?: string;
+    filename?: string;
+    mimeType?: AssignImageTitleMimeType | string;
+    [key: string]: unknown;
+}
+export interface AssignImageTitleResponse {
+    content: string;
+    title?: string;
+    [key: string]: unknown;
+}
 export interface ExtendImageListRequest {
     image_urls: string[];
     num_images: number;
@@ -1411,6 +1451,9 @@ export interface V2RequestOptions extends SamsarRequestOptions {
     externalUser?: V2ExternalUserIdentity | null;
     webhookUrl?: string;
 }
+export interface V2StepVideoRequestOptions extends V2RequestOptions, V2StepGenerationOptions {
+    stepMode?: V2StepGenerationMode;
+}
 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 {
@@ -1541,7 +1584,11 @@ export interface V2StepVideoState {
     current_step?: V2StepVideoStage | string | null;
     current_step_label?: string | null;
     next_step?: V2StepVideoStage | string | null;
+    manual_step_stages?: Array<V2StepVideoStage | string>;
+    auto_advance_step_stages?: Array<V2StepVideoStage | string>;
     waiting_for_process_next?: boolean;
+    requires_user_action?: boolean;
+    can_process_next?: boolean;
     updated_at?: string | null;
     [key: string]: unknown;
 }
@@ -1944,10 +1991,10 @@ 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>>;
+    createV2StepVideoFromText(input: CreateVideoFromTextInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepTextToVideo(input: CreateVideoFromTextInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepVideoFromImage(input: CreateV2StepImageToVideoInput, options?: V2StepVideoRequestOptions): Promise<SamsarResult<V2StepVideoCreateResponse>>;
+    createV2StepImageToVideo(input: CreateV2StepImageToVideoInput, options?: V2StepVideoRequestOptions): 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>>;
@@ -1958,6 +2005,12 @@ export declare class SamsarClient {
     uploadV2ImageData(imageData: string[], options?: V2RequestOptions): Promise<SamsarResult<{
         image_urls: string[];
     }>>;
+    /**
+     * Assign a short SEO-friendly title to an image using the /v2 image route.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    assignV2ImageTitle(payload: AssignImageTitleRequest | FormData, options?: V2RequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
+    assignV2TitleToImage(payload: AssignImageTitleRequest | FormData, options?: V2RequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
     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>>;
@@ -2243,6 +2296,12 @@ export declare class SamsarClient {
      * Enhance an image by upscaling it with the specified resolution.
      */
     enhanceImage(payload: EnhanceImageRequest, options?: SamsarRequestOptions): Promise<SamsarResult<EnhanceImageResponse>>;
+    /**
+     * Assign a short SEO-friendly title to an image.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    assignImageTitle(payload: AssignImageTitleRequest | FormData, options?: SamsarRequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
+    assignTitleToImage(payload: AssignImageTitleRequest | FormData, options?: SamsarRequestOptions): Promise<SamsarResult<AssignImageTitleResponse>>;
     /**
      * Add or extend a saved image list for the authenticated API key.
      */
@@ -2359,6 +2418,7 @@ export declare class SamsarClient {
     }): Promise<SamsarResult<GlobalStatusResponse>>;
     private get;
     private post;
+    private postForm;
     private request;
     private buildHeaders;
     private buildUrl;

package/dist/index.js

@@ -4,6 +4,7 @@ const DEBUG = (() => {
     const env = globalThis?.process?.env;
     return env?.SAMSAR_SDK_DEBUG === '1';
 })();
+const DEFAULT_V2_STEP_MANUAL_STAGES = ['ai_video_generation'];
 export class SamsarRequestError extends Error {
     constructor(message, init) {
         super(message);
@@ -40,6 +41,85 @@ function assertOptionalBoolean(value, fieldName, context = 'createVideoFromImage
         throw new Error(`${fieldName} must be a boolean for ${context}`);
     }
 }
+function getFirstDefinedInputValue(raw, aliases) {
+    for (const alias of aliases) {
+        if (Object.prototype.hasOwnProperty.call(raw, alias)) {
+            return raw[alias];
+        }
+    }
+    return undefined;
+}
+function normalizeV2StepGenerationMode(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase().replace(/\s+/g, '_');
+    if (['one_step', 'one-step', '1_step', '1-step', 'express', 'auto', 'automatic'].includes(normalized)) {
+        return 'one_step';
+    }
+    if (['two_step', 'two-step', '2_step', '2-step', 'manual'].includes(normalized)) {
+        return 'two_step';
+    }
+    return null;
+}
+function normalizeV2StepBoolean(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    throw new Error(`${fieldName} must be a boolean for step video generation`);
+}
+function normalizeV2ManualStepStages(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === false || value === null) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value
+            .filter((stage) => typeof stage === 'string' && stage.trim().length > 0)
+            .map((stage) => stage.trim());
+    }
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map((stage) => stage.trim())
+            .filter(Boolean);
+    }
+    if (typeof value === 'object') {
+        return Object.entries(value)
+            .filter(([, enabled]) => enabled === true || enabled === 'true' || enabled === 1 || enabled === '1')
+            .map(([stage]) => stage.trim())
+            .filter(Boolean);
+    }
+    throw new Error('manual_step_stages must be an array, comma-separated string, stage map, null, or false');
+}
+function buildV2StepGenerationFields(input, options) {
+    const optionRecord = (options ?? {});
+    const stepMode = normalizeV2StepGenerationMode(optionRecord.stepMode);
+    const optionAutoRender = normalizeV2StepBoolean(getFirstDefinedInputValue(optionRecord, ['auto_render_full_video', 'autoRenderFullVideo']), 'auto_render_full_video');
+    const inputAutoRender = normalizeV2StepBoolean(getFirstDefinedInputValue(input, ['auto_render_full_video', 'autoRenderFullVideo']), 'auto_render_full_video');
+    const optionManualStages = normalizeV2ManualStepStages(getFirstDefinedInputValue(optionRecord, ['manual_step_stages', 'manualStepStages']));
+    const inputManualStages = normalizeV2ManualStepStages(getFirstDefinedInputValue(input, ['manual_step_stages', 'manualStepStages']));
+    let autoRenderFullVideo = stepMode ? stepMode === 'one_step' : optionAutoRender ?? inputAutoRender;
+    if (autoRenderFullVideo === undefined) {
+        autoRenderFullVideo = optionManualStages !== undefined || inputManualStages !== undefined
+            ? false
+            : true;
+    }
+    const manualStepStages = autoRenderFullVideo
+        ? []
+        : optionManualStages ?? inputManualStages ?? [...DEFAULT_V2_STEP_MANUAL_STAGES];
+    return {
+        auto_render_full_video: autoRenderFullVideo,
+        autoRenderFullVideo,
+        manual_step_stages: manualStepStages,
+        manualStepStages: manualStepStages,
+    };
+}
 function normalizeCreateVideoFromTextInput(input) {
     const raw = input;
     const normalized = { ...input };
@@ -96,6 +176,17 @@ function normalizeCreateVideoFromImageListInput(input) {
         ['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']],
+        [
+            'express_cta_generation',
+            [
+                'express_cta_generation',
+                'expressCtaGeneration',
+                'auto_generate_cta_text',
+                'autoGenerateCtaText',
+                'generate_cta_texts',
+                'generateCtaTexts',
+            ],
+        ],
         ['cta_url', ['cta_url', 'ctaUrl']],
         ['cta_text_top', ['cta_text_top', 'ctaTextTop']],
         ['cta_text_bottom', ['cta_text_bottom', 'ctaTextBottom']],
@@ -117,12 +208,24 @@ function normalizeCreateVideoFromImageListInput(input) {
     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');
+    assertOptionalBoolean(normalized.express_cta_generation, 'express_cta_generation');
     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.express_cta_generation === true) {
+        const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
+        if (!ctaUrl) {
+            throw new Error('cta_url is required when express_cta_generation is true for createVideoFromImageList');
+        }
+        normalized.cta_url = ctaUrl;
+        normalized.generate_outro_image = true;
+        normalized.add_outro_animation = true;
+        normalized.add_outro_focus_area = true;
+        normalized.add_footer_animation = true;
+    }
     if (normalized.generate_outro_image === true) {
         const ctaUrl = typeof normalized.cta_url === 'string' ? normalized.cta_url.trim() : '';
         if (!ctaUrl) {
@@ -606,8 +709,13 @@ export class SamsarClient {
     }
     async createV2StepVideoFromText(input, options) {
         const normalizedInput = normalizeCreateVideoFromTextInput(input);
+        const stepGenerationFields = buildV2StepGenerationFields(normalizedInput, options);
         return this.postV2('video/step/text_to_video', {
-            input: normalizedInput,
+            ...stepGenerationFields,
+            input: {
+                ...normalizedInput,
+                ...stepGenerationFields,
+            },
             webhookUrl: options?.webhookUrl,
         }, options);
     }
@@ -616,8 +724,13 @@ export class SamsarClient {
     }
     async createV2StepVideoFromImage(input, options) {
         const normalizedInput = normalizeCreateV2StepImageToVideoInput(input);
+        const stepGenerationFields = buildV2StepGenerationFields(normalizedInput, options);
         return this.postV2('video/step/image_to_video', {
-            input: normalizedInput,
+            ...stepGenerationFields,
+            input: {
+                ...normalizedInput,
+                ...stepGenerationFields,
+            },
             webhookUrl: options?.webhookUrl,
         }, options);
     }
@@ -679,6 +792,22 @@ export class SamsarClient {
             },
         }, options);
     }
+    /**
+     * Assign a short SEO-friendly title to an image using the /v2 image route.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    async assignV2ImageTitle(payload, options) {
+        const body = buildAssignImageTitleBody(payload);
+        if (isFormDataBody(body)) {
+            return this.postForm(this.buildV2Url('image/assign_title'), body, options);
+        }
+        return this.postV2('image/assign_title', {
+            input: body,
+        }, options);
+    }
+    async assignV2TitleToImage(payload, options) {
+        return this.assignV2ImageTitle(payload, options);
+    }
     async updateV2VideoOutroImage(input, options) {
         const normalizedInput = normalizeUpdateVideoOutroImageInput(input, 'updateV2VideoOutroImage');
         return this.postV2('update_outro_image', {
@@ -1645,6 +1774,20 @@ export class SamsarClient {
     async enhanceImage(payload, options) {
         return this.post('image/enhance', payload, options);
     }
+    /**
+     * Assign a short SEO-friendly title to an image.
+     * Supports image_url/image_data JSON payloads or binary image/FormData uploads.
+     */
+    async assignImageTitle(payload, options) {
+        const body = buildAssignImageTitleBody(payload);
+        if (isFormDataBody(body)) {
+            return this.postForm('image/assign_title', body, options);
+        }
+        return this.post('image/assign_title', body, options);
+    }
+    async assignTitleToImage(payload, options) {
+        return this.assignImageTitle(payload, options);
+    }
     /**
      * Add or extend a saved image list for the authenticated API key.
      */
@@ -2019,6 +2162,13 @@ export class SamsarClient {
             body: JSON.stringify(body),
         });
     }
+    async postForm(path, body, options) {
+        return this.request(path, {
+            ...(options ?? {}),
+            method: 'POST',
+            body,
+        });
+    }
     async request(path, options) {
         const url = this.buildUrl(path, options.query);
         const controller = new AbortController();
@@ -2108,7 +2258,7 @@ export class SamsarClient {
                 : this.apiKey
                     ? `Bearer ${this.apiKey}`
                     : undefined,
-            'Content-Type': options.body ? 'application/json' : undefined,
+            'Content-Type': options.body && !isFormDataBody(options.body) ? 'application/json' : undefined,
             'x-external-user-api-key': options.externalUserApiKey ?? this.externalUserApiKey,
             'x-app-secret': resolvedAppKey ? resolvedAppSecret : undefined,
             ...this.defaultHeaders,
@@ -2175,6 +2325,104 @@ export class SamsarClient {
 function trimTrailingSlash(url) {
     return url.replace(/\/+$/, '');
 }
+function buildAssignImageTitleBody(payload) {
+    if (isFormDataBody(payload)) {
+        return payload;
+    }
+    const input = (payload ?? {});
+    const image = input.image ??
+        input.file ??
+        input.image_file ??
+        input.imageFile;
+    if (isBinaryAssignImageTitleInput(image)) {
+        return buildAssignImageTitleFormData(input, image);
+    }
+    const stringImage = getTrimmedString(image);
+    const imageData = stringImage?.startsWith('data:image/')
+        ? stringImage
+        : getTrimmedString(input.image_data) ??
+            getTrimmedString(input.imageData) ??
+            getTrimmedString(input.image_data_url) ??
+            getTrimmedString(input.imageDataUrl);
+    const imageUrl = stringImage && !stringImage.startsWith('data:image/')
+        ? stringImage
+        : getTrimmedString(input.image_url) ??
+            getTrimmedString(input.imageUrl) ??
+            getTrimmedString(input.url);
+    const metadata = input.metadata ?? input.metadata_json ?? input.metadataJson;
+    if (!imageData && !imageUrl) {
+        throw new Error('image, image_data, or image_url is required for assignImageTitle');
+    }
+    return {
+        ...(imageData ? { image_data: imageData } : {}),
+        ...(imageUrl ? { image_url: imageUrl } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+    };
+}
+function buildAssignImageTitleFormData(input, image) {
+    if (typeof FormData === 'undefined') {
+        throw new Error('FormData is required for binary assignImageTitle uploads');
+    }
+    const metadata = input.metadata ?? input.metadata_json ?? input.metadataJson;
+    const mimeType = getTrimmedString(input.mimeType) ?? getBlobType(image);
+    if (!mimeType || !isSupportedAssignImageTitleMimeType(mimeType)) {
+        throw new Error('mimeType must be image/png, image/jpeg, image/webp, or image/gif for binary assignImageTitle uploads');
+    }
+    const blob = toAssignImageTitleBlob(image, mimeType);
+    const fileName = getTrimmedString(input.fileName) ??
+        getTrimmedString(input.filename) ??
+        `image.${mimeTypeToExtension(mimeType)}`;
+    const formData = new FormData();
+    formData.append('image', blob, fileName);
+    if (metadata !== undefined) {
+        formData.append('metadata', typeof metadata === 'string' ? metadata : JSON.stringify(metadata));
+    }
+    return formData;
+}
+function isBinaryAssignImageTitleInput(value) {
+    return (isBlobValue(value) ||
+        value instanceof ArrayBuffer ||
+        value instanceof Uint8Array);
+}
+function toAssignImageTitleBlob(value, mimeType) {
+    if (isBlobValue(value)) {
+        if (value.type === mimeType) {
+            return value;
+        }
+        return new Blob([value], { type: mimeType });
+    }
+    if (value instanceof Uint8Array) {
+        const arrayBuffer = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+        return new Blob([arrayBuffer], { type: mimeType });
+    }
+    return new Blob([value], { type: mimeType });
+}
+function getBlobType(value) {
+    return isBlobValue(value) ? getTrimmedString(value.type) : undefined;
+}
+function isBlobValue(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
+function isFormDataBody(body) {
+    return typeof FormData !== 'undefined' && body instanceof FormData;
+}
+function isSupportedAssignImageTitleMimeType(value) {
+    const normalized = value.trim().toLowerCase();
+    return ['image/png', 'image/jpeg', 'image/jpg', 'image/webp', 'image/gif'].includes(normalized);
+}
+function mimeTypeToExtension(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'image/jpeg' || normalized === 'image/jpg') {
+        return 'jpg';
+    }
+    if (normalized === 'image/webp') {
+        return 'webp';
+    }
+    if (normalized === 'image/gif') {
+        return 'gif';
+    }
+    return 'png';
+}
 function parseMaybeJson(value) {
     try {
         return JSON.parse(value);

package/package.json

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