@ai-sdk/provider 4.0.13 → 4.0.15

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @ai-sdk/provider
 
+## 4.0.15
+
+### Patch Changes
+
+- 5c0054d: Add optional browser-direct WebRTC for experimental client-delegated Live conversations alongside the existing WebSocket path. Exchange SDP through an application endpoint with `api.session`, configure server-owned data-channel permissions, and preserve committed React session ownership. Capture follows the selected sender track, borrowed tracks remain caller-owned, and disconnect recovery and finalization stay bounded. Applications continue to handle client delegation and submit context; Live session updates and Responses delegation remain unsupported.
+
+  Serialize microphone sender changes and close the peer if detachment fails, without stopping borrowed tracks. Validate nonempty SDP setup answers with a bounded response body, and document the same-origin broker authentication contract.
+
+- 39535af: Add experimental OpenAI Live provider support through the unified `openai.experimental_realtime` factory for server WebSocket sessions with client delegation. Applications own their agents and tools, receive continuous audio/transcript events and delegation metadata, and return context through validated channels. Support immutable startup options, microphone mute controls, graceful session close, and cumulative voice usage. Responses delegation and Live session updates reject before sending.
+
+  Route known Live model IDs to Live, allow an OpenAI-specific `api` override for early-access models, and preserve legacy Realtime defaults for unknown IDs. Token minting follows the same selection rules and rejects Live before requesting unsupported credentials. Extend the realtime v4 specification with optional server WebSocket configuration, per-connection raw-event parsers, and model-wide startup/finalization capabilities. This provider layer supplies connection settings and protocol mapping for server adapters; browser lifecycle and UI integration belong to the core runtime and framework hooks.
+
+  Preserve Realtime client event IDs for session updates and audio appends, and correlate server errors with the originating client event.
+
+## 4.0.14
+
+### Patch Changes
+
+- 5ec21a6: fix: reject unsupported batch request types
+- 7469a3b: feat: support image generation requests in batches
+
 ## 4.0.13
 
 ### Patch Changes

package/dist/index.d.ts

@@ -736,6 +736,247 @@ type LanguageModelV4GenerateResult = {
     warnings: Array<SharedV4Warning>;
 };
 
+/**
+ * An image file that can be used for image editing or variation generation.
+ */
+type ImageModelV4File = {
+    type: 'file';
+    /**
+     * The IANA media type of the file, e.g. `image/png`. Any string is supported.
+     *
+     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+     */
+    mediaType: string;
+    /**
+     * Generated file data as base64 encoded strings or binary data.
+     *
+     * The file data should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the file data should be returned
+     * as base64 encoded strings. If the API returns binary data, the file data should
+     * be returned as binary data.
+     */
+    data: string | Uint8Array;
+    /**
+     * Optional provider-specific metadata for the file part.
+     */
+    providerOptions?: SharedV4ProviderMetadata;
+} | {
+    type: 'url';
+    /**
+     * The URL of the image file.
+     */
+    url: string;
+    /**
+     * Optional provider-specific metadata for the file part.
+     */
+    providerOptions?: SharedV4ProviderMetadata;
+};
+
+type ImageModelV4CallOptions = {
+    /**
+     * Prompt for the image generation. Some operations, like upscaling, may not require a prompt.
+     */
+    prompt: string | undefined;
+    /**
+     * Number of images to generate.
+     */
+    n: number;
+    /**
+     * Size of the images to generate.
+     * Must have the format `{width}x{height}`.
+     * `undefined` will use the provider's default size.
+     */
+    size: `${number}x${number}` | undefined;
+    /**
+     * Aspect ratio of the images to generate.
+     * Must have the format `{width}:{height}`.
+     * `undefined` will use the provider's default aspect ratio.
+     */
+    aspectRatio: `${number}:${number}` | undefined;
+    /**
+     * Seed for the image generation.
+     * `undefined` will use the provider's default seed.
+     */
+    seed: number | undefined;
+    /**
+     * Array of images for image editing or variation generation.
+     * The images should be provided as base64 encoded strings or binary data.
+     */
+    files: ImageModelV4File[] | undefined;
+    /**
+     * Mask image for inpainting operations.
+     * The mask should be provided as base64 encoded strings or binary data.
+     */
+    mask: ImageModelV4File | undefined;
+    /**
+     * 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": {
+     *     "style": "vivid"
+     *   }
+     * }
+     * ```
+     */
+    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>;
+};
+
+/**
+ * Usage information for an image model call.
+ */
+type ImageModelV4Usage = {
+    /**
+     * The number of input (prompt) tokens used.
+     */
+    inputTokens: number | undefined;
+    /**
+     * The number of output tokens used, if reported by the provider.
+     */
+    outputTokens: number | undefined;
+    /**
+     * The total number of tokens as reported by the provider.
+     */
+    totalTokens: number | undefined;
+};
+
+type ImageModelV4ProviderMetadata = Record<string, {
+    images: JSONArray;
+} & JSONValue>;
+/**
+ * The result of an image model doGenerate call.
+ */
+type ImageModelV4Result = {
+    /**
+     * Generated images as base64 encoded strings or binary data.
+     * The images should be returned without any unnecessary conversion.
+     * If the API returns base64 encoded strings, the images should be returned
+     * as base64 encoded strings. If the API returns binary data, the images should
+     * be returned as binary data.
+     */
+    images: Array<string> | Array<Uint8Array>;
+    /**
+     * Whether an unsuccessful result, such as an empty image result, can be
+     * retried. When omitted, the result is unclassified.
+     */
+    isRetryable?: boolean;
+    /**
+     * 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. It always includes an
+     * `images` key with image-specific metadata
+     *
+     * ```ts
+     * {
+     * "openai": {
+     * "images": ["revisedPrompt": "Revised prompt here."]
+     * }
+     * }
+     * ```
+     */
+    providerMetadata?: ImageModelV4ProviderMetadata;
+    /**
+     * 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;
+    };
+    /**
+     * Optional token usage for the image generation call (if the provider reports it).
+     */
+    usage?: ImageModelV4Usage;
+};
+
+type GetMaxImagesPerCallFunction$2 = (options: {
+    modelId: string;
+}) => PromiseLike<number | undefined> | number | undefined;
+/**
+ * Image generation model specification version 4.
+ */
+type ImageModelV4 = {
+    /**
+     * The image model must specify which image model interface
+     * version it implements. This will allow us to evolve the image
+     * 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 images 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.
+     */
+    readonly maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction$2;
+    /**
+     * Generates an array of images.
+     */
+    doGenerate(options: ImageModelV4CallOptions): PromiseLike<ImageModelV4Result>;
+};
+
+/**
+ * Fields shared by every request in a batch.
+ */
+type BatchV4RequestBase<ModelId extends string = string> = {
+    /**
+     * Application-provided identifier used to correlate the request with its
+     * result.
+     */
+    readonly id: string;
+    /**
+     * Provider-specific model ID for this request.
+     */
+    readonly modelId: ModelId;
+};
+
+/**
+ * One image generation request in a batch.
+ */
+type ImageBatchV4Request<ModelId extends string = string> = BatchV4RequestBase<ModelId> & {
+    readonly type: 'image';
+    readonly options: Pick<ImageModelV4CallOptions, 'prompt' | 'n' | 'size' | 'aspectRatio' | 'seed' | 'files' | 'mask' | 'providerOptions'>;
+};
+
 /**
  * A tool has a name, a description, and a set of parameters.
  *
@@ -1249,21 +1490,6 @@ type LanguageModelV4CallOptions = {
     providerOptions?: SharedV4ProviderOptions;
 };
 
-/**
- * Fields shared by every request in a batch.
- */
-type BatchV4RequestBase<ModelId extends string = string> = {
-    /**
-     * Application-provided identifier used to correlate the request with its
-     * result.
-     */
-    readonly id: string;
-    /**
-     * Provider-specific model ID for this request.
-     */
-    readonly modelId: ModelId;
-};
-
 /**
  * A normalized text generation request within a batch.
  */
@@ -1278,7 +1504,8 @@ type TextBatchV4Request<ModelId extends string = string> = BatchV4RequestBase<Mo
  * Additional modality-specific model ID types can be added to this mapping.
  */
 type BatchV4ModelIds = {
-    readonly text: string;
+    readonly text?: string;
+    readonly image?: string;
 };
 type BatchV4CallOptions = {
     readonly providerOptions?: SharedV4ProviderOptions;
@@ -1319,7 +1546,7 @@ type BatchV4Status = {
     readonly expiresAt?: string;
     readonly providerMetadata?: SharedV4ProviderMetadata;
 };
-type BatchV4Request<ModelIds extends BatchV4ModelIds = BatchV4ModelIds> = TextBatchV4Request<ModelIds['text']>;
+type BatchV4Request<ModelIds extends BatchV4ModelIds = BatchV4ModelIds> = TextBatchV4Request<ModelIds['text'] & string> | ImageBatchV4Request<ModelIds['image'] & string>;
 /**
  * Options for starting a batch of requests discriminated by modality.
  *
@@ -1393,13 +1620,19 @@ type BatchV4ItemResultBase<RESULT> = {
 type TextBatchV4ItemResult = {
     readonly type: 'text';
 } & BatchV4ItemResultBase<LanguageModelV4GenerateResult>;
+/**
+ * A complete terminal result for one request in an image batch.
+ */
+type ImageBatchV4ItemResult = {
+    readonly type: 'image';
+} & BatchV4ItemResultBase<ImageModelV4Result>;
 /**
  * A complete terminal result for one request in a batch, discriminated by
  * modality.
  *
  * Additional modality-specific item results can be added to this union.
  */
-type BatchV4ItemResult = TextBatchV4ItemResult;
+type BatchV4ItemResult = TextBatchV4ItemResult | ImageBatchV4ItemResult;
 /**
  * Specification for a batch interface that implements batch interface version 4.
  */
@@ -2294,224 +2527,6 @@ type FilesV4 = {
     deleteFile?(options: FilesV4DeleteFileCallOptions): PromiseLike<FilesV4DeleteFileResult>;
 };
 
-/**
- * An image file that can be used for image editing or variation generation.
- */
-type ImageModelV4File = {
-    type: 'file';
-    /**
-     * The IANA media type of the file, e.g. `image/png`. Any string is supported.
-     *
-     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
-     */
-    mediaType: string;
-    /**
-     * Generated file data as base64 encoded strings or binary data.
-     *
-     * The file data should be returned without any unnecessary conversion.
-     * If the API returns base64 encoded strings, the file data should be returned
-     * as base64 encoded strings. If the API returns binary data, the file data should
-     * be returned as binary data.
-     */
-    data: string | Uint8Array;
-    /**
-     * Optional provider-specific metadata for the file part.
-     */
-    providerOptions?: SharedV4ProviderMetadata;
-} | {
-    type: 'url';
-    /**
-     * The URL of the image file.
-     */
-    url: string;
-    /**
-     * Optional provider-specific metadata for the file part.
-     */
-    providerOptions?: SharedV4ProviderMetadata;
-};
-
-type ImageModelV4CallOptions = {
-    /**
-     * Prompt for the image generation. Some operations, like upscaling, may not require a prompt.
-     */
-    prompt: string | undefined;
-    /**
-     * Number of images to generate.
-     */
-    n: number;
-    /**
-     * Size of the images to generate.
-     * Must have the format `{width}x{height}`.
-     * `undefined` will use the provider's default size.
-     */
-    size: `${number}x${number}` | undefined;
-    /**
-     * Aspect ratio of the images to generate.
-     * Must have the format `{width}:{height}`.
-     * `undefined` will use the provider's default aspect ratio.
-     */
-    aspectRatio: `${number}:${number}` | undefined;
-    /**
-     * Seed for the image generation.
-     * `undefined` will use the provider's default seed.
-     */
-    seed: number | undefined;
-    /**
-     * Array of images for image editing or variation generation.
-     * The images should be provided as base64 encoded strings or binary data.
-     */
-    files: ImageModelV4File[] | undefined;
-    /**
-     * Mask image for inpainting operations.
-     * The mask should be provided as base64 encoded strings or binary data.
-     */
-    mask: ImageModelV4File | undefined;
-    /**
-     * 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": {
-     *     "style": "vivid"
-     *   }
-     * }
-     * ```
-     */
-    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>;
-};
-
-/**
- * Usage information for an image model call.
- */
-type ImageModelV4Usage = {
-    /**
-     * The number of input (prompt) tokens used.
-     */
-    inputTokens: number | undefined;
-    /**
-     * The number of output tokens used, if reported by the provider.
-     */
-    outputTokens: number | undefined;
-    /**
-     * The total number of tokens as reported by the provider.
-     */
-    totalTokens: number | undefined;
-};
-
-type ImageModelV4ProviderMetadata = Record<string, {
-    images: JSONArray;
-} & JSONValue>;
-/**
- * The result of an image model doGenerate call.
- */
-type ImageModelV4Result = {
-    /**
-     * Generated images as base64 encoded strings or binary data.
-     * The images should be returned without any unnecessary conversion.
-     * If the API returns base64 encoded strings, the images should be returned
-     * as base64 encoded strings. If the API returns binary data, the images should
-     * be returned as binary data.
-     */
-    images: Array<string> | Array<Uint8Array>;
-    /**
-     * Whether an unsuccessful result, such as an empty image result, can be
-     * retried. When omitted, the result is unclassified.
-     */
-    isRetryable?: boolean;
-    /**
-     * 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. It always includes an
-     * `images` key with image-specific metadata
-     *
-     * ```ts
-     * {
-     * "openai": {
-     * "images": ["revisedPrompt": "Revised prompt here."]
-     * }
-     * }
-     * ```
-     */
-    providerMetadata?: ImageModelV4ProviderMetadata;
-    /**
-     * 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;
-    };
-    /**
-     * Optional token usage for the image generation call (if the provider reports it).
-     */
-    usage?: ImageModelV4Usage;
-};
-
-type GetMaxImagesPerCallFunction$2 = (options: {
-    modelId: string;
-}) => PromiseLike<number | undefined> | number | undefined;
-/**
- * Image generation model specification version 4.
- */
-type ImageModelV4 = {
-    /**
-     * The image model must specify which image model interface
-     * version it implements. This will allow us to evolve the image
-     * 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 images 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.
-     */
-    readonly maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction$2;
-    /**
-     * Generates an array of images.
-     */
-    doGenerate(options: ImageModelV4CallOptions): PromiseLike<ImageModelV4Result>;
-};
-
 /**
  * Usage information for an image model call.
  */
@@ -6982,12 +6997,33 @@ type RealtimeModelV4FunctionCallOutput = {
 type RealtimeModelV4ClientEvent = {
     type: 'session-update';
     config: RealtimeModelV4SessionConfig;
+    eventId?: string;
+} | {
+    type: 'session-start';
+    config: RealtimeModelV4SessionConfig;
+    eventId?: string;
+} | {
+    type: 'session-close';
+    eventId?: string;
+} | {
+    type: 'input-audio-mute';
+    eventId?: string;
+} | {
+    type: 'input-audio-unmute';
+    eventId?: string;
+} | {
+    type: 'context-append';
+    content: string;
+    delegationId: string | null;
+    eventId?: string;
+    providerOptions?: SharedV4ProviderOptions;
 } | {
     type: 'input-audio-append';
     /**
      * Base64-encoded audio chunk to append to the input buffer.
      */
     audio: string;
+    eventId?: string;
 } | {
     type: 'input-audio-commit';
 } | {
@@ -7028,6 +7064,51 @@ type RealtimeModelV4ClientEvent = {
  * event data for debugging and provider-specific access.
  */
 type RealtimeModelV4ServerEvent = {
+    type: 'session-started';
+    sessionId: string;
+    delegationMode?: 'client' | 'provider';
+    raw: unknown;
+} | {
+    type: 'session-closed';
+    sessionId?: string;
+    usage: {
+        seconds: number;
+    };
+    reason: string;
+    raw: unknown;
+} | {
+    type: 'session-usage';
+    /** Cumulative duration snapshot, not an increment. */
+    usage: {
+        seconds: number;
+    };
+    contextWindowUsageRatio?: number;
+    raw: unknown;
+} | {
+    type: 'audio-chunk';
+    delta: string;
+    raw: unknown;
+} | {
+    type: 'transcript-fragment';
+    speaker: 'user' | 'assistant';
+    delta: string;
+    startMs: number;
+    endMs: number;
+    raw: unknown;
+} | {
+    type: 'delegation-created';
+    delegationId: string;
+    target?: 'client' | 'provider';
+    offsetMs?: number;
+    responseId?: string;
+    raw: unknown;
+} | {
+    type: 'command-acknowledged';
+    /** Provider-native command name that was acknowledged. */
+    command: string;
+    clientEventId?: string;
+    raw: unknown;
+} | {
     type: 'session-created';
     sessionId?: string;
     raw: unknown;
@@ -7158,6 +7239,7 @@ type RealtimeModelV4ServerEvent = {
     type: 'error';
     message: string;
     code?: string;
+    clientEventId?: string;
     raw: unknown;
 } | {
     type: 'custom';
@@ -7188,6 +7270,38 @@ type RealtimeModelV4 = {
      * Provider-specific model ID (e.g. 'gpt-4o-realtime', 'grok-3').
      */
     readonly modelId: string;
+    /** Conversation semantics and supported transports, when declared. */
+    readonly capabilities?: {
+        conversation: 'continuous' | 'turn-based';
+        transports: readonly ('websocket' | 'webrtc')[];
+        /** Omission preserves the legacy client-secret WebSocket connection. */
+        connections?: readonly ('client-secret-websocket' | 'server-websocket' | 'webrtc')[];
+        /** Omission preserves session-update startup. WebRTC setup may start the session. */
+        startup?: 'session-start' | 'session-update';
+        /** Omission preserves transport-close finalization. */
+        finalization?: 'session-close' | 'transport-close';
+    };
+    /** Server-only connection settings. Headers can contain long-lived credentials. */
+    getServerWebSocketConfig?(): {
+        url: string;
+        headers: Record<string, string>;
+    } | PromiseLike<{
+        url: string;
+        headers: Record<string, string>;
+    }>;
+    /** Provider-specific setup for the WebRTC event channel. */
+    getWebRTCConfig?(): {
+        dataChannelLabel: string;
+    };
+    /** Server-side SDP exchange. Return only the answer and session ID to the client. */
+    doCreateWebRTCSession?(options: {
+        sdp: string;
+        sessionConfig?: RealtimeModelV4SessionConfig;
+        abortSignal?: AbortSignal;
+    }): PromiseLike<{
+        sessionId: string;
+        sdp: string;
+    }>;
     /**
      * Server-side: Creates an ephemeral client secret for authenticating
      * browser-side WebSocket connections. The secret is short-lived and
@@ -7195,13 +7309,13 @@ type RealtimeModelV4 = {
      *
      * Naming: "do" prefix to prevent accidental direct usage by the user.
      */
-    doCreateClientSecret(options: RealtimeModelV4ClientSecretOptions): PromiseLike<RealtimeModelV4ClientSecretResult>;
+    doCreateClientSecret?(options: RealtimeModelV4ClientSecretOptions): PromiseLike<RealtimeModelV4ClientSecretResult>;
     /**
      * Browser-side: Returns the WebSocket URL and subprotocols to use
      * when connecting. Each provider has its own authentication mechanism
      * (e.g. OpenAI uses subprotocol headers, xAI may use query params).
      */
-    getWebSocketConfig(options: {
+    getWebSocketConfig?(options: {
         token: string;
         url: string;
     }): {
@@ -7218,6 +7332,8 @@ type RealtimeModelV4 = {
      * text, and turn-complete data in one message).
      */
     parseServerEvent(raw: unknown): RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
+    /** Create a raw-event parser per connection and discard it on disconnect. */
+    createServerEventParser?(): (raw: unknown) => RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
     /**
      * Browser-side: Serializes a normalized client event into the
      * provider's native JSON format for sending over the WebSocket.
@@ -8242,4 +8358,4 @@ type VideoModelV3 = {
     }>;
 };
 
-export { AISDKError, APICallError, type EmbeddingModelV2, type EmbeddingModelV2Embedding, type EmbeddingModelV3, type EmbeddingModelV3CallOptions, type EmbeddingModelV3Embedding, type EmbeddingModelV3Middleware, type EmbeddingModelV3Result, type EmbeddingModelV4, type EmbeddingModelV4CallOptions, type EmbeddingModelV4Embedding, type EmbeddingModelV4Middleware, type EmbeddingModelV4Result, EmptyResponseBodyError, type BatchV4 as Experimental_BatchV4, type BatchV4CancelResult as Experimental_BatchV4CancelResult, type BatchV4Error as Experimental_BatchV4Error, type BatchV4ItemResult as Experimental_BatchV4ItemResult, type BatchV4ListItem as Experimental_BatchV4ListItem, type BatchV4ListOptions as Experimental_BatchV4ListOptions, type BatchV4ListResult as Experimental_BatchV4ListResult, type BatchV4ModelIds as Experimental_BatchV4ModelIds, type BatchV4OperationOptions as Experimental_BatchV4OperationOptions, type BatchV4Request as Experimental_BatchV4Request, type BatchV4RequestBase as Experimental_BatchV4RequestBase, type BatchV4StartOptions as Experimental_BatchV4StartOptions, type BatchV4StartResult as Experimental_BatchV4StartResult, type BatchV4Status as Experimental_BatchV4Status, type RealtimeFactoryV4 as Experimental_RealtimeFactoryV4, type RealtimeFactoryV4GetTokenOptions as Experimental_RealtimeFactoryV4GetTokenOptions, type RealtimeFactoryV4GetTokenResult as Experimental_RealtimeFactoryV4GetTokenResult, type RealtimeModelV4 as Experimental_RealtimeModelV4, type RealtimeModelV4AudioMessage as Experimental_RealtimeModelV4AudioMessage, type RealtimeModelV4ClientEvent as Experimental_RealtimeModelV4ClientEvent, type RealtimeModelV4ClientSecretOptions as Experimental_RealtimeModelV4ClientSecretOptions, type RealtimeModelV4ClientSecretResult as Experimental_RealtimeModelV4ClientSecretResult, type RealtimeModelV4ConversationItem as Experimental_RealtimeModelV4ConversationItem, type RealtimeModelV4FunctionCallOutput as Experimental_RealtimeModelV4FunctionCallOutput, type RealtimeModelV4ServerEvent as Experimental_RealtimeModelV4ServerEvent, type RealtimeModelV4SessionConfig as Experimental_RealtimeModelV4SessionConfig, type RealtimeModelV4TextMessage as Experimental_RealtimeModelV4TextMessage, type RealtimeModelV4ToolDefinition as Experimental_RealtimeModelV4ToolDefinition, type SpeechTranslationModelV4 as Experimental_SpeechTranslationModelV4, type SpeechTranslationModelV4StreamOptions as Experimental_SpeechTranslationModelV4StreamOptions, type SpeechTranslationModelV4StreamPart as Experimental_SpeechTranslationModelV4StreamPart, type SpeechTranslationModelV4StreamResult as Experimental_SpeechTranslationModelV4StreamResult, type SpeechTranslationModelV4Usage as Experimental_SpeechTranslationModelV4Usage, type TextBatchV4ItemResult as Experimental_TextBatchV4ItemResult, type TextBatchV4Request as Experimental_TextBatchV4Request, type TranscriptionModelV4StreamOptions as Experimental_TranscriptionModelV4StreamOptions, type TranscriptionModelV4StreamPart as Experimental_TranscriptionModelV4StreamPart, type TranscriptionModelV4StreamResult as Experimental_TranscriptionModelV4StreamResult, type VideoModelV3 as Experimental_VideoModelV3, type VideoModelV3CallOptions as Experimental_VideoModelV3CallOptions, type VideoModelV3File as Experimental_VideoModelV3File, type VideoModelV3FrameImage as Experimental_VideoModelV3FrameImage, type VideoModelV3FrameType as Experimental_VideoModelV3FrameType, type VideoModelV3VideoData as Experimental_VideoModelV3VideoData, type VideoModelV4 as Experimental_VideoModelV4, type VideoModelV4CallOptions as Experimental_VideoModelV4CallOptions, type VideoModelV4File as Experimental_VideoModelV4File, type VideoModelV4FrameImage as Experimental_VideoModelV4FrameImage, type VideoModelV4FrameType as Experimental_VideoModelV4FrameType, type VideoModelV4OperationStartResult as Experimental_VideoModelV4OperationStartResult, type VideoModelV4OperationStatusResult as Experimental_VideoModelV4OperationStatusResult, type VideoModelV4OperationWebhook as Experimental_VideoModelV4OperationWebhook, type VideoModelV4Result as Experimental_VideoModelV4Result, type VideoModelV4VideoData as Experimental_VideoModelV4VideoData, type FilesV4, type FilesV4DeleteFileCallOptions, type FilesV4DeleteFileResult, type FilesV4DownloadFileCallOptions, type FilesV4DownloadFileResult, type FilesV4GetFileMetadataCallOptions, type FilesV4GetFileMetadataResult, type FilesV4UploadFileCallOptions, type FilesV4UploadFileResult, type FilesV4UploadFileStreamData, type ImageModelV2, type ImageModelV2CallOptions, type ImageModelV2CallWarning, type ImageModelV2ProviderMetadata, type ImageModelV3, type ImageModelV3CallOptions, type ImageModelV3File, type ImageModelV3Middleware, type ImageModelV3ProviderMetadata, type ImageModelV3Usage, type ImageModelV4, type ImageModelV4CallOptions, type ImageModelV4File, type ImageModelV4Middleware, type ImageModelV4ProviderMetadata, type ImageModelV4Result, type ImageModelV4Usage, InvalidArgumentError, InvalidPromptError, InvalidResponseDataError, type JSONArray, type JSONObject, JSONParseError, type JSONValue, type LanguageModelV2, type LanguageModelV2CallOptions, type LanguageModelV2CallWarning, type LanguageModelV2Content, type LanguageModelV2DataContent, type LanguageModelV2File, type LanguageModelV2FilePart, type LanguageModelV2FinishReason, type LanguageModelV2FunctionTool, type LanguageModelV2Message, type LanguageModelV2Middleware, type LanguageModelV2Prompt, type LanguageModelV2ProviderDefinedTool, type LanguageModelV2Reasoning, type LanguageModelV2ReasoningPart, type LanguageModelV2ResponseMetadata, type LanguageModelV2Source, type LanguageModelV2StreamPart, type LanguageModelV2Text, type LanguageModelV2TextPart, type LanguageModelV2ToolCall, type LanguageModelV2ToolCallPart, type LanguageModelV2ToolChoice, type LanguageModelV2ToolResultOutput, type LanguageModelV2ToolResultPart, type LanguageModelV2Usage, type LanguageModelV3, type LanguageModelV3CallOptions, type LanguageModelV3Content, type LanguageModelV3DataContent, type LanguageModelV3File, type LanguageModelV3FilePart, type LanguageModelV3FinishReason, type LanguageModelV3FunctionTool, type LanguageModelV3GenerateResult, type LanguageModelV3Message, type LanguageModelV3Middleware, type LanguageModelV3Prompt, type LanguageModelV3ProviderTool, type LanguageModelV3Reasoning, type LanguageModelV3ReasoningPart, type LanguageModelV3ResponseMetadata, type LanguageModelV3Source, type LanguageModelV3StreamPart, type LanguageModelV3StreamResult, type LanguageModelV3Text, type LanguageModelV3TextPart, type LanguageModelV3ToolApprovalRequest, type LanguageModelV3ToolApprovalResponsePart, type LanguageModelV3ToolCall, type LanguageModelV3ToolCallPart, type LanguageModelV3ToolChoice, type LanguageModelV3ToolResult, type LanguageModelV3ToolResultOutput, type LanguageModelV3ToolResultPart, type LanguageModelV3Usage, type LanguageModelV4, type LanguageModelV4CallOptions, type LanguageModelV4Content, type LanguageModelV4CustomContent, type LanguageModelV4CustomPart, type LanguageModelV4File, type LanguageModelV4FilePart, type LanguageModelV4FinishReason, type LanguageModelV4FunctionTool, type LanguageModelV4GenerateResult, type LanguageModelV4Message, type LanguageModelV4Middleware, type LanguageModelV4Prompt, type LanguageModelV4ProviderTool, type LanguageModelV4Reasoning, type LanguageModelV4ReasoningFile, type LanguageModelV4ReasoningFilePart, type LanguageModelV4ReasoningPart, type LanguageModelV4ResponseMetadata, type LanguageModelV4Source, type LanguageModelV4StreamPart, type LanguageModelV4StreamResult, type LanguageModelV4Text, type LanguageModelV4TextPart, type LanguageModelV4ToolApprovalRequest, type LanguageModelV4ToolApprovalResponsePart, type LanguageModelV4ToolCall, type LanguageModelV4ToolCallPart, type LanguageModelV4ToolChoice, type LanguageModelV4ToolResult, type LanguageModelV4ToolResultOutput, type LanguageModelV4ToolResultPart, type LanguageModelV4Usage, LoadAPIKeyError, LoadSettingError, NoContentGeneratedError, NoSuchModelError, NoSuchProviderReferenceError, type ProviderV2, type ProviderV3, type ProviderV4, type RerankingModelV3, type RerankingModelV3CallOptions, type RerankingModelV4, type RerankingModelV4CallOptions, type RerankingModelV4Result, type SharedV2Headers, type SharedV2ProviderMetadata, type SharedV2ProviderOptions, type SharedV3Headers, type SharedV3ProviderMetadata, type SharedV3ProviderOptions, type SharedV3Warning, type SharedV4AudioFormat, type SharedV4FileData, type SharedV4FileDataData, type SharedV4FileDataReference, type SharedV4FileDataText, type SharedV4FileDataUrl, type SharedV4Headers, type SharedV4ProviderMetadata, type SharedV4ProviderOptions, type SharedV4ProviderReference, type SharedV4Warning, type SkillsV4, type SkillsV4File, type SkillsV4UploadSkillCallOptions, type SkillsV4UploadSkillResult, type SpeechModelV2, type SpeechModelV2CallOptions, type SpeechModelV2CallWarning, type SpeechModelV3, type SpeechModelV3CallOptions, type SpeechModelV4, type SpeechModelV4CallOptions, type SpeechModelV4Result, TooManyEmbeddingValuesForCallError, type TranscriptionModelV2, type TranscriptionModelV2CallOptions, type TranscriptionModelV2CallWarning, type TranscriptionModelV3, type TranscriptionModelV3CallOptions, type TranscriptionModelV4, type TranscriptionModelV4CallOptions, type TranscriptionModelV4Result, type TypeValidationContext, TypeValidationError, UnsupportedFunctionalityError, getErrorMessage, isJSONArray, isJSONObject, isJSONValue };
+export { AISDKError, APICallError, type EmbeddingModelV2, type EmbeddingModelV2Embedding, type EmbeddingModelV3, type EmbeddingModelV3CallOptions, type EmbeddingModelV3Embedding, type EmbeddingModelV3Middleware, type EmbeddingModelV3Result, type EmbeddingModelV4, type EmbeddingModelV4CallOptions, type EmbeddingModelV4Embedding, type EmbeddingModelV4Middleware, type EmbeddingModelV4Result, EmptyResponseBodyError, type BatchV4 as Experimental_BatchV4, type BatchV4CancelResult as Experimental_BatchV4CancelResult, type BatchV4Error as Experimental_BatchV4Error, type BatchV4ItemResult as Experimental_BatchV4ItemResult, type BatchV4ListItem as Experimental_BatchV4ListItem, type BatchV4ListOptions as Experimental_BatchV4ListOptions, type BatchV4ListResult as Experimental_BatchV4ListResult, type BatchV4ModelIds as Experimental_BatchV4ModelIds, type BatchV4OperationOptions as Experimental_BatchV4OperationOptions, type BatchV4Request as Experimental_BatchV4Request, type BatchV4RequestBase as Experimental_BatchV4RequestBase, type BatchV4StartOptions as Experimental_BatchV4StartOptions, type BatchV4StartResult as Experimental_BatchV4StartResult, type BatchV4Status as Experimental_BatchV4Status, type ImageBatchV4ItemResult as Experimental_ImageBatchV4ItemResult, type ImageBatchV4Request as Experimental_ImageBatchV4Request, type RealtimeFactoryV4 as Experimental_RealtimeFactoryV4, type RealtimeFactoryV4GetTokenOptions as Experimental_RealtimeFactoryV4GetTokenOptions, type RealtimeFactoryV4GetTokenResult as Experimental_RealtimeFactoryV4GetTokenResult, type RealtimeModelV4 as Experimental_RealtimeModelV4, type RealtimeModelV4AudioMessage as Experimental_RealtimeModelV4AudioMessage, type RealtimeModelV4ClientEvent as Experimental_RealtimeModelV4ClientEvent, type RealtimeModelV4ClientSecretOptions as Experimental_RealtimeModelV4ClientSecretOptions, type RealtimeModelV4ClientSecretResult as Experimental_RealtimeModelV4ClientSecretResult, type RealtimeModelV4ConversationItem as Experimental_RealtimeModelV4ConversationItem, type RealtimeModelV4FunctionCallOutput as Experimental_RealtimeModelV4FunctionCallOutput, type RealtimeModelV4ServerEvent as Experimental_RealtimeModelV4ServerEvent, type RealtimeModelV4SessionConfig as Experimental_RealtimeModelV4SessionConfig, type RealtimeModelV4TextMessage as Experimental_RealtimeModelV4TextMessage, type RealtimeModelV4ToolDefinition as Experimental_RealtimeModelV4ToolDefinition, type SpeechTranslationModelV4 as Experimental_SpeechTranslationModelV4, type SpeechTranslationModelV4StreamOptions as Experimental_SpeechTranslationModelV4StreamOptions, type SpeechTranslationModelV4StreamPart as Experimental_SpeechTranslationModelV4StreamPart, type SpeechTranslationModelV4StreamResult as Experimental_SpeechTranslationModelV4StreamResult, type SpeechTranslationModelV4Usage as Experimental_SpeechTranslationModelV4Usage, type TextBatchV4ItemResult as Experimental_TextBatchV4ItemResult, type TextBatchV4Request as Experimental_TextBatchV4Request, type TranscriptionModelV4StreamOptions as Experimental_TranscriptionModelV4StreamOptions, type TranscriptionModelV4StreamPart as Experimental_TranscriptionModelV4StreamPart, type TranscriptionModelV4StreamResult as Experimental_TranscriptionModelV4StreamResult, type VideoModelV3 as Experimental_VideoModelV3, type VideoModelV3CallOptions as Experimental_VideoModelV3CallOptions, type VideoModelV3File as Experimental_VideoModelV3File, type VideoModelV3FrameImage as Experimental_VideoModelV3FrameImage, type VideoModelV3FrameType as Experimental_VideoModelV3FrameType, type VideoModelV3VideoData as Experimental_VideoModelV3VideoData, type VideoModelV4 as Experimental_VideoModelV4, type VideoModelV4CallOptions as Experimental_VideoModelV4CallOptions, type VideoModelV4File as Experimental_VideoModelV4File, type VideoModelV4FrameImage as Experimental_VideoModelV4FrameImage, type VideoModelV4FrameType as Experimental_VideoModelV4FrameType, type VideoModelV4OperationStartResult as Experimental_VideoModelV4OperationStartResult, type VideoModelV4OperationStatusResult as Experimental_VideoModelV4OperationStatusResult, type VideoModelV4OperationWebhook as Experimental_VideoModelV4OperationWebhook, type VideoModelV4Result as Experimental_VideoModelV4Result, type VideoModelV4VideoData as Experimental_VideoModelV4VideoData, type FilesV4, type FilesV4DeleteFileCallOptions, type FilesV4DeleteFileResult, type FilesV4DownloadFileCallOptions, type FilesV4DownloadFileResult, type FilesV4GetFileMetadataCallOptions, type FilesV4GetFileMetadataResult, type FilesV4UploadFileCallOptions, type FilesV4UploadFileResult, type FilesV4UploadFileStreamData, type ImageModelV2, type ImageModelV2CallOptions, type ImageModelV2CallWarning, type ImageModelV2ProviderMetadata, type ImageModelV3, type ImageModelV3CallOptions, type ImageModelV3File, type ImageModelV3Middleware, type ImageModelV3ProviderMetadata, type ImageModelV3Usage, type ImageModelV4, type ImageModelV4CallOptions, type ImageModelV4File, type ImageModelV4Middleware, type ImageModelV4ProviderMetadata, type ImageModelV4Result, type ImageModelV4Usage, InvalidArgumentError, InvalidPromptError, InvalidResponseDataError, type JSONArray, type JSONObject, JSONParseError, type JSONValue, type LanguageModelV2, type LanguageModelV2CallOptions, type LanguageModelV2CallWarning, type LanguageModelV2Content, type LanguageModelV2DataContent, type LanguageModelV2File, type LanguageModelV2FilePart, type LanguageModelV2FinishReason, type LanguageModelV2FunctionTool, type LanguageModelV2Message, type LanguageModelV2Middleware, type LanguageModelV2Prompt, type LanguageModelV2ProviderDefinedTool, type LanguageModelV2Reasoning, type LanguageModelV2ReasoningPart, type LanguageModelV2ResponseMetadata, type LanguageModelV2Source, type LanguageModelV2StreamPart, type LanguageModelV2Text, type LanguageModelV2TextPart, type LanguageModelV2ToolCall, type LanguageModelV2ToolCallPart, type LanguageModelV2ToolChoice, type LanguageModelV2ToolResultOutput, type LanguageModelV2ToolResultPart, type LanguageModelV2Usage, type LanguageModelV3, type LanguageModelV3CallOptions, type LanguageModelV3Content, type LanguageModelV3DataContent, type LanguageModelV3File, type LanguageModelV3FilePart, type LanguageModelV3FinishReason, type LanguageModelV3FunctionTool, type LanguageModelV3GenerateResult, type LanguageModelV3Message, type LanguageModelV3Middleware, type LanguageModelV3Prompt, type LanguageModelV3ProviderTool, type LanguageModelV3Reasoning, type LanguageModelV3ReasoningPart, type LanguageModelV3ResponseMetadata, type LanguageModelV3Source, type LanguageModelV3StreamPart, type LanguageModelV3StreamResult, type LanguageModelV3Text, type LanguageModelV3TextPart, type LanguageModelV3ToolApprovalRequest, type LanguageModelV3ToolApprovalResponsePart, type LanguageModelV3ToolCall, type LanguageModelV3ToolCallPart, type LanguageModelV3ToolChoice, type LanguageModelV3ToolResult, type LanguageModelV3ToolResultOutput, type LanguageModelV3ToolResultPart, type LanguageModelV3Usage, type LanguageModelV4, type LanguageModelV4CallOptions, type LanguageModelV4Content, type LanguageModelV4CustomContent, type LanguageModelV4CustomPart, type LanguageModelV4File, type LanguageModelV4FilePart, type LanguageModelV4FinishReason, type LanguageModelV4FunctionTool, type LanguageModelV4GenerateResult, type LanguageModelV4Message, type LanguageModelV4Middleware, type LanguageModelV4Prompt, type LanguageModelV4ProviderTool, type LanguageModelV4Reasoning, type LanguageModelV4ReasoningFile, type LanguageModelV4ReasoningFilePart, type LanguageModelV4ReasoningPart, type LanguageModelV4ResponseMetadata, type LanguageModelV4Source, type LanguageModelV4StreamPart, type LanguageModelV4StreamResult, type LanguageModelV4Text, type LanguageModelV4TextPart, type LanguageModelV4ToolApprovalRequest, type LanguageModelV4ToolApprovalResponsePart, type LanguageModelV4ToolCall, type LanguageModelV4ToolCallPart, type LanguageModelV4ToolChoice, type LanguageModelV4ToolResult, type LanguageModelV4ToolResultOutput, type LanguageModelV4ToolResultPart, type LanguageModelV4Usage, LoadAPIKeyError, LoadSettingError, NoContentGeneratedError, NoSuchModelError, NoSuchProviderReferenceError, type ProviderV2, type ProviderV3, type ProviderV4, type RerankingModelV3, type RerankingModelV3CallOptions, type RerankingModelV4, type RerankingModelV4CallOptions, type RerankingModelV4Result, type SharedV2Headers, type SharedV2ProviderMetadata, type SharedV2ProviderOptions, type SharedV3Headers, type SharedV3ProviderMetadata, type SharedV3ProviderOptions, type SharedV3Warning, type SharedV4AudioFormat, type SharedV4FileData, type SharedV4FileDataData, type SharedV4FileDataReference, type SharedV4FileDataText, type SharedV4FileDataUrl, type SharedV4Headers, type SharedV4ProviderMetadata, type SharedV4ProviderOptions, type SharedV4ProviderReference, type SharedV4Warning, type SkillsV4, type SkillsV4File, type SkillsV4UploadSkillCallOptions, type SkillsV4UploadSkillResult, type SpeechModelV2, type SpeechModelV2CallOptions, type SpeechModelV2CallWarning, type SpeechModelV3, type SpeechModelV3CallOptions, type SpeechModelV4, type SpeechModelV4CallOptions, type SpeechModelV4Result, TooManyEmbeddingValuesForCallError, type TranscriptionModelV2, type TranscriptionModelV2CallOptions, type TranscriptionModelV2CallWarning, type TranscriptionModelV3, type TranscriptionModelV3CallOptions, type TranscriptionModelV4, type TranscriptionModelV4CallOptions, type TranscriptionModelV4Result, type TypeValidationContext, TypeValidationError, UnsupportedFunctionalityError, getErrorMessage, isJSONArray, isJSONObject, isJSONValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider",
-  "version": "4.0.13",
+  "version": "4.0.15",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/batch/v4/batch-v4.ts

@@ -4,6 +4,8 @@ import type {
   SharedV4Warning,
 } from '../../shared';
 import type { LanguageModelV4GenerateResult } from '../../language-model/v4/language-model-v4-generate-result';
+import type { ImageModelV4Result } from '../../image-model/v4';
+import type { ImageBatchV4Request } from './image-batch-v4-request';
 import type { TextBatchV4Request } from './text-batch-v4-request';
 
 /**
@@ -12,7 +14,8 @@ import type { TextBatchV4Request } from './text-batch-v4-request';
  * Additional modality-specific model ID types can be added to this mapping.
  */
 export type BatchV4ModelIds = {
-  readonly text: string;
+  readonly text?: string;
+  readonly image?: string;
 };
 
 type BatchV4CallOptions = {
@@ -59,7 +62,8 @@ export type BatchV4Status = {
 };
 
 export type BatchV4Request<ModelIds extends BatchV4ModelIds = BatchV4ModelIds> =
-  TextBatchV4Request<ModelIds['text']>;
+  | TextBatchV4Request<ModelIds['text'] & string>
+  | ImageBatchV4Request<ModelIds['image'] & string>;
 
 /**
  * Options for starting a batch of requests discriminated by modality.
@@ -148,13 +152,20 @@ export type TextBatchV4ItemResult = {
   readonly type: 'text';
 } & BatchV4ItemResultBase<LanguageModelV4GenerateResult>;
 
+/**
+ * A complete terminal result for one request in an image batch.
+ */
+export type ImageBatchV4ItemResult = {
+  readonly type: 'image';
+} & BatchV4ItemResultBase<ImageModelV4Result>;
+
 /**
  * A complete terminal result for one request in a batch, discriminated by
  * modality.
  *
  * Additional modality-specific item results can be added to this union.
  */
-export type BatchV4ItemResult = TextBatchV4ItemResult;
+export type BatchV4ItemResult = TextBatchV4ItemResult | ImageBatchV4ItemResult;
 
 /**
  * Specification for a batch interface that implements batch interface version 4.

package/src/batch/v4/image-batch-v4-request.ts

@@ -0,0 +1,21 @@
+import type { ImageModelV4CallOptions } from '../../image-model/v4';
+import type { BatchV4RequestBase } from './batch-v4-request';
+
+/**
+ * One image generation request in a batch.
+ */
+export type ImageBatchV4Request<ModelId extends string = string> =
+  BatchV4RequestBase<ModelId> & {
+    readonly type: 'image';
+    readonly options: Pick<
+      ImageModelV4CallOptions,
+      | 'prompt'
+      | 'n'
+      | 'size'
+      | 'aspectRatio'
+      | 'seed'
+      | 'files'
+      | 'mask'
+      | 'providerOptions'
+    >;
+  };

package/src/batch/v4/index.ts

@@ -12,7 +12,9 @@ export type {
   BatchV4StartOptions as Experimental_BatchV4StartOptions,
   BatchV4StartResult as Experimental_BatchV4StartResult,
   BatchV4Status as Experimental_BatchV4Status,
+  ImageBatchV4ItemResult as Experimental_ImageBatchV4ItemResult,
   TextBatchV4ItemResult as Experimental_TextBatchV4ItemResult,
 } from './batch-v4';
 export type { BatchV4RequestBase as Experimental_BatchV4RequestBase } from './batch-v4-request';
 export type { TextBatchV4Request as Experimental_TextBatchV4Request } from './text-batch-v4-request';
+export type { ImageBatchV4Request as Experimental_ImageBatchV4Request } from './image-batch-v4-request';

package/src/realtime-model/v4/realtime-model-v4-client-event.ts

@@ -1,3 +1,4 @@
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
 import type { RealtimeModelV4ConversationItem } from './realtime-model-v4-conversation-item';
 import type { RealtimeModelV4SessionConfig } from './realtime-model-v4-session-config';
 
@@ -12,6 +13,31 @@ export type RealtimeModelV4ClientEvent =
   | {
       type: 'session-update';
       config: RealtimeModelV4SessionConfig;
+      eventId?: string;
+    }
+  | {
+      type: 'session-start';
+      config: RealtimeModelV4SessionConfig;
+      eventId?: string;
+    }
+  | {
+      type: 'session-close';
+      eventId?: string;
+    }
+  | {
+      type: 'input-audio-mute';
+      eventId?: string;
+    }
+  | {
+      type: 'input-audio-unmute';
+      eventId?: string;
+    }
+  | {
+      type: 'context-append';
+      content: string;
+      delegationId: string | null;
+      eventId?: string;
+      providerOptions?: SharedV4ProviderOptions;
     }
 
   // ── Input audio buffer ─────────────────────────────────────────────
@@ -22,6 +48,7 @@ export type RealtimeModelV4ClientEvent =
        * Base64-encoded audio chunk to append to the input buffer.
        */
       audio: string;
+      eventId?: string;
     }
   | {
       type: 'input-audio-commit';

package/src/realtime-model/v4/realtime-model-v4-server-event.ts

@@ -6,8 +6,55 @@
  * event data for debugging and provider-specific access.
  */
 export type RealtimeModelV4ServerEvent =
+  | {
+      type: 'session-started';
+      sessionId: string;
+      delegationMode?: 'client' | 'provider';
+      raw: unknown;
+    }
+  | {
+      type: 'session-closed';
+      sessionId?: string;
+      usage: { seconds: number };
+      reason: string;
+      raw: unknown;
+    }
+  | {
+      type: 'session-usage';
+      /** Cumulative duration snapshot, not an increment. */
+      usage: { seconds: number };
+      contextWindowUsageRatio?: number;
+      raw: unknown;
+    }
+  | {
+      type: 'audio-chunk';
+      delta: string;
+      raw: unknown;
+    }
+  | {
+      type: 'transcript-fragment';
+      speaker: 'user' | 'assistant';
+      delta: string;
+      startMs: number;
+      endMs: number;
+      raw: unknown;
+    }
+  | {
+      type: 'delegation-created';
+      delegationId: string;
+      target?: 'client' | 'provider';
+      offsetMs?: number;
+      responseId?: string;
+      raw: unknown;
+    }
+  | {
+      type: 'command-acknowledged';
+      /** Provider-native command name that was acknowledged. */
+      command: string;
+      clientEventId?: string;
+      raw: unknown;
+    }
   // ── Session lifecycle ──────────────────────────────────────────────
-
   | {
       type: 'session-created';
       sessionId?: string;
@@ -184,6 +231,7 @@ export type RealtimeModelV4ServerEvent =
       type: 'error';
       message: string;
       code?: string;
+      clientEventId?: string;
       raw: unknown;
     }
 

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

@@ -29,6 +29,37 @@ export type RealtimeModelV4 = {
    */
   readonly modelId: string;
 
+  /** Conversation semantics and supported transports, when declared. */
+  readonly capabilities?: {
+    conversation: 'continuous' | 'turn-based';
+    transports: readonly ('websocket' | 'webrtc')[];
+    /** Omission preserves the legacy client-secret WebSocket connection. */
+    connections?: readonly (
+      | 'client-secret-websocket'
+      | 'server-websocket'
+      | 'webrtc'
+    )[];
+    /** Omission preserves session-update startup. WebRTC setup may start the session. */
+    startup?: 'session-start' | 'session-update';
+    /** Omission preserves transport-close finalization. */
+    finalization?: 'session-close' | 'transport-close';
+  };
+
+  /** Server-only connection settings. Headers can contain long-lived credentials. */
+  getServerWebSocketConfig?():
+    | { url: string; headers: Record<string, string> }
+    | PromiseLike<{ url: string; headers: Record<string, string> }>;
+
+  /** Provider-specific setup for the WebRTC event channel. */
+  getWebRTCConfig?(): { dataChannelLabel: string };
+
+  /** Server-side SDP exchange. Return only the answer and session ID to the client. */
+  doCreateWebRTCSession?(options: {
+    sdp: string;
+    sessionConfig?: RealtimeModelV4SessionConfig;
+    abortSignal?: AbortSignal;
+  }): PromiseLike<{ sessionId: string; sdp: string }>;
+
   /**
    * Server-side: Creates an ephemeral client secret for authenticating
    * browser-side WebSocket connections. The secret is short-lived and
@@ -36,7 +67,7 @@ export type RealtimeModelV4 = {
    *
    * Naming: "do" prefix to prevent accidental direct usage by the user.
    */
-  doCreateClientSecret(
+  doCreateClientSecret?(
     options: RealtimeModelV4ClientSecretOptions,
   ): PromiseLike<RealtimeModelV4ClientSecretResult>;
 
@@ -45,7 +76,7 @@ export type RealtimeModelV4 = {
    * when connecting. Each provider has its own authentication mechanism
    * (e.g. OpenAI uses subprotocol headers, xAI may use query params).
    */
-  getWebSocketConfig(options: { token: string; url: string }): {
+  getWebSocketConfig?(options: { token: string; url: string }): {
     url: string;
     protocols?: string[];
   };
@@ -63,6 +94,11 @@ export type RealtimeModelV4 = {
     raw: unknown,
   ): RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
 
+  /** Create a raw-event parser per connection and discard it on disconnect. */
+  createServerEventParser?(): (
+    raw: unknown,
+  ) => RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
+
   /**
    * Browser-side: Serializes a normalized client event into the
    * provider's native JSON format for sending over the WebSocket.