@ai-sdk/fal 3.0.0-beta.3 → 3.0.0-beta.31

package/src/fal-provider.ts

@@ -1,24 +1,24 @@
 import {
-  Experimental_VideoModelV3,
-  ImageModelV3,
   NoSuchModelError,
-  ProviderV3,
-  SpeechModelV3,
-  TranscriptionModelV3,
+  type Experimental_VideoModelV4,
+  type ImageModelV4,
+  type ProviderV4,
+  type SpeechModelV4,
+  type TranscriptionModelV4,
 } from '@ai-sdk/provider';
-import type { FetchFunction } from '@ai-sdk/provider-utils';
 import {
   withoutTrailingSlash,
   withUserAgentSuffix,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { FalImageModel } from './fal-image-model';
-import { FalImageModelId } from './fal-image-settings';
-import { FalTranscriptionModelId } from './fal-transcription-options';
+import type { FalImageModelId } from './fal-image-settings';
+import type { FalTranscriptionModelId } from './fal-transcription-options';
 import { FalTranscriptionModel } from './fal-transcription-model';
-import { FalSpeechModelId } from './fal-speech-settings';
+import type { FalSpeechModelId } from './fal-speech-settings';
 import { FalSpeechModel } from './fal-speech-model';
 import { FalVideoModel } from './fal-video-model';
-import { FalVideoModelId } from './fal-video-settings';
+import type { FalVideoModelId } from './fal-video-settings';
 import { VERSION } from './version';
 
 export interface FalProviderSettings {
@@ -46,36 +46,36 @@ export interface FalProviderSettings {
   fetch?: FetchFunction;
 }
 
-export interface FalProvider extends ProviderV3 {
+export interface FalProvider extends ProviderV4 {
   /**
    * Creates a model for image generation.
    */
-  image(modelId: FalImageModelId): ImageModelV3;
+  image(modelId: FalImageModelId): ImageModelV4;
 
   /**
    * Creates a model for image generation.
    */
-  imageModel(modelId: FalImageModelId): ImageModelV3;
+  imageModel(modelId: FalImageModelId): ImageModelV4;
 
   /**
    * Creates a model for transcription.
    */
-  transcription(modelId: FalTranscriptionModelId): TranscriptionModelV3;
+  transcription(modelId: FalTranscriptionModelId): TranscriptionModelV4;
 
   /**
    * Creates a model for video generation.
    */
-  video(modelId: FalVideoModelId): Experimental_VideoModelV3;
+  video(modelId: FalVideoModelId): Experimental_VideoModelV4;
 
   /**
    * Creates a model for video generation.
    */
-  videoModel(modelId: FalVideoModelId): Experimental_VideoModelV3;
+  videoModel(modelId: FalVideoModelId): Experimental_VideoModelV4;
 
   /**
    * Creates a model for speech generation.
    */
-  speech(modelId: FalSpeechModelId): SpeechModelV3;
+  speech(modelId: FalSpeechModelId): SpeechModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
@@ -182,7 +182,7 @@ export function createFal(options: FalProviderSettings = {}): FalProvider {
   };
 
   return {
-    specificationVersion: 'v3' as const,
+    specificationVersion: 'v4' as const,
     imageModel: createImageModel,
     image: createImageModel,
     languageModel: (modelId: string) => {

package/src/fal-speech-model-options.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod/v4';
+import { FAL_EMOTIONS, FAL_LANGUAGE_BOOSTS } from './fal-api-types';
+
+export const falSpeechModelOptionsSchema = z.looseObject({
+  voice_setting: z
+    .object({
+      speed: z.number().nullish(),
+      vol: z.number().nullish(),
+      voice_id: z.string().nullish(),
+      pitch: z.number().nullish(),
+      english_normalization: z.boolean().nullish(),
+      emotion: z.enum(FAL_EMOTIONS).nullish(),
+    })
+    .partial()
+    .nullish(),
+  audio_setting: z.record(z.string(), z.unknown()).nullish(),
+  language_boost: z.enum(FAL_LANGUAGE_BOOSTS).nullish(),
+  pronunciation_dict: z.record(z.string(), z.string()).nullish(),
+});
+
+export type FalSpeechModelOptions = z.infer<typeof falSpeechModelOptionsSchema>;

package/src/fal-speech-model.ts

@@ -1,4 +1,4 @@
-import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import type { SpeechModelV4, SharedV4Warning } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createBinaryResponseHandler,
@@ -7,31 +7,15 @@ import {
   getFromApi,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import { FalConfig } from './fal-config';
+import type { FalConfig } from './fal-config';
 import { falFailedResponseHandler } from './fal-error';
-import { FAL_EMOTIONS, FAL_LANGUAGE_BOOSTS } from './fal-api-types';
-import { FalSpeechModelId } from './fal-speech-settings';
-
-const falSpeechModelOptionsSchema = z.looseObject({
-  voice_setting: z
-    .object({
-      speed: z.number().nullish(),
-      vol: z.number().nullish(),
-      voice_id: z.string().nullish(),
-      pitch: z.number().nullish(),
-      english_normalization: z.boolean().nullish(),
-      emotion: z.enum(FAL_EMOTIONS).nullish(),
-    })
-    .partial()
-    .nullish(),
-  audio_setting: z.record(z.string(), z.unknown()).nullish(),
-  language_boost: z.enum(FAL_LANGUAGE_BOOSTS).nullish(),
-  pronunciation_dict: z.record(z.string(), z.string()).nullish(),
-});
-
-export type FalSpeechModelOptions = z.infer<typeof falSpeechModelOptionsSchema>;
+import { falSpeechModelOptionsSchema } from './fal-speech-model-options';
+import type { FalSpeechModelId } from './fal-speech-settings';
 
 interface FalSpeechModelConfig extends FalConfig {
   _internal?: {
@@ -39,13 +23,27 @@ interface FalSpeechModelConfig extends FalConfig {
   };
 }
 
-export class FalSpeechModel implements SpeechModelV3 {
-  readonly specificationVersion = 'v3';
+export class FalSpeechModel implements SpeechModelV4 {
+  readonly specificationVersion = 'v4';
 
   get provider(): string {
     return this.config.provider;
   }
 
+  static [WORKFLOW_SERIALIZE](model: FalSpeechModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: FalSpeechModelId;
+    config: FalSpeechModelConfig;
+  }) {
+    return new FalSpeechModel(options.modelId, options.config);
+  }
+
   constructor(
     readonly modelId: FalSpeechModelId,
     private readonly config: FalSpeechModelConfig,
@@ -58,8 +56,8 @@ export class FalSpeechModel implements SpeechModelV3 {
     speed,
     language,
     providerOptions,
-  }: Parameters<SpeechModelV3['doGenerate']>[0]) {
-    const warnings: SharedV3Warning[] = [];
+  }: Parameters<SpeechModelV4['doGenerate']>[0]) {
+    const warnings: SharedV4Warning[] = [];
 
     const falOptions = await parseProviderOptions({
       provider: 'fal',
@@ -98,8 +96,8 @@ export class FalSpeechModel implements SpeechModelV3 {
   }
 
   async doGenerate(
-    options: Parameters<SpeechModelV3['doGenerate']>[0],
-  ): Promise<Awaited<ReturnType<SpeechModelV3['doGenerate']>>> {
+    options: Parameters<SpeechModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
     const { requestBody, warnings } = await this.getArgs(options);
 
@@ -112,7 +110,7 @@ export class FalSpeechModel implements SpeechModelV3 {
         path: `https://fal.run/${this.modelId}`,
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body: requestBody,
       failedResponseHandler: falFailedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(

package/src/fal-transcription-model-options.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod/v4';
+
+// https://fal.ai/models/fal-ai/whisper/api?platform=http
+export const falTranscriptionModelOptionsSchema = z.object({
+  /**
+   * Language of the audio file. If set to null, the language will be automatically detected. Defaults to null.
+   *
+   * If translate is selected as the task, the audio will be translated to English, regardless of the language selected.
+   */
+  language: z
+    .union([z.enum(['en']), z.string()])
+    .nullish()
+    .default('en'),
+
+  /**
+   * Whether to diarize the audio file. Defaults to true.
+   */
+  diarize: z.boolean().nullish().default(true),
+
+  /**
+   * Level of the chunks to return. Either segment or word. Default value: "segment"
+   */
+  chunkLevel: z.enum(['segment', 'word']).nullish().default('segment'),
+
+  /**
+   * Version of the model to use. All of the models are the Whisper large variant. Default value: "3"
+   */
+  version: z.enum(['3']).nullish().default('3'),
+
+  /**
+   * Default value: 64
+   */
+  batchSize: z.number().nullish().default(64),
+
+  /**
+   * Number of speakers in the audio file. Defaults to null. If not provided, the number of speakers will be automatically detected.
+   */
+  numSpeakers: z.number().nullable().nullish(),
+});
+
+export type FalTranscriptionModelOptions = z.infer<
+  typeof falTranscriptionModelOptionsSchema
+>;

package/src/fal-transcription-model.ts

@@ -1,7 +1,7 @@
 import {
   AISDKError,
-  TranscriptionModelV3,
-  SharedV3Warning,
+  type TranscriptionModelV4,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -12,54 +12,16 @@ import {
   getFromApi,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import { FalConfig } from './fal-config';
+import type { FalConfig } from './fal-config';
 import { falErrorDataSchema, falFailedResponseHandler } from './fal-error';
-import { FalTranscriptionModelId } from './fal-transcription-options';
-import { FalTranscriptionAPITypes } from './fal-api-types';
-
-// https://fal.ai/models/fal-ai/whisper/api?platform=http
-const falTranscriptionModelOptionsSchema = z.object({
-  /**
-   * Language of the audio file. If set to null, the language will be automatically detected. Defaults to null.
-   *
-   * If translate is selected as the task, the audio will be translated to English, regardless of the language selected.
-   */
-  language: z
-    .union([z.enum(['en']), z.string()])
-    .nullish()
-    .default('en'),
-
-  /**
-   * Whether to diarize the audio file. Defaults to true.
-   */
-  diarize: z.boolean().nullish().default(true),
-
-  /**
-   * Level of the chunks to return. Either segment or word. Default value: "segment"
-   */
-  chunkLevel: z.enum(['segment', 'word']).nullish().default('segment'),
-
-  /**
-   * Version of the model to use. All of the models are the Whisper large variant. Default value: "3"
-   */
-  version: z.enum(['3']).nullish().default('3'),
-
-  /**
-   * Default value: 64
-   */
-  batchSize: z.number().nullish().default(64),
-
-  /**
-   * Number of speakers in the audio file. Defaults to null. If not provided, the number of speakers will be automatically detected.
-   */
-  numSpeakers: z.number().nullable().nullish(),
-});
-
-export type FalTranscriptionModelOptions = z.infer<
-  typeof falTranscriptionModelOptionsSchema
->;
+import { falTranscriptionModelOptionsSchema } from './fal-transcription-model-options';
+import type { FalTranscriptionModelId } from './fal-transcription-options';
+import type { FalTranscriptionAPITypes } from './fal-api-types';
 
 interface FalTranscriptionModelConfig extends FalConfig {
   _internal?: {
@@ -67,13 +29,27 @@ interface FalTranscriptionModelConfig extends FalConfig {
   };
 }
 
-export class FalTranscriptionModel implements TranscriptionModelV3 {
-  readonly specificationVersion = 'v3';
+export class FalTranscriptionModel implements TranscriptionModelV4 {
+  readonly specificationVersion = 'v4';
 
   get provider(): string {
     return this.config.provider;
   }
 
+  static [WORKFLOW_SERIALIZE](model: FalTranscriptionModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: FalTranscriptionModelId;
+    config: FalTranscriptionModelConfig;
+  }) {
+    return new FalTranscriptionModel(options.modelId, options.config);
+  }
+
   constructor(
     readonly modelId: FalTranscriptionModelId,
     private readonly config: FalTranscriptionModelConfig,
@@ -81,8 +57,8 @@ export class FalTranscriptionModel implements TranscriptionModelV3 {
 
   private async getArgs({
     providerOptions,
-  }: Parameters<TranscriptionModelV3['doGenerate']>[0]) {
-    const warnings: SharedV3Warning[] = [];
+  }: Parameters<TranscriptionModelV4['doGenerate']>[0]) {
+    const warnings: SharedV4Warning[] = [];
 
     // Parse provider options
     const falOptions = await parseProviderOptions({
@@ -121,8 +97,8 @@ export class FalTranscriptionModel implements TranscriptionModelV3 {
   }
 
   async doGenerate(
-    options: Parameters<TranscriptionModelV3['doGenerate']>[0],
-  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+    options: Parameters<TranscriptionModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<TranscriptionModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
     const { body, warnings } = await this.getArgs(options);
 
@@ -138,7 +114,7 @@ export class FalTranscriptionModel implements TranscriptionModelV3 {
         path: `https://queue.fal.run/fal-ai/${this.modelId}`,
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body: {
         ...body,
         audio_url: audioUrl,
@@ -170,7 +146,7 @@ export class FalTranscriptionModel implements TranscriptionModelV3 {
             path: `https://queue.fal.run/fal-ai/${this.modelId}/requests/${queueResponse.request_id}`,
             modelId: this.modelId,
           }),
-          headers: combineHeaders(this.config.headers(), options.headers),
+          headers: combineHeaders(this.config.headers?.(), options.headers),
           failedResponseHandler: async ({
             requestBodyValues,
             response,

package/src/fal-video-model-options.ts

@@ -0,0 +1,39 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export type FalVideoModelOptions = {
+  loop?: boolean | null;
+  motionStrength?: number | null;
+  pollIntervalMs?: number | null;
+  pollTimeoutMs?: number | null;
+  resolution?: string | null;
+  negativePrompt?: string | null;
+  promptOptimizer?: boolean | null;
+  [key: string]: unknown; // For passthrough
+};
+
+// Provider options schema for FAL video generation
+export const falVideoModelOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        // Video loop - only for Luma models
+        loop: z.boolean().nullish(),
+
+        // Motion strength (provider-specific)
+        motionStrength: z.number().min(0).max(1).nullish(),
+
+        // Polling configuration
+        pollIntervalMs: z.number().positive().nullish(),
+        pollTimeoutMs: z.number().positive().nullish(),
+
+        // Resolution (model-specific, e.g., '480p', '720p', '1080p')
+        resolution: z.string().nullish(),
+
+        // Model-specific parameters
+        negativePrompt: z.string().nullish(),
+        promptOptimizer: z.boolean().nullish(),
+      })
+      .passthrough(),
+  ),
+);

package/src/fal-video-model.ts

@@ -1,7 +1,7 @@
 import {
   AISDKError,
-  type Experimental_VideoModelV3,
-  type SharedV3Warning,
+  type Experimental_VideoModelV4,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -10,61 +10,26 @@ import {
   createJsonResponseHandler,
   delay,
   getFromApi,
-  lazySchema,
   parseProviderOptions,
   postJsonToApi,
-  zodSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import type { FalConfig } from './fal-config';
 import { falErrorDataSchema, falFailedResponseHandler } from './fal-error';
+import {
+  falVideoModelOptionsSchema,
+  type FalVideoModelOptions,
+} from './fal-video-model-options';
 import type { FalVideoModelId } from './fal-video-settings';
 
-export type FalVideoModelOptions = {
-  loop?: boolean | null;
-  motionStrength?: number | null;
-  pollIntervalMs?: number | null;
-  pollTimeoutMs?: number | null;
-  resolution?: string | null;
-  negativePrompt?: string | null;
-  promptOptimizer?: boolean | null;
-  [key: string]: unknown; // For passthrough
-};
-
-// Provider options schema for FAL video generation
-export const falVideoModelOptionsSchema = lazySchema(() =>
-  zodSchema(
-    z
-      .object({
-        // Video loop - only for Luma models
-        loop: z.boolean().nullish(),
-
-        // Motion strength (provider-specific)
-        motionStrength: z.number().min(0).max(1).nullish(),
-
-        // Polling configuration
-        pollIntervalMs: z.number().positive().nullish(),
-        pollTimeoutMs: z.number().positive().nullish(),
-
-        // Resolution (model-specific, e.g., '480p', '720p', '1080p')
-        resolution: z.string().nullish(),
-
-        // Model-specific parameters
-        negativePrompt: z.string().nullish(),
-        promptOptimizer: z.boolean().nullish(),
-      })
-      .passthrough(),
-  ),
-);
-
 interface FalVideoModelConfig extends FalConfig {
   _internal?: {
     currentDate?: () => Date;
   };
 }
 
-export class FalVideoModel implements Experimental_VideoModelV3 {
-  readonly specificationVersion = 'v3';
+export class FalVideoModel implements Experimental_VideoModelV4 {
+  readonly specificationVersion = 'v4';
   readonly maxVideosPerCall = 1; // FAL video models support 1 video at a time
 
   get provider(): string {
@@ -81,10 +46,10 @@ export class FalVideoModel implements Experimental_VideoModelV3 {
   ) {}
 
   async doGenerate(
-    options: Parameters<Experimental_VideoModelV3['doGenerate']>[0],
-  ): Promise<Awaited<ReturnType<Experimental_VideoModelV3['doGenerate']>>> {
+    options: Parameters<Experimental_VideoModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<Experimental_VideoModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
-    const warnings: SharedV3Warning[] = [];
+    const warnings: SharedV4Warning[] = [];
 
     const falOptions = (await parseProviderOptions({
       provider: 'fal',
@@ -158,7 +123,7 @@ export class FalVideoModel implements Experimental_VideoModelV3 {
         path: `https://queue.fal.run/fal-ai/${this.normalizedModelId}`,
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body,
       failedResponseHandler: falFailedResponseHandler,
       successfulResponseHandler:
@@ -189,7 +154,7 @@ export class FalVideoModel implements Experimental_VideoModelV3 {
               path: responseUrl,
               modelId: this.modelId,
             }),
-            headers: combineHeaders(this.config.headers(), options.headers),
+            headers: combineHeaders(this.config.headers?.(), options.headers),
             failedResponseHandler: async ({
               response,
               url,

package/src/index.ts

@@ -4,13 +4,13 @@ export type {
   FalImageModelOptions,
   /** @deprecated Use `FalImageModelOptions` instead. */
   FalImageModelOptions as FalImageProviderOptions,
-} from './fal-image-options';
-export type { FalSpeechModelOptions } from './fal-speech-model';
-export type { FalTranscriptionModelOptions } from './fal-transcription-model';
+} from './fal-image-model-options';
+export type { FalSpeechModelOptions } from './fal-speech-model-options';
+export type { FalTranscriptionModelOptions } from './fal-transcription-model-options';
 export type {
   FalVideoModelOptions,
   /** @deprecated Use `FalVideoModelOptions` instead. */
   FalVideoModelOptions as FalVideoProviderOptions,
-} from './fal-video-model';
+} from './fal-video-model-options';
 export type { FalVideoModelId } from './fal-video-settings';
 export { VERSION } from './version';