@ai-sdk/provider 3.0.7 → 4.0.0-beta.0

package/src/speech-model/index.ts

@@ -1,2 +1,3 @@
-export * from './v2/index';
+export * from './v4/index';
 export * from './v3/index';
+export * from './v2/index';

package/src/speech-model/v4/index.ts

@@ -0,0 +1,2 @@
+export type { SpeechModelV4 } from './speech-model-v4';
+export type { SpeechModelV4CallOptions } from './speech-model-v4-call-options';

package/src/speech-model/v4/speech-model-v4-call-options.ts

@@ -0,0 +1,62 @@
+import { JSONObject } from '../../json-value/json-value';
+
+type SpeechModelV4ProviderOptions = Record<string, JSONObject>;
+
+export type SpeechModelV4CallOptions = {
+  /**
+   * Text to convert to speech.
+   */
+  text: string;
+
+  /**
+   * The voice to use for speech synthesis.
+   * This is provider-specific and may be a voice ID, name, or other identifier.
+   */
+  voice?: string;
+
+  /**
+   * The desired output format for the audio e.g. "mp3", "wav", etc.
+   */
+  outputFormat?: string;
+
+  /**
+   * Instructions for the speech generation e.g. "Speak in a slow and steady tone".
+   */
+  instructions?: string;
+
+  /**
+   * The speed of the speech generation.
+   */
+  speed?: number;
+
+  /**
+   * The language for speech generation. This should be an ISO 639-1 language code (e.g. "en", "es", "fr")
+   * or "auto" for automatic language detection. Provider support varies.
+   */
+  language?: string;
+
+  /**
+   * Additional provider-specific options that are passed through to the provider
+   * as body parameters.
+   *
+   * The outer record is keyed by the provider name, and the inner
+   * record is keyed by the provider-specific metadata key.
+   * ```ts
+   * {
+   *   "openai": {}
+   * }
+   * ```
+   */
+  providerOptions?: SpeechModelV4ProviderOptions;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+};

package/src/speech-model/v4/speech-model-v4.ts

@@ -0,0 +1,89 @@
+import { JSONObject } from '../../json-value';
+import { SharedV2Headers } from '../../shared';
+import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+import { SpeechModelV4CallOptions } from './speech-model-v4-call-options';
+
+/**
+ * Speech model specification version 3.
+ */
+export type SpeechModelV4 = {
+  /**
+   * The speech model must specify which speech model interface
+   * version it implements. This will allow us to evolve the speech
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Generates speech audio from text.
+   */
+  doGenerate(options: SpeechModelV4CallOptions): PromiseLike<{
+    /**
+     * Generated audio as an ArrayBuffer.
+     * The audio should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the audio should be returned
+     * as base64 encoded strings. If the API returns binary data, the audio
+     * should be returned as binary data.
+     */
+    audio: string | Uint8Array;
+
+    /**
+     * Warnings for the call, e.g. unsupported settings.
+     */
+    warnings: Array<SharedV4Warning>;
+
+    /**
+     * Optional request information for telemetry and debugging purposes.
+     */
+    request?: {
+      /**
+       * Response body (available only for providers that use HTTP requests).
+       */
+      body?: unknown;
+    };
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers?: SharedV2Headers;
+
+      /**
+       * Response body.
+       */
+      body?: unknown;
+    };
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: Record<string, JSONObject>;
+  }>;
+};

package/src/transcription-model/index.ts

@@ -1,2 +1,3 @@
-export * from './v2/index';
+export * from './v4/index';
 export * from './v3/index';
+export * from './v2/index';

package/src/transcription-model/v4/index.ts

@@ -0,0 +1,2 @@
+export type { TranscriptionModelV4 } from './transcription-model-v4';
+export type { TranscriptionModelV4CallOptions } from './transcription-model-v4-call-options';

package/src/transcription-model/v4/transcription-model-v4-call-options.ts

@@ -0,0 +1,45 @@
+import { JSONObject } from '../../json-value/json-value';
+
+type TranscriptionModelV4ProviderOptions = Record<string, JSONObject>;
+
+export type TranscriptionModelV4CallOptions = {
+  /**
+   * Audio data to transcribe.
+   * Accepts a `Uint8Array` or `string`, where `string` is a base64 encoded audio file.
+   */
+  audio: Uint8Array | string;
+
+  /**
+   * The IANA media type of the audio data.
+   *
+   * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType: string;
+
+  /**
+   * Additional provider-specific options that are passed through to the provider
+   * as body parameters.
+   *
+   * The outer record is keyed by the provider name, and the inner
+   * record is keyed by the provider-specific metadata key.
+   * ```ts
+   * {
+   * "openai": {
+   * "timestampGranularities": ["word"]
+   * }
+   * }
+   * ```
+   */
+  providerOptions?: TranscriptionModelV4ProviderOptions;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+};

package/src/transcription-model/v4/transcription-model-v4.ts

@@ -0,0 +1,117 @@
+import { JSONObject } from '../../json-value';
+import { SharedV4Headers } from '../../shared';
+import { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+import { TranscriptionModelV4CallOptions } from './transcription-model-v4-call-options';
+
+/**
+ * Transcription model specification version 3.
+ */
+export type TranscriptionModelV4 = {
+  /**
+   * The transcription model must specify which transcription model interface
+   * version it implements. This will allow us to evolve the transcription
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Generates a transcript.
+   */
+  doGenerate(options: TranscriptionModelV4CallOptions): PromiseLike<{
+    /**
+     * The complete transcribed text from the audio.
+     */
+    text: string;
+
+    /**
+     * Array of transcript segments with timing information.
+     * Each segment represents a portion of the transcribed text with start and end times.
+     */
+    segments: Array<{
+      /**
+       * The text content of this segment.
+       */
+      text: string;
+      /**
+       * The start time of this segment in seconds.
+       */
+      startSecond: number;
+      /**
+       * The end time of this segment in seconds.
+       */
+      endSecond: number;
+    }>;
+
+    /**
+     * The detected language of the audio content, as an ISO-639-1 code (e.g., 'en' for English).
+     * May be undefined if the language couldn't be detected.
+     */
+    language: string | undefined;
+
+    /**
+     * The total duration of the audio file in seconds.
+     * May be undefined if the duration couldn't be determined.
+     */
+    durationInSeconds: number | undefined;
+
+    /**
+     * Warnings for the call, e.g. unsupported settings.
+     */
+    warnings: Array<SharedV4Warning>;
+
+    /**
+     * Optional request information for telemetry and debugging purposes.
+     */
+    request?: {
+      /**
+       * Raw request HTTP body that was sent to the provider API as a string (JSON should be stringified).
+       * Non-HTTP(s) providers should not set this.
+       */
+      body?: string;
+    };
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers?: SharedV4Headers;
+
+      /**
+       * Response body.
+       */
+      body?: unknown;
+    };
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     */
+    providerMetadata?: Record<string, JSONObject>;
+  }>;
+};

package/src/video-model/index.ts

@@ -1 +1,2 @@
+export * from './v4/index';
 export * from './v3/index';

package/src/video-model/v4/index.ts

@@ -0,0 +1,6 @@
+export type {
+  VideoModelV4 as Experimental_VideoModelV4,
+  VideoModelV4VideoData as Experimental_VideoModelV4VideoData,
+} from './video-model-v4';
+export type { VideoModelV4CallOptions as Experimental_VideoModelV4CallOptions } from './video-model-v4-call-options';
+export type { VideoModelV4File as Experimental_VideoModelV4File } from './video-model-v4-file';

package/src/video-model/v4/video-model-v4-call-options.ts

@@ -0,0 +1,81 @@
+import { SharedV4ProviderOptions } from '../../shared';
+import { VideoModelV4File } from './video-model-v4-file';
+
+export type VideoModelV4CallOptions = {
+  /**
+   * Text prompt for the video generation.
+   */
+  prompt: string | undefined;
+
+  /**
+   * Number of videos to generate. Default: 1.
+   * Most video models only support n=1 due to computational cost.
+   */
+  n: number;
+
+  /**
+   * Aspect ratio of the videos to generate.
+   * Must have the format `{width}:{height}`.
+   * `undefined` will use the provider's default aspect ratio.
+   * Common values: '16:9', '9:16', '1:1', '21:9', '4:3'
+   */
+  aspectRatio: `${number}:${number}` | undefined;
+
+  /**
+   * Resolution of the video to generate.
+   * Format: `{width}x{height}` (e.g., '1280x720', '1920x1080')
+   * `undefined` will use the provider's default resolution.
+   */
+  resolution: `${number}x${number}` | undefined;
+
+  /**
+   * Duration of the video in seconds.
+   * `undefined` will use the provider's default duration.
+   * Typically 3-10 seconds for most models.
+   */
+  duration: number | undefined;
+
+  /**
+   * Frames per second (FPS) for the video.
+   * `undefined` will use the provider's default FPS.
+   * Common values: 24, 30, 60
+   */
+  fps: number | undefined;
+
+  /**
+   * Seed for deterministic video generation.
+   * `undefined` will use a random seed.
+   */
+  seed: number | undefined;
+
+  /**
+   * Input image for image-to-video generation.
+   * The image serves as the starting frame that the model will animate.
+   */
+  image: VideoModelV4File | undefined;
+
+  /**
+   * Additional provider-specific options that are passed through to the provider
+   * as body parameters.
+   *
+   * Example:
+   * {
+   *   "fal": {
+   *     "loop": true,
+   *     "motionStrength": 0.8
+   *   }
+   * }
+   */
+  providerOptions: SharedV4ProviderOptions;
+
+  /**
+   * Abort signal for cancelling the operation.
+   */
+  abortSignal?: AbortSignal;
+
+  /**
+   * Additional HTTP headers to be sent with the request.
+   * Only applicable for HTTP-based providers.
+   */
+  headers?: Record<string, string | undefined>;
+};

package/src/video-model/v4/video-model-v4-file.ts

@@ -0,0 +1,40 @@
+import { SharedV4ProviderMetadata } from '../../shared';
+
+/**
+ * A video or image file that can be used for video editing or image-to-video generation.
+ * Supports both image inputs (for image-to-video) and video inputs (for editing).
+ */
+export type VideoModelV4File =
+  | {
+      type: 'file';
+
+      /**
+       * The IANA media type of the file.
+       * Video types: 'video/mp4', 'video/webm', 'video/quicktime'
+       * Image types: 'image/png', 'image/jpeg', 'image/webp'
+       */
+      mediaType: string;
+
+      /**
+       * File data as base64 encoded string or binary data.
+       */
+      data: string | Uint8Array;
+
+      /**
+       * Optional provider-specific metadata for the file part.
+       */
+      providerOptions?: SharedV4ProviderMetadata;
+    }
+  | {
+      type: 'url';
+
+      /**
+       * The URL of the video or image file.
+       */
+      url: string;
+
+      /**
+       * Optional provider-specific metadata for the file part.
+       */
+      providerOptions?: SharedV4ProviderMetadata;
+    };

package/src/video-model/v4/video-model-v4.ts

@@ -0,0 +1,132 @@
+import type { VideoModelV4CallOptions } from './video-model-v4-call-options';
+import type { SharedV4ProviderMetadata } from '../../shared/v4/shared-v4-provider-metadata';
+import type { SharedV4Warning } from '../../shared/v4/shared-v4-warning';
+
+type GetMaxVideosPerCallFunction = (options: {
+  modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+
+/**
+ * Generated video data. Can be a URL, base64-encoded string, or binary data.
+ */
+export type VideoModelV4VideoData =
+  | {
+      /**
+       * Video available as a URL (most common for video providers).
+       */
+      type: 'url';
+      url: string;
+      mediaType: string;
+    }
+  | {
+      /**
+       * Video as base64-encoded string.
+       */
+      type: 'base64';
+      data: string;
+      mediaType: string;
+    }
+  | {
+      /**
+       * Video as binary data.
+       */
+      type: 'binary';
+      data: Uint8Array;
+      mediaType: string;
+    };
+
+/**
+ * Video generation model specification version 3.
+ */
+export type VideoModelV4 = {
+  /**
+   * The video model must specify which video model interface
+   * version it implements. This will allow us to evolve the video
+   * model interface and retain backwards compatibility. The different
+   * implementation versions can be handled as a discriminated union
+   * on our side.
+   */
+  readonly specificationVersion: 'v4';
+
+  /**
+   * Name of the provider for logging purposes.
+   */
+  readonly provider: string;
+
+  /**
+   * Provider-specific model ID for logging purposes.
+   */
+  readonly modelId: string;
+
+  /**
+   * Limit of how many videos can be generated in a single API call.
+   * Can be set to a number for a fixed limit, to undefined to use
+   * the global limit, or a function that returns a number or undefined,
+   * optionally as a promise.
+   *
+   * Most video models only support generating 1 video at a time due to
+   * computational cost. Default is typically 1.
+   */
+  readonly maxVideosPerCall: number | undefined | GetMaxVideosPerCallFunction;
+
+  /**
+   * Generates an array of videos.
+   */
+  doGenerate(options: VideoModelV4CallOptions): PromiseLike<{
+    /**
+     * Generated videos as URLs, base64 strings, or binary data.
+     *
+     * Most providers return URLs to video files (MP4, WebM) due to large file sizes.
+     * Use the discriminated union to indicate the type of video data being returned.
+     */
+    videos: Array<VideoModelV4VideoData>;
+
+    /**
+     * Warnings for the call, e.g. unsupported features.
+     */
+    warnings: Array<SharedV4Warning>;
+
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * from the provider to the AI SDK and enable provider-specific
+     * results that can be fully encapsulated in the provider.
+     *
+     * The outer record is keyed by the provider name, and the inner
+     * record is provider-specific metadata.
+     *
+     * ```ts
+     * {
+     *   "fal": {
+     *     "videos": [{
+     *       "duration": 5.0,
+     *       "fps": 24,
+     *       "width": 1280,
+     *       "height": 720
+     *     }]
+     *   }
+     * }
+     * ```
+     */
+    providerMetadata?: SharedV4ProviderMetadata;
+
+    /**
+     * Response information for telemetry and debugging purposes.
+     */
+    response: {
+      /**
+       * Timestamp for the start of the generated response.
+       */
+      timestamp: Date;
+
+      /**
+       * The ID of the response model that was used to generate the response.
+       */
+      modelId: string;
+
+      /**
+       * Response headers.
+       */
+      headers: Record<string, string> | undefined;
+    };
+  }>;
+};