@ai-sdk/fal 2.0.9 → 2.0.11

package/src/fal-image-model.ts

@@ -0,0 +1,367 @@
+import type { ImageModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import type { Resolvable } from '@ai-sdk/provider-utils';
+import {
+  combineHeaders,
+  convertImageModelFileToDataUri,
+  createBinaryResponseHandler,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  createStatusCodeErrorResponseHandler,
+  FetchFunction,
+  getFromApi,
+  parseProviderOptions,
+  postJsonToApi,
+  resolve,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { FalImageModelId, FalImageSize } from './fal-image-settings';
+import { falImageProviderOptionsSchema } from './fal-image-options';
+
+interface FalImageModelConfig {
+  provider: string;
+  baseURL: string;
+  headers?: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class FalImageModel implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxImagesPerCall = 1;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: FalImageModelId,
+    private readonly config: FalImageModelConfig,
+  ) {}
+
+  private async getArgs({
+    prompt,
+    n,
+    size,
+    aspectRatio,
+    seed,
+    providerOptions,
+    files,
+    mask,
+  }: Parameters<ImageModelV3['doGenerate']>[0]) {
+    const warnings: Array<SharedV3Warning> = [];
+
+    let imageSize: FalImageSize | undefined;
+    if (size) {
+      const [width, height] = size.split('x').map(Number);
+      imageSize = { width, height };
+    } else if (aspectRatio) {
+      imageSize = convertAspectRatioToSize(aspectRatio);
+    }
+
+    const falOptions = await parseProviderOptions({
+      provider: 'fal',
+      providerOptions,
+      schema: falImageProviderOptionsSchema,
+    });
+
+    const requestBody: Record<string, unknown> = {
+      prompt,
+      seed,
+      image_size: imageSize,
+      num_images: n,
+    };
+
+    // Handle image editing: convert files to image_url or image_urls
+    if (files != null && files.length > 0) {
+      const useMultipleImages = falOptions?.useMultipleImages === true;
+
+      if (useMultipleImages) {
+        // Use image_urls array for models that support multiple images (e.g., flux-2/edit)
+        requestBody.image_urls = files.map(file =>
+          convertImageModelFileToDataUri(file),
+        );
+      } else {
+        // Use single image_url for standard image editing models
+        requestBody.image_url = convertImageModelFileToDataUri(files[0]);
+
+        if (files.length > 1) {
+          warnings.push({
+            type: 'other',
+            message:
+              'Multiple input images provided but useMultipleImages is not enabled. ' +
+              'Only the first image will be used. Set providerOptions.fal.useMultipleImages ' +
+              'to true for models that support multiple images (e.g., fal-ai/flux-2/edit).',
+          });
+        }
+      }
+    }
+
+    // Handle mask for inpainting
+    if (mask != null) {
+      requestBody.mask_url = convertImageModelFileToDataUri(mask);
+    }
+
+    if (falOptions) {
+      const deprecatedKeys =
+        '__deprecatedKeys' in falOptions
+          ? (falOptions.__deprecatedKeys as string[])
+          : undefined;
+
+      if (deprecatedKeys && deprecatedKeys.length > 0) {
+        warnings.push({
+          type: 'other',
+          message: `The following provider options use deprecated snake_case and will be removed in @ai-sdk/fal v2.0. Please use camelCase instead: ${deprecatedKeys
+            .map(key => {
+              const camelCase = key.replace(/_([a-z])/g, (_, letter) =>
+                letter.toUpperCase(),
+              );
+              return `'${key}' (use '${camelCase}')`;
+            })
+            .join(', ')}`,
+        });
+      }
+
+      const fieldMapping: Record<string, string> = {
+        imageUrl: 'image_url',
+        maskUrl: 'mask_url',
+        guidanceScale: 'guidance_scale',
+        numInferenceSteps: 'num_inference_steps',
+        enableSafetyChecker: 'enable_safety_checker',
+        outputFormat: 'output_format',
+        syncMode: 'sync_mode',
+        safetyTolerance: 'safety_tolerance',
+      };
+
+      for (const [key, value] of Object.entries(falOptions)) {
+        if (key === '__deprecatedKeys') continue;
+        if (key === 'useMultipleImages') continue; // Don't send to API
+        const apiKey = fieldMapping[key] ?? key;
+
+        if (value !== undefined) {
+          requestBody[apiKey] = value;
+        }
+      }
+    }
+
+    return { requestBody, warnings } as const;
+  }
+
+  async doGenerate(
+    options: Parameters<ImageModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<ImageModelV3['doGenerate']>>> {
+    const { requestBody, warnings } = await this.getArgs(options);
+
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { value, responseHeaders } = await postJsonToApi({
+      url: `${this.config.baseURL}/${this.modelId}`,
+      headers: combineHeaders(
+        await resolve(this.config.headers),
+        options.headers,
+      ),
+      body: requestBody,
+      failedResponseHandler: falFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        falImageResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const {
+      images: targetImages,
+      // prompt is just passed through and not a revised prompt per image
+      prompt: _prompt,
+      // NSFW information is normalized merged into `providerMetadata.fal.images`
+      has_nsfw_concepts,
+      nsfw_content_detected,
+      // pass through other properties to providerMetadata
+      ...responseMetaData
+    } = value;
+
+    // download the images:
+    const downloadedImages = await Promise.all(
+      targetImages.map(image =>
+        this.downloadImage(image.url, options.abortSignal),
+      ),
+    );
+
+    return {
+      images: downloadedImages,
+      warnings,
+      response: {
+        modelId: this.modelId,
+        timestamp: currentDate,
+        headers: responseHeaders,
+      },
+      providerMetadata: {
+        fal: {
+          images: targetImages.map((image, index) => {
+            const {
+              url,
+              content_type: contentType,
+              file_name: fileName,
+              file_data: fileData,
+              file_size: fileSize,
+              ...imageMetaData
+            } = image;
+
+            const nsfw =
+              has_nsfw_concepts?.[index] ?? nsfw_content_detected?.[index];
+
+            return {
+              ...imageMetaData,
+              ...removeOnlyUndefined({
+                contentType,
+                fileName,
+                fileData,
+                fileSize,
+                nsfw,
+              }),
+            };
+          }),
+          ...responseMetaData,
+        },
+      },
+    };
+  }
+
+  private async downloadImage(
+    url: string,
+    abortSignal: AbortSignal | undefined,
+  ): Promise<Uint8Array> {
+    const { value: response } = await getFromApi({
+      url,
+      // No specific headers should be needed for this request as it's a
+      // generated image provided by fal.ai.
+      abortSignal,
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      successfulResponseHandler: createBinaryResponseHandler(),
+      fetch: this.config.fetch,
+    });
+    return response;
+  }
+}
+
+function removeOnlyUndefined<T extends Record<string, unknown>>(obj: T) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== undefined),
+  ) as Partial<T>;
+}
+
+/**
+Converts an aspect ratio to an image size compatible with fal.ai APIs.
+@param aspectRatio - The aspect ratio to convert.
+@returns The image size.
+ */
+function convertAspectRatioToSize(
+  aspectRatio: `${number}:${number}`,
+): FalImageSize | undefined {
+  switch (aspectRatio) {
+    case '1:1':
+      return 'square_hd';
+    case '16:9':
+      return 'landscape_16_9';
+    case '9:16':
+      return 'portrait_16_9';
+    case '4:3':
+      return 'landscape_4_3';
+    case '3:4':
+      return 'portrait_4_3';
+    case '16:10':
+      return { width: 1280, height: 800 };
+    case '10:16':
+      return { width: 800, height: 1280 };
+    case '21:9':
+      return { width: 2560, height: 1080 };
+    case '9:21':
+      return { width: 1080, height: 2560 };
+  }
+  return undefined;
+}
+
+// Validation error has a particular payload to inform the exact property that is invalid
+const falValidationErrorSchema = z.object({
+  detail: z.array(
+    z.object({
+      loc: z.array(z.string()),
+      msg: z.string(),
+      type: z.string(),
+    }),
+  ),
+});
+
+type ValidationError = z.infer<typeof falValidationErrorSchema>;
+
+// Other errors have a message property
+const falHttpErrorSchema = z.object({
+  message: z.string(),
+});
+
+const falErrorSchema = z.union([falValidationErrorSchema, falHttpErrorSchema]);
+
+const falImageSchema = z.object({
+  url: z.string(),
+  width: z.number().nullish(),
+  height: z.number().nullish(),
+  // e.g. https://fal.ai/models/fal-ai/fashn/tryon/v1.6/api#schema-output
+  content_type: z.string().nullish(),
+  // e.g. https://fal.ai/models/fal-ai/flowedit/api#schema-output
+  file_name: z.string().nullish(),
+  file_data: z.string().optional(),
+  file_size: z.number().nullish(),
+});
+
+// https://fal.ai/models/fal-ai/lora/api#type-File
+const loraFileSchema = z.object({
+  url: z.string(),
+  content_type: z.string().optional(),
+  file_name: z.string().nullable().optional(),
+  file_data: z.string().optional(),
+  file_size: z.number().nullable().optional(),
+});
+
+const commonResponseSchema = z.object({
+  timings: z
+    .object({
+      inference: z.number().optional(),
+    })
+    .optional(),
+  seed: z.number().optional(),
+  has_nsfw_concepts: z.array(z.boolean()).optional(),
+  prompt: z.string().optional(),
+  // https://fal.ai/models/fal-ai/lcm/api#schema-output
+  nsfw_content_detected: z.array(z.boolean()).optional(),
+  num_inference_steps: z.number().optional(),
+  // https://fal.ai/models/fal-ai/lora/api#schema-output
+  debug_latents: loraFileSchema.optional(),
+  debug_per_pass_latents: loraFileSchema.optional(),
+});
+
+// Most FAL image models respond with an array of images, but some have a response
+// with a single image, e.g. https://fal.ai/models/easel-ai/easel-avatar/api#schema-output
+const base = z.looseObject(commonResponseSchema.shape);
+const falImageResponseSchema = z
+  .union([
+    base.extend({ images: z.array(falImageSchema) }),
+    base.extend({ image: falImageSchema }),
+  ])
+  .transform(v => ('images' in v ? v : { ...v, images: [v.image] }))
+  .pipe(base.extend({ images: z.array(falImageSchema) }));
+
+function isValidationError(error: unknown): error is ValidationError {
+  return falValidationErrorSchema.safeParse(error).success;
+}
+
+const falFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: falErrorSchema,
+  errorToMessage: error => {
+    if (isValidationError(error)) {
+      return error.detail
+        .map(detail => `${detail.loc.join('.')}: ${detail.msg}`)
+        .join('\n');
+    }
+    return error.message ?? 'Unknown fal error';
+  },
+});

package/src/fal-image-options.ts

@@ -0,0 +1,129 @@
+import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const falImageProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        /** @deprecated use prompt.images instead */
+        imageUrl: z.string().nullish().meta({
+          deprecated: true,
+          description: 'Use `prompt.images` instead',
+        }),
+        maskUrl: z
+          .string()
+          .nullish()
+          .meta({ deprecated: true, description: 'Use `prompt.mask` instead' }),
+        guidanceScale: z.number().min(1).max(20).nullish(),
+        numInferenceSteps: z.number().min(1).max(50).nullish(),
+        enableSafetyChecker: z.boolean().nullish(),
+        outputFormat: z.enum(['jpeg', 'png']).nullish(),
+        syncMode: z.boolean().nullish(),
+        strength: z.number().nullish(),
+        acceleration: z.enum(['none', 'regular', 'high']).nullish(),
+        safetyTolerance: z
+          .enum(['1', '2', '3', '4', '5', '6'])
+          .or(z.number().min(1).max(6))
+          .nullish(),
+        /**
+         * When true, converts multiple input images to `image_urls` array instead of `image_url` string.
+         */
+        useMultipleImages: z.boolean().nullish(),
+
+        // Deprecated snake_case versions
+        image_url: z.string().nullish(),
+        mask_url: z.string().nullish(),
+        guidance_scale: z.number().min(1).max(20).nullish(),
+        num_inference_steps: z.number().min(1).max(50).nullish(),
+        enable_safety_checker: z.boolean().nullish(),
+        output_format: z.enum(['jpeg', 'png']).nullish(),
+        sync_mode: z.boolean().nullish(),
+        safety_tolerance: z
+          .enum(['1', '2', '3', '4', '5', '6'])
+          .or(z.number().min(1).max(6))
+          .nullish(),
+      })
+      .passthrough()
+      .transform(data => {
+        const result: Record<string, unknown> = {};
+        const deprecatedKeys: string[] = [];
+
+        const mapKey = (snakeKey: string, camelKey: string) => {
+          const snakeValue = data[snakeKey as keyof typeof data];
+          const camelValue = data[camelKey as keyof typeof data];
+
+          // If snake_case is used, mark it as deprecated
+          if (snakeValue !== undefined && snakeValue !== null) {
+            deprecatedKeys.push(snakeKey);
+            result[camelKey] = snakeValue;
+          } else if (camelValue !== undefined && camelValue !== null) {
+            result[camelKey] = camelValue;
+          }
+        };
+
+        // Map all known parameters
+        mapKey('image_url', 'imageUrl');
+        mapKey('mask_url', 'maskUrl');
+        mapKey('guidance_scale', 'guidanceScale');
+        mapKey('num_inference_steps', 'numInferenceSteps');
+        mapKey('enable_safety_checker', 'enableSafetyChecker');
+        mapKey('output_format', 'outputFormat');
+        mapKey('sync_mode', 'syncMode');
+        mapKey('safety_tolerance', 'safetyTolerance');
+
+        // These don't have snake_case equivalents
+        if (data.strength !== undefined && data.strength !== null) {
+          result.strength = data.strength;
+        }
+        if (data.acceleration !== undefined && data.acceleration !== null) {
+          result.acceleration = data.acceleration;
+        }
+        if (
+          data.useMultipleImages !== undefined &&
+          data.useMultipleImages !== null
+        ) {
+          result.useMultipleImages = data.useMultipleImages;
+        }
+
+        for (const [key, value] of Object.entries(data)) {
+          if (
+            ![
+              // camelCase known keys
+              'imageUrl',
+              'maskUrl',
+              'guidanceScale',
+              'numInferenceSteps',
+              'enableSafetyChecker',
+              'outputFormat',
+              'syncMode',
+              'strength',
+              'acceleration',
+              'safetyTolerance',
+              'useMultipleImages',
+              // snake_case known keys
+              'image_url',
+              'mask_url',
+              'guidance_scale',
+              'num_inference_steps',
+              'enable_safety_checker',
+              'output_format',
+              'sync_mode',
+              'safety_tolerance',
+            ].includes(key)
+          ) {
+            result[key] = value;
+          }
+        }
+
+        if (deprecatedKeys.length > 0) {
+          (result as any).__deprecatedKeys = deprecatedKeys;
+        }
+
+        return result;
+      }),
+  ),
+);
+
+export type FalImageProviderOptions = InferSchema<
+  typeof falImageProviderOptionsSchema
+>;

package/src/fal-image-settings.ts

@@ -0,0 +1,71 @@
+// https://fal.ai/explore/search?categories=image-to-image,text-to-image&q=newest
+export type FalImageModelId =
+  | 'fal-ai/aura-sr'
+  | 'fal-ai/bria/background/remove'
+  | 'fal-ai/bria/eraser'
+  | 'fal-ai/bria/product-shot'
+  | 'fal-ai/bria/reimagine'
+  | 'bria/text-to-image/3.2'
+  | 'fal-ai/bria/text-to-image/base'
+  | 'fal-ai/bria/text-to-image/fast'
+  | 'fal-ai/bria/text-to-image/hd'
+  | 'fal-ai/bytedance/dreamina/v3.1/text-to-image'
+  | 'fal-ai/ccsr'
+  | 'fal-ai/clarity-upscaler'
+  | 'fal-ai/creative-upscaler'
+  | 'fal-ai/esrgan'
+  | 'fal-ai/flux-general'
+  | 'fal-ai/flux-general/differential-diffusion'
+  | 'fal-ai/flux-general/image-to-image'
+  | 'fal-ai/flux-general/inpainting'
+  | 'fal-ai/flux-general/rf-inversion'
+  | 'fal-ai/flux-kontext-lora/text-to-image'
+  | 'fal-ai/flux-lora'
+  | 'fal-ai/flux-lora/image-to-image'
+  | 'fal-ai/flux-lora/inpainting'
+  | 'fal-ai/flux-pro/kontext'
+  | 'fal-ai/flux-pro/kontext/max'
+  | 'fal-ai/flux-pro/v1.1'
+  | 'fal-ai/flux-pro/v1.1-ultra'
+  | 'fal-ai/flux-pro/v1.1-ultra-finetuned'
+  | 'fal-ai/flux-pro/v1.1-ultra/redux'
+  | 'fal-ai/flux-pro/v1.1/redux'
+  | 'fal-ai/flux/dev'
+  | 'fal-ai/flux/dev/image-to-image'
+  | 'fal-ai/flux/dev/redux'
+  | 'fal-ai/flux/krea'
+  | 'fal-ai/flux/krea/image-to-image'
+  | 'fal-ai/flux/krea/redux'
+  | 'fal-ai/flux/schnell'
+  | 'fal-ai/flux/schnell/redux'
+  | 'fal-ai/ideogram/character'
+  | 'fal-ai/ideogram/character/edit'
+  | 'fal-ai/ideogram/character/remix'
+  | 'fal-ai/imagen4/preview'
+  | 'fal-ai/luma-photon'
+  | 'fal-ai/luma-photon/flash'
+  | 'fal-ai/object-removal'
+  | 'fal-ai/omnigen-v2'
+  | 'fal-ai/qwen-image'
+  | 'fal-ai/recraft/v3/text-to-image'
+  | 'fal-ai/recraft/v3/image-to-image'
+  | 'fal-ai/sana/sprint'
+  | 'fal-ai/sana/v1.5/4.8b'
+  | 'fal-ai/sana/v1.5/1.6b'
+  | 'fal-ai/sky-raccoon'
+  | 'fal-ai/wan/v2.2-5b/text-to-image'
+  | 'fal-ai/wan/v2.2-a14b/text-to-image'
+  | 'fal-ai/fashn/tryon/v1.6'
+  | (string & {});
+
+export type FalImageSize =
+  | 'square'
+  | 'square_hd'
+  | 'landscape_16_9'
+  | 'landscape_4_3'
+  | 'portrait_16_9'
+  | 'portrait_4_3'
+  | {
+      width: number;
+      height: number;
+    };

package/src/fal-provider.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createFal } from './fal-provider';
+import { FalImageModel } from './fal-image-model';
+
+vi.mock('./fal-image-model', () => ({
+  FalImageModel: vi.fn(),
+}));
+
+describe('createFal', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('image', () => {
+    it('should construct an image model with default configuration', () => {
+      const provider = createFal();
+      const modelId = 'fal-ai/flux/dev';
+
+      const model = provider.image(modelId);
+
+      expect(model).toBeInstanceOf(FalImageModel);
+      expect(FalImageModel).toHaveBeenCalledWith(
+        modelId,
+        expect.objectContaining({
+          provider: 'fal.image',
+          baseURL: 'https://fal.run',
+        }),
+      );
+    });
+
+    it('should respect custom configuration options', () => {
+      const customBaseURL = 'https://custom.fal.run';
+      const customHeaders = { 'X-Custom-Header': 'value' };
+      const mockFetch = vi.fn();
+
+      const provider = createFal({
+        apiKey: 'custom-api-key',
+        baseURL: customBaseURL,
+        headers: customHeaders,
+        fetch: mockFetch,
+      });
+      const modelId = 'fal-ai/flux/dev';
+
+      provider.image(modelId);
+
+      expect(FalImageModel).toHaveBeenCalledWith(
+        modelId,
+        expect.objectContaining({
+          baseURL: customBaseURL,
+          headers: expect.any(Function),
+          fetch: mockFetch,
+          provider: 'fal.image',
+        }),
+      );
+    });
+  });
+});