@ai-sdk/fal 2.0.9 → 2.0.11

package/src/fal-provider.ts

@@ -0,0 +1,183 @@
+import {
+  ImageModelV3,
+  NoSuchModelError,
+  ProviderV3,
+  SpeechModelV3,
+  TranscriptionModelV3,
+} from '@ai-sdk/provider';
+import type { FetchFunction } from '@ai-sdk/provider-utils';
+import {
+  withoutTrailingSlash,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { FalImageModel } from './fal-image-model';
+import { FalImageModelId } from './fal-image-settings';
+import { FalTranscriptionModelId } from './fal-transcription-options';
+import { FalTranscriptionModel } from './fal-transcription-model';
+import { FalSpeechModelId } from './fal-speech-settings';
+import { FalSpeechModel } from './fal-speech-model';
+import { VERSION } from './version';
+
+export interface FalProviderSettings {
+  /**
+fal.ai API key. Default value is taken from the `FAL_API_KEY` environment
+variable, falling back to `FAL_KEY`.
+  */
+  apiKey?: string;
+
+  /**
+Base URL for the API calls.
+The default prefix is `https://fal.run`.
+   */
+  baseURL?: string;
+
+  /**
+Custom headers to include in the requests.
+   */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept
+requests, or to provide a custom fetch implementation for e.g. testing.
+   */
+  fetch?: FetchFunction;
+}
+
+export interface FalProvider extends ProviderV3 {
+  /**
+Creates a model for image generation.
+   */
+  image(modelId: FalImageModelId): ImageModelV3;
+
+  /**
+Creates a model for image generation.
+   */
+  imageModel(modelId: FalImageModelId): ImageModelV3;
+
+  /**
+Creates a model for transcription.
+   */
+  transcription(modelId: FalTranscriptionModelId): TranscriptionModelV3;
+
+  /**
+Creates a model for speech generation.
+   */
+  speech(modelId: FalSpeechModelId): SpeechModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+const defaultBaseURL = 'https://fal.run';
+
+function loadFalApiKey({
+  apiKey,
+  description = 'fal.ai',
+}: {
+  apiKey: string | undefined;
+  description?: string;
+}): string {
+  if (typeof apiKey === 'string') {
+    return apiKey;
+  }
+
+  if (apiKey != null) {
+    throw new Error(`${description} API key must be a string.`);
+  }
+
+  if (typeof process === 'undefined') {
+    throw new Error(
+      `${description} API key is missing. Pass it using the 'apiKey' parameter. Environment variables are not supported in this environment.`,
+    );
+  }
+
+  let envApiKey = process.env.FAL_API_KEY;
+  if (envApiKey == null) {
+    envApiKey = process.env.FAL_KEY;
+  }
+
+  if (envApiKey == null) {
+    throw new Error(
+      `${description} API key is missing. Pass it using the 'apiKey' parameter or set either the FAL_API_KEY or FAL_KEY environment variable.`,
+    );
+  }
+
+  if (typeof envApiKey !== 'string') {
+    throw new Error(
+      `${description} API key must be a string. The value of the environment variable is not a string.`,
+    );
+  }
+
+  return envApiKey;
+}
+
+/**
+Create a fal.ai provider instance.
+ */
+export function createFal(options: FalProviderSettings = {}): FalProvider {
+  const baseURL = withoutTrailingSlash(options.baseURL ?? defaultBaseURL);
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Key ${loadFalApiKey({
+          apiKey: options.apiKey,
+        })}`,
+        ...options.headers,
+      },
+      `ai-sdk/fal/${VERSION}`,
+    );
+
+  const createImageModel = (modelId: FalImageModelId) =>
+    new FalImageModel(modelId, {
+      provider: 'fal.image',
+      baseURL: baseURL ?? defaultBaseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const createSpeechModel = (modelId: FalSpeechModelId) =>
+    new FalSpeechModel(modelId, {
+      provider: `fal.speech`,
+      url: ({ path }) => path,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const createTranscriptionModel = (modelId: FalTranscriptionModelId) =>
+    new FalTranscriptionModel(modelId, {
+      provider: `fal.transcription`,
+      url: ({ path }) => path,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+    });
+  };
+
+  return {
+    specificationVersion: 'v3' as const,
+    imageModel: createImageModel,
+    image: createImageModel,
+    languageModel: (modelId: string) => {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: 'languageModel',
+      });
+    },
+    speech: createSpeechModel,
+    embeddingModel,
+    textEmbeddingModel: embeddingModel,
+    transcription: createTranscriptionModel,
+  };
+}
+
+/**
+Default fal.ai provider instance.
+ */
+export const fal = createFal();

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

@@ -0,0 +1,128 @@
+import { createTestServer } from '@ai-sdk/test-server/with-vitest';
+import { createFal } from './fal-provider';
+import { FalSpeechModel } from './fal-speech-model';
+import { describe, it, expect } from 'vitest';
+
+const provider = createFal({ apiKey: 'test-api-key' });
+const model = provider.speech('fal-ai/minimax/speech-02-hd');
+
+const server = createTestServer({
+  'https://fal.run/fal-ai/minimax/speech-02-hd': {},
+  'https://fal.media/files/test.mp3': {},
+});
+
+describe('FalSpeechModel.doGenerate', () => {
+  function prepareResponses({
+    jsonHeaders,
+    audioHeaders,
+  }: {
+    jsonHeaders?: Record<string, string>;
+    audioHeaders?: Record<string, string>;
+  } = {}) {
+    const audioBuffer = new Uint8Array(100);
+    server.urls['https://fal.run/fal-ai/minimax/speech-02-hd'].response = {
+      type: 'json-value',
+      headers: {
+        'content-type': 'application/json',
+        ...jsonHeaders,
+      },
+      body: {
+        audio: { url: 'https://fal.media/files/test.mp3' },
+        duration_ms: 1234,
+      },
+    };
+    server.urls['https://fal.media/files/test.mp3'].response = {
+      type: 'binary',
+      headers: {
+        'content-type': 'audio/mp3',
+        ...audioHeaders,
+      },
+      body: Buffer.from(audioBuffer),
+    };
+    return audioBuffer;
+  }
+
+  it('should pass text and default output_format', async () => {
+    prepareResponses();
+
+    await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(await server.calls[0].requestBodyJson).toMatchObject({
+      text: 'Hello from the AI SDK!',
+      output_format: 'url',
+    });
+  });
+
+  it('should pass headers', async () => {
+    prepareResponses();
+
+    const provider = createFal({
+      apiKey: 'test-api-key',
+      headers: {
+        'Custom-Provider-Header': 'provider-header-value',
+      },
+    });
+
+    await provider.speech('fal-ai/minimax/speech-02-hd').doGenerate({
+      text: 'Hello from the AI SDK!',
+      headers: {
+        'Custom-Request-Header': 'request-header-value',
+      },
+    });
+
+    expect(server.calls[0].requestHeaders).toMatchObject({
+      authorization: 'Key test-api-key',
+      'content-type': 'application/json',
+      'custom-provider-header': 'provider-header-value',
+      'custom-request-header': 'request-header-value',
+    });
+  });
+
+  it('should return audio data', async () => {
+    const audio = prepareResponses();
+
+    const result = await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(result.audio).toStrictEqual(audio);
+  });
+
+  it('should include response data with timestamp, modelId and headers', async () => {
+    prepareResponses({ jsonHeaders: { 'x-request-id': 'test-request-id' } });
+
+    const testDate = new Date(0);
+    const customModel = new FalSpeechModel('fal-ai/minimax/speech-02-hd', {
+      provider: 'fal.speech',
+      url: ({ path }) => path,
+      headers: () => ({}),
+      _internal: { currentDate: () => testDate },
+    });
+
+    const result = await customModel.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(result.response).toMatchObject({
+      timestamp: testDate,
+      modelId: 'fal-ai/minimax/speech-02-hd',
+      headers: expect.objectContaining({ 'x-request-id': 'test-request-id' }),
+    });
+  });
+
+  it('should include warnings for unsupported settings', async () => {
+    prepareResponses();
+
+    const result = await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+      language: 'en',
+      // invalid outputFormat triggers a warning and defaults to url
+      // (we still return audio via URL)
+      outputFormat: 'wav',
+    });
+
+    expect(result.warnings.length).toBeGreaterThan(0);
+  });
+});

package/src/fal-speech-model.ts

@@ -0,0 +1,156 @@
+import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createBinaryResponseHandler,
+  createJsonResponseHandler,
+  createStatusCodeErrorResponseHandler,
+  getFromApi,
+  parseProviderOptions,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { 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 falSpeechProviderOptionsSchema = 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 FalSpeechCallOptions = z.infer<
+  typeof falSpeechProviderOptionsSchema
+>;
+
+interface FalSpeechModelConfig extends FalConfig {
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class FalSpeechModel implements SpeechModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: FalSpeechModelId,
+    private readonly config: FalSpeechModelConfig,
+  ) {}
+
+  private async getArgs({
+    text,
+    voice,
+    outputFormat,
+    speed,
+    language,
+    providerOptions,
+  }: Parameters<SpeechModelV3['doGenerate']>[0]) {
+    const warnings: SharedV3Warning[] = [];
+
+    const falOptions = await parseProviderOptions({
+      provider: 'fal',
+      providerOptions,
+      schema: falSpeechProviderOptionsSchema,
+    });
+
+    const requestBody = {
+      text,
+      output_format: outputFormat === 'hex' ? 'hex' : 'url',
+      voice,
+      speed,
+      ...falOptions,
+    };
+
+    // Language is not directly supported; warn and ignore
+    if (language) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'language',
+        details:
+          "fal speech models don't support 'language' directly; consider providerOptions.fal.language_boost",
+      });
+    }
+
+    // warn on invalid values (and on hex until we support hex response handling)
+    if (outputFormat && outputFormat !== 'url' && outputFormat !== 'hex') {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'outputFormat',
+        details: `Unsupported outputFormat: ${outputFormat}. Using 'url' instead.`,
+      });
+    }
+
+    return { requestBody, warnings } as const;
+  }
+
+  async doGenerate(
+    options: Parameters<SpeechModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { requestBody, warnings } = await this.getArgs(options);
+
+    const {
+      value: json,
+      responseHeaders,
+      rawValue,
+    } = await postJsonToApi({
+      url: this.config.url({
+        path: `https://fal.run/${this.modelId}`,
+        modelId: this.modelId,
+      }),
+      headers: combineHeaders(this.config.headers(), options.headers),
+      body: requestBody,
+      failedResponseHandler: falFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        falSpeechResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const audioUrl = json.audio.url;
+    const { value: audio } = await getFromApi({
+      url: audioUrl,
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      successfulResponseHandler: createBinaryResponseHandler(),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      audio,
+      warnings,
+      request: {
+        body: JSON.stringify(requestBody),
+      },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawValue,
+      },
+    };
+  }
+}
+
+const falSpeechResponseSchema = z.object({
+  audio: z.object({ url: z.string() }),
+  duration_ms: z.number().optional(),
+  request_id: z.string().optional(),
+});

package/src/fal-speech-settings.ts

@@ -0,0 +1,10 @@
+// https://fal.ai/explore/search?categories=text-to-speech&q=newest
+export type FalSpeechModelId =
+  | 'fal-ai/minimax/voice-clone'
+  | 'fal-ai/minimax/voice-design'
+  | 'fal-ai/dia-tts/voice-clone'
+  | 'fal-ai/minimax/speech-02-hd'
+  | 'fal-ai/minimax/speech-02-turbo'
+  | 'fal-ai/dia-tts'
+  | 'resemble-ai/chatterboxhd/text-to-speech'
+  | (string & {});

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

@@ -0,0 +1,181 @@
+import { createTestServer } from '@ai-sdk/test-server/with-vitest';
+import { createFal } from './fal-provider';
+import { FalTranscriptionModel } from './fal-transcription-model';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+
+const audioData = await readFile(path.join(__dirname, 'transcript-test.mp3'));
+const provider = createFal({ apiKey: 'test-api-key' });
+const model = provider.transcription('wizper');
+
+const server = createTestServer({
+  'https://queue.fal.run/fal-ai/wizper': {},
+  'https://queue.fal.run/fal-ai/wizper/requests/test-id': {},
+});
+
+describe('doGenerate', () => {
+  function prepareJsonResponse({
+    headers,
+  }: {
+    headers?: Record<string, string>;
+  } = {}) {
+    server.urls['https://queue.fal.run/fal-ai/wizper'].response = {
+      type: 'json-value',
+      headers,
+      body: {
+        status: 'COMPLETED',
+        request_id: 'test-id',
+        response_url:
+          'https://queue.fal.run/fal-ai/wizper/requests/test-id/result',
+        status_url: 'https://queue.fal.run/fal-ai/wizper/requests/test-id',
+        cancel_url:
+          'https://queue.fal.run/fal-ai/wizper/requests/test-id/cancel',
+        logs: null,
+        metrics: {},
+        queue_position: 0,
+      },
+    };
+    server.urls[
+      'https://queue.fal.run/fal-ai/wizper/requests/test-id'
+    ].response = {
+      type: 'json-value',
+      headers,
+      body: {
+        text: 'Hello world!',
+        chunks: [
+          {
+            text: 'Hello',
+            timestamp: [0, 1],
+            speaker: 'speaker_1',
+          },
+          {
+            text: ' ',
+            timestamp: [1, 2],
+            speaker: 'speaker_1',
+          },
+          {
+            text: 'world!',
+            timestamp: [2, 3],
+            speaker: 'speaker_1',
+          },
+        ],
+        diarization_segments: [
+          {
+            speaker: 'speaker_1',
+            timestamp: [0, 3],
+          },
+        ],
+      },
+    };
+  }
+
+  it('should pass the model', async () => {
+    prepareJsonResponse();
+
+    await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(await server.calls[0].requestBodyJson).toMatchObject({
+      audio_url: expect.stringMatching(/^data:audio\//),
+      task: 'transcribe',
+      diarize: true,
+      chunk_level: 'word',
+    });
+  });
+
+  it('should pass headers', async () => {
+    prepareJsonResponse();
+
+    const provider = createFal({
+      apiKey: 'test-api-key',
+      headers: {
+        'Custom-Provider-Header': 'provider-header-value',
+      },
+    });
+
+    await provider.transcription('wizper').doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      headers: {
+        'Custom-Request-Header': 'request-header-value',
+      },
+    });
+
+    expect(server.calls[0].requestHeaders).toMatchObject({
+      authorization: 'Key test-api-key',
+      'content-type': 'application/json',
+      'custom-provider-header': 'provider-header-value',
+      'custom-request-header': 'request-header-value',
+    });
+  });
+
+  it('should extract the transcription text', async () => {
+    prepareJsonResponse();
+
+    const result = await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.text).toBe('Hello world!');
+  });
+
+  it('should include response data with timestamp, modelId and headers', async () => {
+    prepareJsonResponse({
+      headers: {
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+
+    const testDate = new Date(0);
+    const customModel = new FalTranscriptionModel('wizper', {
+      provider: 'test-provider',
+      url: ({ path }) => path,
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response).toMatchObject({
+      timestamp: testDate,
+      modelId: 'wizper',
+      headers: {
+        'content-type': 'application/json',
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+  });
+
+  it('should use real date when no custom date provider is specified', async () => {
+    prepareJsonResponse();
+
+    const testDate = new Date(0);
+    const customModel = new FalTranscriptionModel('wizper', {
+      provider: 'test-provider',
+      url: ({ path }) => path,
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response.timestamp.getTime()).toEqual(testDate.getTime());
+    expect(result.response.modelId).toBe('wizper');
+  });
+});