@umituz/react-native-ai-fal-provider 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-fal-provider",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "FAL AI provider for React Native - implements IAIProvider interface for unified AI generation",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -33,13 +33,13 @@
     "react-native": ">=0.74.0"
   },
   "dependencies": {
-    "@fal-ai/client": "^1.2.1"
+    "@fal-ai/client": ">=0.6.0"
   },
   "devDependencies": {
     "@types/react": "~19.1.10",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
-    "@umituz/react-native-ai-generation-content": "^1.16.0",
+    "@umituz/react-native-ai-generation-content": "^1.17.26",
     "eslint": "^8.57.0",
     "react": "19.1.0",
     "react-native": "0.81.5",
@@ -53,4 +53,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/domain/constants/default-models.constants.ts

@@ -0,0 +1,181 @@
+/**
+ * Default FAL AI Models Catalog
+ * Provides default model configurations for all FAL AI capabilities
+ */
+
+import type { FalModelType } from "../entities/fal.types";
+
+export interface FalModelConfig {
+  id: string;
+  name: string;
+  type: FalModelType;
+  /** @deprecated Use `type` instead. Kept for backward compatibility */
+  category?: string;
+  isDefault?: boolean;
+  isActive?: boolean;
+  pricing?: {
+    freeUserCost: number;
+    premiumUserCost: number;
+  };
+  description?: string;
+  order?: number;
+}
+
+export const DEFAULT_TEXT_TO_IMAGE_MODELS: FalModelConfig[] = [
+  {
+    id: "fal-ai/flux/schnell",
+    name: "Flux Schnell",
+    type: "text-to-image",
+    isDefault: true,
+    isActive: true,
+    pricing: { freeUserCost: 1, premiumUserCost: 0.5 },
+    description: "Fast and efficient text-to-image generation",
+    order: 1,
+  },
+  {
+    id: "fal-ai/flux/dev",
+    name: "Flux Dev",
+    type: "text-to-image",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 2, premiumUserCost: 1 },
+    description: "High-quality text-to-image generation",
+    order: 2,
+  },
+  {
+    id: "fal-ai/flux-pro",
+    name: "Flux Pro",
+    type: "text-to-image",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 3, premiumUserCost: 1.5 },
+    description: "Professional-grade text-to-image generation",
+    order: 3,
+  },
+];
+
+export const DEFAULT_TEXT_TO_VOICE_MODELS: FalModelConfig[] = [
+  {
+    id: "fal-ai/playai/tts/v3",
+    name: "PlayAI TTS v3",
+    type: "text-to-voice",
+    isDefault: true,
+    isActive: true,
+    pricing: { freeUserCost: 1, premiumUserCost: 0.5 },
+    description: "High-quality text-to-speech synthesis",
+    order: 1,
+  },
+  {
+    id: "fal-ai/eleven-labs/tts",
+    name: "ElevenLabs TTS",
+    type: "text-to-voice",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 2, premiumUserCost: 1 },
+    description: "Premium voice synthesis with multiple voice options",
+    order: 2,
+  },
+];
+
+export const DEFAULT_TEXT_TO_VIDEO_MODELS: FalModelConfig[] = [
+  {
+    id: "fal-ai/hunyuan-video/1",
+    name: "Hunyuan",
+    type: "text-to-video",
+    isDefault: true,
+    isActive: true,
+    pricing: { freeUserCost: 10, premiumUserCost: 5 },
+    description: "High-quality video generation",
+    order: 1,
+  },
+  {
+    id: "fal-ai/minimax-video",
+    name: "MiniMax",
+    type: "text-to-video",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 15, premiumUserCost: 8 },
+    description: "Advanced video generation with better dynamics",
+    order: 2,
+  },
+  {
+    id: "fal-ai/kling-video/v1.5/pro/text-to-video",
+    name: "Kling 1.5",
+    type: "text-to-video",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 20, premiumUserCost: 10 },
+    description: "Professional video generation",
+    order: 3,
+  },
+  {
+    id: "fal-ai/mochi-v1",
+    name: "Mochi",
+    type: "text-to-video",
+    isDefault: false,
+    isActive: true,
+    pricing: { freeUserCost: 8, premiumUserCost: 4 },
+    description: "Fast video generation",
+    order: 4,
+  },
+];
+
+export const DEFAULT_IMAGE_TO_VIDEO_MODELS: FalModelConfig[] = [
+  {
+    id: "fal-ai/kling-video/v1.5/pro/image-to-video",
+    name: "Kling I2V",
+    type: "image-to-video",
+    isDefault: true,
+    isActive: true,
+    pricing: { freeUserCost: 15, premiumUserCost: 8 },
+    description: "High-quality image to video generation",
+    order: 1,
+  },
+];
+
+/**
+ * Get all default models
+ */
+export function getAllDefaultModels(): FalModelConfig[] {
+  return [
+    ...DEFAULT_TEXT_TO_IMAGE_MODELS,
+    ...DEFAULT_TEXT_TO_VOICE_MODELS,
+    ...DEFAULT_TEXT_TO_VIDEO_MODELS,
+    ...DEFAULT_IMAGE_TO_VIDEO_MODELS,
+  ];
+}
+
+/**
+ * Get default models by type
+ */
+export function getDefaultModelsByType(type: FalModelType): FalModelConfig[] {
+  switch (type) {
+    case "text-to-image":
+      return DEFAULT_TEXT_TO_IMAGE_MODELS;
+    case "text-to-voice":
+      return DEFAULT_TEXT_TO_VOICE_MODELS;
+    case "text-to-video":
+      return DEFAULT_TEXT_TO_VIDEO_MODELS;
+    case "image-to-video":
+      return DEFAULT_IMAGE_TO_VIDEO_MODELS;
+    case "image-to-image":
+      return [];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Get default model for a type
+ */
+export function getDefaultModel(type: FalModelType): FalModelConfig | undefined {
+  const models = getDefaultModelsByType(type);
+  return models.find((m) => m.isDefault) || models[0];
+}
+
+/**
+ * Find model by ID across all types
+ */
+export function findModelById(id: string): FalModelConfig | undefined {
+  return getAllDefaultModels().find((m) => m.id === id);
+}

package/src/domain/constants/feature-models.constants.ts

@@ -0,0 +1,68 @@
+/**
+ * FAL Feature Models Catalog
+ * Provider-specific model IDs for image and video processing features
+ */
+
+import type {
+  ImageFeatureType,
+  VideoFeatureType,
+} from "@umituz/react-native-ai-generation-content";
+
+export interface FeatureModelConfig {
+  id: string;
+  feature: ImageFeatureType | VideoFeatureType;
+  description?: string;
+}
+
+/**
+ * FAL model IDs for IMAGE processing features
+ */
+export const FAL_IMAGE_FEATURE_MODELS: Record<ImageFeatureType, string> = {
+  "upscale": "fal-ai/clarity-upscaler",
+  "photo-restore": "fal-ai/aura-sr",
+  "face-swap": "fal-ai/face-swap",
+  "anime-selfie": "fal-ai/anime-image-generator",
+  "remove-background": "fal-ai/bria/background/remove",
+  "remove-object": "fal-ai/flux-kontext-lora/inpaint",
+  "hd-touch-up": "fal-ai/clarity-upscaler",
+  "replace-background": "fal-ai/bria/background/replace",
+};
+
+/**
+ * FAL model IDs for VIDEO processing features
+ */
+export const FAL_VIDEO_FEATURE_MODELS: Record<VideoFeatureType, string> = {
+  "ai-hug": "fal-ai/wan-25-preview/image-to-video",
+  "ai-kiss": "fal-ai/wan-25-preview/image-to-video",
+};
+
+/**
+ * Get FAL model ID for an image feature
+ */
+export function getFalImageFeatureModel(feature: ImageFeatureType): string {
+  return FAL_IMAGE_FEATURE_MODELS[feature];
+}
+
+/**
+ * Get FAL model ID for a video feature
+ */
+export function getFalVideoFeatureModel(feature: VideoFeatureType): string {
+  return FAL_VIDEO_FEATURE_MODELS[feature];
+}
+
+/**
+ * Get all feature model configs
+ */
+export function getAllFeatureModels(): FeatureModelConfig[] {
+  const imageModels = Object.entries(FAL_IMAGE_FEATURE_MODELS).map(([feature, id]) => ({
+    id,
+    feature: feature as ImageFeatureType,
+  }));
+
+  const videoModels = Object.entries(FAL_VIDEO_FEATURE_MODELS).map(([feature, id]) => ({
+    id,
+    feature: feature as VideoFeatureType,
+  }));
+
+  return [...imageModels, ...videoModels];
+}

package/src/index.ts

@@ -42,6 +42,39 @@ export type {
   FalErrorMessages,
 } from "./domain/entities/error.types";
 
+// =============================================================================
+// DOMAIN LAYER - Default Models
+// =============================================================================
+
+export {
+  DEFAULT_TEXT_TO_IMAGE_MODELS,
+  DEFAULT_TEXT_TO_VOICE_MODELS,
+  DEFAULT_TEXT_TO_VIDEO_MODELS,
+  DEFAULT_IMAGE_TO_VIDEO_MODELS,
+  getAllDefaultModels,
+  getDefaultModelsByType,
+  getDefaultModel,
+  findModelById,
+} from "./domain/constants/default-models.constants";
+
+export type { FalModelConfig } from "./domain/constants/default-models.constants";
+
+// =============================================================================
+// DOMAIN LAYER - Feature Models
+// =============================================================================
+
+export {
+  FAL_IMAGE_FEATURE_MODELS,
+  FAL_VIDEO_FEATURE_MODELS,
+  getFalImageFeatureModel,
+  getFalVideoFeatureModel,
+  getAllFeatureModels,
+} from "./domain/constants/feature-models.constants";
+
+export type {
+  FeatureModelConfig,
+} from "./domain/constants/feature-models.constants";
+
 // =============================================================================
 // INFRASTRUCTURE LAYER - Provider (IAIProvider Implementation)
 // =============================================================================
@@ -49,10 +82,11 @@ export type {
 export { FalProvider, falProvider } from "./infrastructure/services";
 
 // =============================================================================
-// INFRASTRUCTURE LAYER - Services (Low-level client)
+// INFRASTRUCTURE LAYER - Services
 // =============================================================================
 
-export { falClientService } from "./infrastructure/services";
+export { falClientService, falModelsService } from "./infrastructure/services";
+export type { ModelFetcher } from "./infrastructure/services";
 
 // =============================================================================
 // INFRASTRUCTURE LAYER - Utils
@@ -63,6 +97,29 @@ export {
   falErrorMapper,
   mapFalError,
   isFalErrorRetryable,
+  // Input builders
+  buildSingleImageInput,
+  buildDualImageInput,
+  buildUpscaleInput,
+  buildPhotoRestoreInput,
+  buildVideoFromImageInput,
+  buildFaceSwapInput,
+  buildAnimeSelfieInput,
+  buildRemoveBackgroundInput,
+  buildRemoveObjectInput,
+  buildReplaceBackgroundInput,
+  buildHDTouchUpInput,
+} from "./infrastructure/utils";
+
+export type {
+  UpscaleOptions,
+  PhotoRestoreOptions,
+  FaceSwapOptions,
+  AnimeSelfieOptions,
+  RemoveBackgroundOptions,
+  RemoveObjectOptions,
+  ReplaceBackgroundOptions,
+  VideoFromImageOptions,
 } from "./infrastructure/utils";
 
 // =============================================================================

package/src/infrastructure/services/fal-models.service.ts

@@ -0,0 +1,198 @@
+/**
+ * FAL Models Service
+ * Manages FAL AI model configurations with in-memory caching
+ *
+ * This service provides default models and allows apps to override/extend
+ * with custom model sources (e.g., Firebase, API)
+ */
+
+import type { FalModelType } from "../../domain/entities/fal.types";
+import {
+  type FalModelConfig,
+  getDefaultModelsByType,
+  getDefaultModel,
+  findModelById,
+} from "../../domain/constants/default-models.constants";
+
+export type { FalModelConfig };
+
+export type ModelFetcher = (type: FalModelType) => Promise<FalModelConfig[]>;
+
+interface CacheEntry {
+  data: FalModelConfig[];
+  timestamp: number;
+}
+
+const DEFAULT_CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours
+
+class FalModelsService {
+  private cache = new Map<FalModelType, CacheEntry>();
+  private cacheTtl = DEFAULT_CACHE_TTL;
+  private customFetcher: ModelFetcher | null = null;
+
+  /**
+   * Set custom model fetcher (e.g., for Firebase integration)
+   */
+  setModelFetcher(fetcher: ModelFetcher): void {
+    this.customFetcher = fetcher;
+    this.clearCache();
+  }
+
+  /**
+   * Configure cache TTL
+   */
+  setCacheTtl(ttlMs: number): void {
+    this.cacheTtl = ttlMs;
+  }
+
+  /**
+   * Get models by type with caching
+   */
+  async getModels(type: FalModelType): Promise<FalModelConfig[]> {
+    const cached = this.getFromCache(type);
+    if (cached) {
+      return cached;
+    }
+
+    let models: FalModelConfig[];
+
+    if (this.customFetcher) {
+      try {
+        models = await this.customFetcher(type);
+        if (models.length === 0) {
+          models = getDefaultModelsByType(type);
+        }
+      } catch {
+        models = getDefaultModelsByType(type);
+      }
+    } else {
+      models = getDefaultModelsByType(type);
+    }
+
+    this.setCache(type, models);
+    return this.sortModels(models);
+  }
+
+  /**
+   * Get text-to-image models
+   */
+  async getTextToImageModels(): Promise<FalModelConfig[]> {
+    return this.getModels("text-to-image");
+  }
+
+  /**
+   * Get text-to-voice models
+   */
+  async getTextToVoiceModels(): Promise<FalModelConfig[]> {
+    return this.getModels("text-to-voice");
+  }
+
+  /**
+   * Get text-to-video models
+   */
+  async getTextToVideoModels(): Promise<FalModelConfig[]> {
+    return this.getModels("text-to-video");
+  }
+
+  /**
+   * Get image-to-video models
+   */
+  async getImageToVideoModels(): Promise<FalModelConfig[]> {
+    return this.getModels("image-to-video");
+  }
+
+  /**
+   * Get default model for type
+   */
+  getDefaultModel(type: FalModelType): FalModelConfig | undefined {
+    return getDefaultModel(type);
+  }
+
+  /**
+   * Find model by ID (from cache or defaults)
+   */
+  async findById(id: string): Promise<FalModelConfig | undefined> {
+    // Check cache first
+    for (const [, entry] of this.cache) {
+      const found = entry.data.find((m) => m.id === id);
+      if (found) return found;
+    }
+
+    // Fall back to defaults
+    return findModelById(id);
+  }
+
+  /**
+   * Get model pricing
+   */
+  async getModelPricing(
+    modelId: string
+  ): Promise<{ freeUserCost: number; premiumUserCost: number } | null> {
+    const model = await this.findById(modelId);
+    return model?.pricing || null;
+  }
+
+  /**
+   * Get voice model pricing
+   */
+  async getVoiceModelPricing(
+    modelId: string
+  ): Promise<{ freeUserCost: number; premiumUserCost: number } | null> {
+    const models = await this.getTextToVoiceModels();
+    const model = models.find((m) => m.id === modelId);
+    return model?.pricing || null;
+  }
+
+  /**
+   * Get video model pricing
+   */
+  async getVideoModelPricing(
+    modelId: string
+  ): Promise<{ freeUserCost: number; premiumUserCost: number } | null> {
+    const models = await this.getTextToVideoModels();
+    const model = models.find((m) => m.id === modelId);
+    return model?.pricing || null;
+  }
+
+  /**
+   * Clear all cached models
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Clear cache for specific type
+   */
+  clearCacheForType(type: FalModelType): void {
+    this.cache.delete(type);
+  }
+
+  private getFromCache(type: FalModelType): FalModelConfig[] | null {
+    const entry = this.cache.get(type);
+    if (!entry) return null;
+
+    const isExpired = Date.now() - entry.timestamp > this.cacheTtl;
+    if (isExpired) {
+      this.cache.delete(type);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  private setCache(type: FalModelType, data: FalModelConfig[]): void {
+    this.cache.set(type, { data, timestamp: Date.now() });
+  }
+
+  private sortModels(models: FalModelConfig[]): FalModelConfig[] {
+    return [...models].sort((a, b) => {
+      if (a.order !== b.order) {
+        return (a.order || 0) - (b.order || 0);
+      }
+      return a.name.localeCompare(b.name);
+    });
+  }
+}
+
+export const falModelsService = new FalModelsService();

package/src/infrastructure/services/fal-provider.ts

@@ -11,8 +11,27 @@ import type {
   JobStatus,
   AIJobStatusType,
   SubscribeOptions,
+  ImageFeatureType,
+  VideoFeatureType,
+  ImageFeatureInputData,
+  VideoFeatureInputData,
 } from "@umituz/react-native-ai-generation-content";
 import type { FalQueueStatus, FalLogEntry } from "../../domain/entities/fal.types";
+import {
+  FAL_IMAGE_FEATURE_MODELS,
+  FAL_VIDEO_FEATURE_MODELS,
+} from "../../domain/constants/feature-models.constants";
+import {
+  buildUpscaleInput,
+  buildPhotoRestoreInput,
+  buildVideoFromImageInput,
+  buildFaceSwapInput,
+  buildAnimeSelfieInput,
+  buildRemoveBackgroundInput,
+  buildRemoveObjectInput,
+  buildReplaceBackgroundInput,
+  buildHDTouchUpInput,
+} from "../utils/input-builders.util";
 
 declare const __DEV__: boolean;
 
@@ -172,6 +191,79 @@ export class FalProvider implements IAIProvider {
     this.config = null;
     this.initialized = false;
   }
+
+  /**
+   * Get model ID for an IMAGE feature
+   */
+  getImageFeatureModel(feature: ImageFeatureType): string {
+    return FAL_IMAGE_FEATURE_MODELS[feature];
+  }
+
+  /**
+   * Build input for an IMAGE feature
+   */
+  buildImageFeatureInput(
+    feature: ImageFeatureType,
+    data: ImageFeatureInputData,
+  ): Record<string, unknown> {
+    const { imageBase64, targetImageBase64, prompt, options } = data;
+
+    switch (feature) {
+      case "upscale":
+        return buildUpscaleInput(imageBase64, options);
+      case "photo-restore":
+        return buildPhotoRestoreInput(imageBase64, options);
+      case "face-swap":
+        if (!targetImageBase64) {
+          throw new Error("Face swap requires target image");
+        }
+        return buildFaceSwapInput(imageBase64, targetImageBase64, options);
+      case "anime-selfie":
+        return buildAnimeSelfieInput(imageBase64, options);
+      case "remove-background":
+        return buildRemoveBackgroundInput(imageBase64, options);
+      case "remove-object":
+        return buildRemoveObjectInput(imageBase64, { prompt, ...options });
+      case "hd-touch-up":
+        return buildHDTouchUpInput(imageBase64, options);
+      case "replace-background":
+        if (!prompt) {
+          throw new Error("Replace background requires prompt");
+        }
+        return buildReplaceBackgroundInput(imageBase64, { prompt });
+      default:
+        throw new Error(`Unknown image feature: ${feature}`);
+    }
+  }
+
+  /**
+   * Get model ID for a VIDEO feature
+   */
+  getVideoFeatureModel(feature: VideoFeatureType): string {
+    return FAL_VIDEO_FEATURE_MODELS[feature];
+  }
+
+  /**
+   * Build input for a VIDEO feature
+   */
+  buildVideoFeatureInput(
+    feature: VideoFeatureType,
+    data: VideoFeatureInputData,
+  ): Record<string, unknown> {
+    const { sourceImageBase64, targetImageBase64, prompt, options } = data;
+
+    switch (feature) {
+      case "ai-hug":
+      case "ai-kiss":
+        return buildVideoFromImageInput(sourceImageBase64, {
+          target_image: targetImageBase64,
+          motion_prompt: prompt,
+          ...options,
+        });
+      default:
+        throw new Error(`Unknown video feature: ${feature}`);
+    }
+  }
 }
 
 export const falProvider = new FalProvider();

package/src/infrastructure/services/index.ts

@@ -5,3 +5,4 @@
 
 export { falClientService } from "./fal-client.service";
 export { FalProvider, falProvider } from "./fal-provider";
+export { falModelsService, type FalModelConfig, type ModelFetcher } from "./fal-models.service";

package/src/infrastructure/utils/index.ts

@@ -5,3 +5,29 @@
 
 export { categorizeFalError } from "./error-categorizer";
 export { falErrorMapper, mapFalError, isFalErrorRetryable } from "./error-mapper";
+
+// Input builders
+export {
+  buildSingleImageInput,
+  buildDualImageInput,
+  buildUpscaleInput,
+  buildPhotoRestoreInput,
+  buildVideoFromImageInput,
+  buildFaceSwapInput,
+  buildAnimeSelfieInput,
+  buildRemoveBackgroundInput,
+  buildRemoveObjectInput,
+  buildReplaceBackgroundInput,
+  buildHDTouchUpInput,
+} from "./input-builders.util";
+
+export type {
+  UpscaleOptions,
+  PhotoRestoreOptions,
+  FaceSwapOptions,
+  AnimeSelfieOptions,
+  RemoveBackgroundOptions,
+  RemoveObjectOptions,
+  ReplaceBackgroundOptions,
+  VideoFromImageOptions,
+} from "./input-builders.util";

package/src/infrastructure/utils/input-builders.util.ts

@@ -0,0 +1,199 @@
+/**
+ * FAL Input Builders
+ * Constructs FAL API input from normalized data
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UpscaleOptions {
+  scaleFactor?: number;
+  enhanceFaces?: boolean;
+}
+
+export interface PhotoRestoreOptions {
+  enhanceFaces?: boolean;
+}
+
+export interface FaceSwapOptions {
+  // No additional options
+}
+
+export interface AnimeSelfieOptions {
+  style?: string;
+}
+
+export interface RemoveBackgroundOptions {
+  // No additional options
+}
+
+export interface RemoveObjectOptions {
+  mask?: string;
+  prompt?: string;
+}
+
+export interface ReplaceBackgroundOptions {
+  prompt: string;
+}
+
+export interface VideoFromImageOptions {
+  target_image?: string;
+  motion_prompt?: string;
+  duration?: number;
+}
+
+// =============================================================================
+// BASE BUILDERS
+// =============================================================================
+
+/**
+ * Build FAL single image input format
+ */
+export function buildSingleImageInput(
+  base64: string,
+  extraParams?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    image_url: base64.startsWith("data:")
+      ? base64
+      : `data:image/jpeg;base64,${base64}`,
+    ...extraParams,
+  };
+}
+
+/**
+ * Build FAL dual image input format
+ */
+export function buildDualImageInput(
+  sourceBase64: string,
+  targetBase64: string,
+  extraParams?: Record<string, unknown>,
+): Record<string, unknown> {
+  const formatImage = (b64: string) =>
+    b64.startsWith("data:") ? b64 : `data:image/jpeg;base64,${b64}`;
+
+  return {
+    image_url: formatImage(sourceBase64),
+    second_image_url: formatImage(targetBase64),
+    ...extraParams,
+  };
+}
+
+// =============================================================================
+// FEATURE-SPECIFIC BUILDERS
+// =============================================================================
+
+/**
+ * Build upscale input for FAL clarity-upscaler
+ */
+export function buildUpscaleInput(
+  base64: string,
+  options?: UpscaleOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64, {
+    scale: options?.scaleFactor || 2,
+    face_enhance: options?.enhanceFaces || false,
+  });
+}
+
+/**
+ * Build photo restore input for FAL aura-sr
+ */
+export function buildPhotoRestoreInput(
+  base64: string,
+  options?: PhotoRestoreOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64, {
+    face_enhance: options?.enhanceFaces || true,
+  });
+}
+
+/**
+ * Build AI hug/kiss video input for FAL wan-25-preview
+ * Supports dual images for interaction videos
+ */
+export function buildVideoFromImageInput(
+  base64: string,
+  options?: VideoFromImageOptions,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {
+    motion_prompt: options?.motion_prompt,
+    num_frames: options?.duration ? Math.ceil(options.duration * 24) : undefined,
+  };
+
+  // If target image is provided, use dual image format
+  if (options?.target_image) {
+    return buildDualImageInput(base64, options.target_image, params);
+  }
+
+  return buildSingleImageInput(base64, params);
+}
+
+/**
+ * Build face swap input for FAL face-swap
+ */
+export function buildFaceSwapInput(
+  sourceBase64: string,
+  targetBase64: string,
+  _options?: FaceSwapOptions,
+): Record<string, unknown> {
+  return buildDualImageInput(sourceBase64, targetBase64);
+}
+
+/**
+ * Build anime selfie input for FAL anime-image-generator
+ */
+export function buildAnimeSelfieInput(
+  base64: string,
+  options?: AnimeSelfieOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64, {
+    style: options?.style || "anime",
+  });
+}
+
+/**
+ * Build remove background input for FAL bria/background/remove
+ */
+export function buildRemoveBackgroundInput(
+  base64: string,
+  _options?: RemoveBackgroundOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64);
+}
+
+/**
+ * Build remove object (inpaint) input for FAL flux-kontext-lora/inpaint
+ */
+export function buildRemoveObjectInput(
+  base64: string,
+  options?: RemoveObjectOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64, {
+    mask_url: options?.mask,
+    prompt: options?.prompt || "Remove the object and fill with background",
+  });
+}
+
+/**
+ * Build replace background input for FAL bria/background/replace
+ */
+export function buildReplaceBackgroundInput(
+  base64: string,
+  options: ReplaceBackgroundOptions,
+): Record<string, unknown> {
+  return buildSingleImageInput(base64, {
+    prompt: options.prompt,
+  });
+}
+
+/**
+ * Build HD touch up input (same as upscale)
+ */
+export function buildHDTouchUpInput(
+  base64: string,
+  options?: UpscaleOptions,
+): Record<string, unknown> {
+  return buildUpscaleInput(base64, options);
+}