Backport: feat(fal): deprecate snake_case provider options in favor of camelCase (#10296)

This is an automated backport of #10280 to the release-v5.0 branch.

---------

Co-authored-by: Kevin Thomas <[email protected]>
Co-authored-by: Gregor Martynus <[email protected]>

Author: 3 people

.changeset/fuzzy-squids-check.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/fal': patch
+---
+
+Create a schema for Fal AI providerOptions, and deprecate snake_case parameters for camelCase options

content/providers/01-ai-sdk-providers/10-fal.mdx

@@ -152,7 +152,7 @@ await generateImage({
   prompt: 'Put a donut next to the flour.',
   providerOptions: {
     fal: {
-      image_url:
+      imageUrl:
         'https://v3.fal.media/files/rabbit/rmgBxhwGYb2d3pl3x9sKf_output.png',
     },
   },
@@ -163,11 +163,21 @@ await generateImage({
 
 Fal image models support flexible provider options through the `providerOptions.fal` object. You can pass any parameters supported by the specific Fal model's API. Common options include:
 
-- **image_url** - Reference image URL for image-to-image generation
+- **imageUrl** - Reference image URL for image-to-image generation
 - **strength** - Controls how much the output differs from the input image
-- **guidance_scale** - Controls adherence to the prompt
-- **num_inference_steps** - Number of denoising steps
-- **safety_checker** - Enable/disable safety filtering
+- **guidanceScale** - Controls adherence to the prompt (range: 1-20)
+- **numInferenceSteps** - Number of denoising steps (range: 1-50)
+- **enableSafetyChecker** - Enable/disable safety filtering
+- **outputFormat** - Output format: 'jpeg' or 'png'
+- **syncMode** - Wait for completion before returning response
+- **acceleration** - Speed of generation: 'none', 'regular', or 'high'
+- **safetyTolerance** - Content safety filtering level (1-6, where 1 is strictest)
+
+<Note type="warning">
+  **Deprecation Notice**: snake_case parameter names (e.g., `image_url`,
+  `guidance_scale`) are deprecated and will be removed in `@ai-sdk/fal` v2.0.
+  Please use camelCase names (e.g., `imageUrl`, `guidanceScale`) instead.
+</Note>
 
 Refer to the [Fal AI model documentation](https://fal.ai/models) for model-specific parameters.
 

examples/ai-core/src/generate-image/fal-kontext.ts

@@ -1,4 +1,4 @@
-import { fal } from '@ai-sdk/fal';
+import { fal, type FalImageProviderOptions } from '@ai-sdk/fal';
 import { experimental_generateImage as generateImage } from 'ai';
 import { presentImages } from '../lib/present-image';
 import 'dotenv/config';
@@ -9,9 +9,9 @@ async function main() {
     prompt: 'Put a donut next to the flour.',
     providerOptions: {
       fal: {
-        image_url:
+        imageUrl:
           'https://v3.fal.media/files/rabbit/rmgBxhwGYb2d3pl3x9sKf_output.png',
-      },
+      } satisfies FalImageProviderOptions,
     },
   });
   await presentImages(images);

packages/codemod/src/codemods/v5/replace-fal-snake-case.ts

@@ -0,0 +1,63 @@
+import { createTransformer } from '../lib/create-transformer';
+
+export default createTransformer((fileInfo, api, options, context) => {
+  const { j, root } = context;
+
+  // Helper function to convert snake_case to camelCase
+  function snakeToCamel(str: string): string {
+    return str.replace(/_([a-z])/g, (match, letter) => letter.toUpperCase());
+  }
+
+  // Helper function to recursively transform snake_case properties in an object
+  function transformFalProperties(objExpression: any) {
+    if (objExpression.type !== 'ObjectExpression') return;
+
+    objExpression.properties.forEach((prop: any) => {
+      if (
+        (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+        prop.key.type === 'Identifier'
+      ) {
+        const originalName = prop.key.name;
+        const camelCaseName = snakeToCamel(originalName);
+
+        // Only transform if the name actually changes (contains snake_case)
+        if (originalName !== camelCaseName && originalName.includes('_')) {
+          context.hasChanges = true;
+          prop.key = j.identifier(camelCaseName);
+        }
+
+        // Recursively transform nested objects
+        if (prop.value.type === 'ObjectExpression') {
+          transformFalProperties(prop.value);
+        }
+      }
+    });
+  }
+
+  // Find all ObjectExpression nodes that could contain providerOptions
+  root.find(j.ObjectExpression).forEach(objectPath => {
+    // Look for providerOptions property within this object
+    objectPath.node.properties.forEach((prop: any) => {
+      if (
+        (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+        prop.key.type === 'Identifier' &&
+        prop.key.name === 'providerOptions' &&
+        prop.value.type === 'ObjectExpression'
+      ) {
+        // Found providerOptions, now look for fal property
+        prop.value.properties.forEach((providerProp: any) => {
+          if (
+            (providerProp.type === 'ObjectProperty' ||
+              providerProp.type === 'Property') &&
+            providerProp.key.type === 'Identifier' &&
+            providerProp.key.name === 'fal' &&
+            providerProp.value.type === 'ObjectExpression'
+          ) {
+            // Found fal, transform its properties
+            transformFalProperties(providerProp.value);
+          }
+        });
+      }
+    });
+  });
+});

packages/codemod/src/lib/upgrade.ts

@@ -58,6 +58,7 @@ const bundle = [
   'v5/rename-todatastreamresponse-to-touimessagestreamresponse',
   'v5/rename-tool-parameters-to-inputschema',
   'v5/replace-bedrock-snake-case',
+  'v5/replace-fal-snake-case',
   'v5/replace-content-with-parts',
   'v5/replace-experimental-provider-metadata',
   'v5/replace-image-type-with-file-type',

packages/codemod/src/test/__testfixtures__/replace-fal-snake-case.input.ts

@@ -0,0 +1,64 @@
+// @ts-nocheck
+import { fal } from '@ai-sdk/fal';
+import { experimental_generateImage as generateImage } from 'ai';
+
+// Test 1: Basic snake_case conversion
+const result1 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'A cute baby sea otter',
+  providerOptions: {
+    fal: {
+      guidance_scale: 7.5,
+      num_inference_steps: 28,
+      enable_safety_checker: true,
+    },
+  },
+});
+
+// Test 2: Image-to-image with image_url
+const result2 = await generateImage({
+  model: fal.image('fal-ai/flux/dev/image-to-image'),
+  prompt: 'Transform this',
+  providerOptions: {
+    fal: {
+      image_url: 'https://example.com/image.png',
+      guidance_scale: 7.5,
+      num_inference_steps: 50,
+    },
+  },
+});
+
+// Test 3: Mixed snake_case options
+const result3 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'Abstract art',
+  providerOptions: {
+    fal: {
+      output_format: 'png',
+      sync_mode: true,
+      safety_tolerance: 5,
+    },
+  },
+});
+
+// Test 4: Already camelCase (should not change)
+const result4 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'Landscape',
+  providerOptions: {
+    fal: {
+      guidanceScale: 7.0,
+      numInferenceSteps: 20,
+    },
+  },
+});
+
+// Test 5: Nested objects
+const config = {
+  providerOptions: {
+    fal: {
+      guidance_scale: 8.0,
+      enable_safety_checker: false,
+    },
+  },
+};

packages/codemod/src/test/__testfixtures__/replace-fal-snake-case.output.ts

@@ -0,0 +1,64 @@
+// @ts-nocheck
+import { fal } from '@ai-sdk/fal';
+import { experimental_generateImage as generateImage } from 'ai';
+
+// Test 1: Basic snake_case conversion
+const result1 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'A cute baby sea otter',
+  providerOptions: {
+    fal: {
+      guidanceScale: 7.5,
+      numInferenceSteps: 28,
+      enableSafetyChecker: true,
+    },
+  },
+});
+
+// Test 2: Image-to-image with image_url
+const result2 = await generateImage({
+  model: fal.image('fal-ai/flux/dev/image-to-image'),
+  prompt: 'Transform this',
+  providerOptions: {
+    fal: {
+      imageUrl: 'https://example.com/image.png',
+      guidanceScale: 7.5,
+      numInferenceSteps: 50,
+    },
+  },
+});
+
+// Test 3: Mixed snake_case options
+const result3 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'Abstract art',
+  providerOptions: {
+    fal: {
+      outputFormat: 'png',
+      syncMode: true,
+      safetyTolerance: 5,
+    },
+  },
+});
+
+// Test 4: Already camelCase (should not change)
+const result4 = await generateImage({
+  model: fal.image('fal-ai/flux/dev'),
+  prompt: 'Landscape',
+  providerOptions: {
+    fal: {
+      guidanceScale: 7.0,
+      numInferenceSteps: 20,
+    },
+  },
+});
+
+// Test 5: Nested objects
+const config = {
+  providerOptions: {
+    fal: {
+      guidanceScale: 8.0,
+      enableSafetyChecker: false,
+    },
+  },
+};

packages/codemod/src/test/replace-fal-snake-case.test.ts

@@ -0,0 +1,9 @@
+import { describe, it } from 'vitest';
+import transformer from '../codemods/v5/replace-fal-snake-case';
+import { testTransform } from './test-utils';
+
+describe('replace-fal-snake-case', () => {
+  it('transforms correctly', () => {
+    testTransform(transformer, 'replace-fal-snake-case');
+  });
+});

packages/fal/src/fal-image-model.test.ts

@@ -73,6 +73,81 @@ describe('FalImageModel', () => {
       });
     });
 
+    it('should convert camelCase provider options to snake_case for API', async () => {
+      const model = createBasicModel();
+
+      const result = await model.doGenerate({
+        prompt,
+        n: 1,
+        size: undefined,
+        aspectRatio: undefined,
+        seed: undefined,
+        providerOptions: {
+          fal: {
+            imageUrl: 'https://example.com/image.png',
+            guidanceScale: 7.5,
+            numInferenceSteps: 50,
+            enableSafetyChecker: false,
+          },
+        },
+      });
+
+      expect(await server.calls[0].requestBodyJson).toStrictEqual({
+        prompt,
+        num_images: 1,
+        image_url: 'https://example.com/image.png',
+        guidance_scale: 7.5,
+        num_inference_steps: 50,
+        enable_safety_checker: false,
+      });
+
+      expect(result.warnings).toHaveLength(0);
+    });
+
+    it('should accept deprecated snake_case provider options with warning', async () => {
+      const model = createBasicModel();
+
+      const result = await model.doGenerate({
+        prompt,
+        n: 1,
+        size: undefined,
+        aspectRatio: undefined,
+        seed: undefined,
+        providerOptions: {
+          fal: {
+            image_url: 'https://example.com/image.png',
+            guidance_scale: 7.5,
+            num_inference_steps: 50,
+          },
+        },
+      });
+
+      expect(await server.calls[0].requestBodyJson).toStrictEqual({
+        prompt,
+        num_images: 1,
+        image_url: 'https://example.com/image.png',
+        guidance_scale: 7.5,
+        num_inference_steps: 50,
+      });
+
+      expect(result.warnings).toHaveLength(1);
+      expect(result.warnings[0]).toMatchObject({
+        type: 'other',
+        message: expect.stringContaining('deprecated snake_case'),
+      });
+
+      const warning = result.warnings[0];
+      if (warning.type === 'other') {
+        expect(warning.message).toContain("'image_url' (use 'imageUrl')");
+        expect(warning.message).toContain(
+          "'guidance_scale' (use 'guidanceScale')",
+        );
+        expect(warning.message).toContain(
+          "'num_inference_steps' (use 'numInferenceSteps')",
+        );
+      }
+    });
+
     it('should convert aspect ratio to size', async () => {
       const model = createBasicModel();