@ai-sdk/openai 4.0.65 → 4.0.67

package/src/live/openai-realtime-model-live-options.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod/v4';
+
+export type OpenAIRealtimeModelLiveId = 'gpt-live-1' | (string & {});
+
+const serverEventSelectorSchema = z
+  .strictObject({
+    type: z.string(),
+    responseEvent: z.string().optional(),
+  })
+  .refine(
+    selector =>
+      (selector.type === 'response.event') ===
+      (selector.responseEvent !== undefined),
+    'responseEvent is required for response.event and forbidden for other event types.',
+  );
+
+export const openaiRealtimeModelLiveOptionsSchema = z.strictObject({
+  client: z
+    .strictObject({
+      dataChannel: z.strictObject({
+        allowedClientEvents: z
+          .union([z.literal('all'), z.array(z.string())])
+          .optional(),
+        allowedServerEvents: z
+          .union([z.literal('all'), z.array(serverEventSelectorSchema)])
+          .optional(),
+      }),
+    })
+    .optional(),
+  delegation: z
+    .strictObject({ type: z.literal('client') })
+    .nullable()
+    .optional(),
+  input: z
+    .array(
+      z.discriminatedUnion('role', [
+        z.strictObject({
+          type: z.literal('message'),
+          role: z.enum(['developer', 'user']),
+          content: z.tuple([
+            z.strictObject({ type: z.literal('input_text'), text: z.string() }),
+          ]),
+        }),
+        z.strictObject({
+          type: z.literal('message'),
+          role: z.literal('assistant'),
+          content: z.tuple([
+            z.strictObject({
+              type: z.enum(['text', 'output_text']),
+              text: z.string(),
+            }),
+          ]),
+        }),
+      ]),
+    )
+    .max(128)
+    .optional(),
+  store: z.boolean().optional(),
+  voice: z.strictObject({ id: z.string().min(1) }).optional(),
+});
+
+/** Experimental Live options under sessionConfig.providerOptions.openai. */
+export type OpenAIRealtimeModelLiveOptions = z.infer<
+  typeof openaiRealtimeModelLiveOptionsSchema
+>;

package/src/live/openai-realtime-model-live.ts

@@ -0,0 +1,107 @@
+import {
+  type Experimental_RealtimeModelV4 as RealtimeModelV4,
+  type Experimental_RealtimeModelV4ClientEvent as RealtimeModelV4ClientEvent,
+  type Experimental_RealtimeModelV4SessionConfig as RealtimeModelV4SessionConfig,
+} from '@ai-sdk/provider';
+import {
+  createJsonResponseHandler,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { openaiFailedResponseHandler } from '../openai-error';
+import {
+  createOpenAILiveServerEventParser,
+  parseOpenAILiveServerEvent,
+  serializeOpenAILiveClientEvent,
+} from './openai-live-event-mapper';
+import type { OpenAIRealtimeModelLiveId } from './openai-realtime-model-live-options';
+import { buildOpenAILiveSessionConfig } from './openai-live-session-config';
+import type { OpenAIRealtimeModelConfig } from '../realtime/openai-realtime-model';
+
+export type OpenAIRealtimeModelLiveConfig = OpenAIRealtimeModelConfig;
+
+const webRTCSessionSchema = z.object({
+  session: z.object({ id: z.string().min(1) }),
+  transport: z.object({ type: z.literal('webrtc'), sdp: z.string().min(1) }),
+});
+
+export class OpenAIRealtimeModelLive implements RealtimeModelV4 {
+  readonly specificationVersion = 'v4' as const;
+  readonly capabilities = {
+    conversation: 'continuous',
+    transports: ['websocket', 'webrtc'],
+    connections: ['server-websocket', 'webrtc'],
+    startup: 'session-start',
+    finalization: 'session-close',
+  } as const;
+
+  constructor(
+    readonly modelId: OpenAIRealtimeModelLiveId,
+    private readonly config: OpenAIRealtimeModelLiveConfig,
+  ) {}
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  getWebRTCConfig(): { dataChannelLabel: string } {
+    return { dataChannelLabel: 'oai-events' };
+  }
+
+  getServerWebSocketConfig(): { url: string; headers: Record<string, string> } {
+    const url = new URL(`${this.config.baseURL}/live/sessions`);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(this.config.headers())) {
+      if (value !== undefined) headers[key] = value;
+    }
+    return { url: url.toString(), headers };
+  }
+
+  async doCreateWebRTCSession({
+    sdp,
+    sessionConfig = {},
+    abortSignal,
+  }: {
+    sdp: string;
+    sessionConfig?: RealtimeModelV4SessionConfig;
+    abortSignal?: AbortSignal;
+  }): Promise<{ sessionId: string; sdp: string }> {
+    const session = buildOpenAILiveSessionConfig(
+      sessionConfig,
+      this.modelId,
+      'webrtc',
+    );
+    const { value } = await postJsonToApi({
+      url: `${this.config.baseURL}/live/sessions`,
+      headers: this.config.headers(),
+      body: {
+        session,
+        transport: { type: 'webrtc', sdp: z.string().min(1).parse(sdp) },
+      },
+      failedResponseHandler: openaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(webRTCSessionSchema),
+      abortSignal,
+      fetch: this.config.fetch,
+    });
+    return { sessionId: value.session.id, sdp: value.transport.sdp };
+  }
+
+  parseServerEvent(raw: unknown) {
+    return parseOpenAILiveServerEvent(raw);
+  }
+
+  createServerEventParser() {
+    return createOpenAILiveServerEventParser();
+  }
+
+  serializeClientEvent(event: RealtimeModelV4ClientEvent): unknown {
+    return serializeOpenAILiveClientEvent(event, this.modelId);
+  }
+
+  buildSessionConfig(
+    config: RealtimeModelV4SessionConfig,
+  ): Record<string, unknown> {
+    return buildOpenAILiveSessionConfig(config, this.modelId);
+  }
+}

package/src/normalize-openai-json-schema.ts

@@ -0,0 +1,161 @@
+import {
+  UnsupportedFunctionalityError,
+  type JSONSchema7,
+  type JSONSchema7Definition,
+  type SharedV4Warning,
+} from '@ai-sdk/provider';
+
+/**
+ * Normalizes JSON Schema for OpenAI structured outputs.
+ *
+ * OpenAI does not support the JSON Schema `propertyNames` keyword. Property
+ * names in JSON objects are always strings, so string-based constraints can be
+ * left to client-side validation after removing the keyword. This
+ * compatibility layer does not rewrite non-string property name schemas.
+ */
+export function normalizeOpenAIJsonSchema(schema: JSONSchema7): {
+  schema: JSONSchema7;
+  warnings: SharedV4Warning[];
+} {
+  let removedPropertyNames = false;
+
+  const normalizedSchema = normalizeSchema(schema);
+
+  return {
+    schema: normalizedSchema,
+    warnings: removedPropertyNames
+      ? [
+          {
+            type: 'compatibility',
+            feature: 'JSON Schema propertyNames',
+            details:
+              'OpenAI does not support JSON Schema propertyNames. It was removed before sending the schema, so OpenAI will not enforce property-name constraints.',
+          },
+        ]
+      : [],
+  };
+
+  function normalizeSchema(schema: JSONSchema7): JSONSchema7 {
+    const propertyNames = schema.propertyNames;
+
+    if (propertyNames != null) {
+      if (
+        typeof propertyNames === 'boolean' ||
+        propertyNames.type !== 'string'
+      ) {
+        throw new UnsupportedFunctionalityError({
+          functionality:
+            'JSON Schema propertyNames that does not use a string schema',
+        });
+      }
+
+      removedPropertyNames = true;
+    }
+
+    const normalizedSchema = { ...schema };
+    delete normalizedSchema.propertyNames;
+
+    if (normalizedSchema.properties != null) {
+      normalizedSchema.properties = normalizeSchemaRecord(
+        normalizedSchema.properties,
+      );
+    }
+
+    if (normalizedSchema.patternProperties != null) {
+      normalizedSchema.patternProperties = normalizeSchemaRecord(
+        normalizedSchema.patternProperties,
+      );
+    }
+
+    if (normalizedSchema.additionalProperties != null) {
+      normalizedSchema.additionalProperties = normalizeDefinition(
+        normalizedSchema.additionalProperties,
+      );
+    }
+
+    if (normalizedSchema.additionalItems != null) {
+      normalizedSchema.additionalItems = normalizeDefinition(
+        normalizedSchema.additionalItems,
+      );
+    }
+
+    if (normalizedSchema.items != null) {
+      normalizedSchema.items = Array.isArray(normalizedSchema.items)
+        ? normalizedSchema.items.map(normalizeDefinition)
+        : normalizeDefinition(normalizedSchema.items);
+    }
+
+    if (normalizedSchema.contains != null) {
+      normalizedSchema.contains = normalizeDefinition(
+        normalizedSchema.contains,
+      );
+    }
+
+    if (normalizedSchema.not != null) {
+      normalizedSchema.not = normalizeDefinition(normalizedSchema.not);
+    }
+
+    if (normalizedSchema.allOf != null) {
+      normalizedSchema.allOf = normalizedSchema.allOf.map(normalizeDefinition);
+    }
+
+    if (normalizedSchema.anyOf != null) {
+      normalizedSchema.anyOf = normalizedSchema.anyOf.map(normalizeDefinition);
+    }
+
+    if (normalizedSchema.oneOf != null) {
+      normalizedSchema.oneOf = normalizedSchema.oneOf.map(normalizeDefinition);
+    }
+
+    if (normalizedSchema.definitions != null) {
+      normalizedSchema.definitions = normalizeSchemaRecord(
+        normalizedSchema.definitions,
+      );
+    }
+
+    if (normalizedSchema.$defs != null) {
+      normalizedSchema.$defs = normalizeSchemaRecord(normalizedSchema.$defs);
+    }
+
+    if (normalizedSchema.dependencies != null) {
+      normalizedSchema.dependencies = Object.fromEntries(
+        Object.entries(normalizedSchema.dependencies).map(
+          ([key, dependency]) => [
+            key,
+            Array.isArray(dependency)
+              ? dependency
+              : normalizeDefinition(dependency),
+          ],
+        ),
+      );
+    }
+
+    for (const keyword of ['if', 'then', 'else'] as const) {
+      const conditionalSchema = normalizedSchema[keyword];
+      if (conditionalSchema != null) {
+        normalizedSchema[keyword] = normalizeDefinition(conditionalSchema);
+      }
+    }
+
+    return normalizedSchema;
+  }
+
+  function normalizeSchemaRecord(
+    schemas: Record<string, JSONSchema7Definition>,
+  ): Record<string, JSONSchema7Definition> {
+    return Object.fromEntries(
+      Object.entries(schemas).map(([key, schema]) => [
+        key,
+        normalizeDefinition(schema),
+      ]),
+    );
+  }
+
+  function normalizeDefinition(
+    definition: JSONSchema7Definition,
+  ): JSONSchema7Definition {
+    return typeof definition === 'boolean'
+      ? definition
+      : normalizeSchema(definition);
+  }
+}

package/src/openai-batch.ts

@@ -1,6 +1,7 @@
 import {
   InvalidArgumentError,
   InvalidResponseDataError,
+  UnsupportedFunctionalityError,
   type Experimental_BatchV4 as BatchV4,
   type Experimental_BatchV4CancelResult as BatchV4CancelResult,
   type Experimental_BatchV4StartResult as BatchV4StartResult,
@@ -89,6 +90,20 @@ type OpenAIBatchResultConversion =
   | { success: true; result: LanguageModelV4GenerateResult }
   | { success: false; error: BatchV4Error };
 
+function assertTextBatchRequests(
+  requests: BatchV4StartOptions['requests'],
+): asserts requests is ReadonlyArray<OpenAIBatchRequest> {
+  for (const request of requests) {
+    const requestType = request.type;
+    if (requestType !== 'text') {
+      throw new UnsupportedFunctionalityError({
+        functionality: `batch request type: ${requestType}`,
+        message: `The OpenAI Batch API does not support batch requests with type "${requestType}".`,
+      });
+    }
+  }
+}
+
 const openaiBatchResponseZodSchema = () =>
   z.object({
     id: z.string(),
@@ -174,6 +189,7 @@ export class OpenAIBatch implements BatchV4<OpenAIBatchModelIds> {
   async doStartBatch(
     options: BatchV4StartOptions<OpenAIBatchModelIds>,
   ): Promise<BatchV4StartResult> {
+    assertTextBatchRequests(options.requests);
     validateSingleModel(options.requests);
 
     const fileParts: string[] = [];

package/src/openai-config.ts

@@ -24,6 +24,13 @@ export type OpenAIConfig = {
    * @see https://github.com/vercel/ai/issues/20180
    */
   explicitMessageItemType?: boolean;
+  /**
+   * Whether the provider supports the
+   * `web_search_call.action.sources` Responses API include value.
+   *
+   * Defaults to `true`.
+   */
+  supportsWebSearchSourcesInclude?: boolean;
   /**
    * This is soft-deprecated. Use provider references (e.g. `{ openai: 'file-abc123' }`)
    * in file part data instead. File ID prefixes used to identify file IDs

package/src/openai-provider.ts

@@ -5,8 +5,6 @@ import type {
   ImageModelV4,
   LanguageModelV4,
   ProviderV4,
-  Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
-  Experimental_RealtimeFactoryV4GetTokenOptions as RealtimeFactoryV4GetTokenOptions,
   SpeechModelV4,
   SkillsV4,
   TranscriptionModelV4,
@@ -33,7 +31,10 @@ import type { OpenAIImageModelId } from './image/openai-image-model-options';
 import { openaiTools } from './openai-tools';
 import { OpenAIBatch } from './openai-batch';
 import { OpenAIResponsesLanguageModel } from './responses/openai-responses-language-model';
-import { OpenAIRealtimeModel } from './realtime/openai-realtime-model';
+import {
+  createOpenAIRealtimeFactory,
+  type OpenAIRealtimeFactory,
+} from './realtime/openai-realtime-factory';
 import type { OpenAIResponsesModelId } from './responses/openai-responses-language-model-options';
 import { OpenAISpeechModel } from './speech/openai-speech-model';
 import type { OpenAISpeechModelId } from './speech/openai-speech-model-options';
@@ -125,7 +126,7 @@ export interface OpenAIProvider extends ProviderV4 {
    * Creates an experimental realtime model for bidirectional audio/text
    * communication over WebSocket.
    */
-  experimental_realtime: RealtimeFactoryV4;
+  experimental_realtime: OpenAIRealtimeFactory;
 
   /**
    * Returns a FilesV4 interface for uploading files to OpenAI.
@@ -337,33 +338,6 @@ export function createOpenAI(
       },
     });
 
-  const createRealtimeModel = (modelId: string) =>
-    new OpenAIRealtimeModel(modelId, {
-      provider: `${providerName}.realtime`,
-      baseURL,
-      headers: getHeaders,
-      fetch: options.fetch,
-    });
-
-  const experimentalRealtimeFactory = Object.assign(
-    (modelId: string) => createRealtimeModel(modelId),
-    {
-      getToken: async (tokenOptions: RealtimeFactoryV4GetTokenOptions) => {
-        const model = createRealtimeModel(tokenOptions.model);
-        const secret = await model.doCreateClientSecret({
-          sessionConfig: tokenOptions.sessionConfig,
-          expiresAfterSeconds: tokenOptions.expiresAfterSeconds,
-        });
-
-        return {
-          token: secret.token,
-          url: secret.url,
-          expiresAt: secret.expiresAt,
-        };
-      },
-    },
-  ) as RealtimeFactoryV4;
-
   const provider = function (modelId: OpenAIResponsesModelId) {
     return createLanguageModel(modelId);
   };
@@ -393,7 +367,12 @@ export function createOpenAI(
   provider.skills = createSkills;
   provider.experimental_batch = createBatch;
 
-  provider.experimental_realtime = experimentalRealtimeFactory;
+  provider.experimental_realtime = createOpenAIRealtimeFactory({
+    provider: providerName,
+    baseURL,
+    headers: getHeaders,
+    fetch: options.fetch,
+  });
 
   provider.tools = openaiTools;
 

package/src/realtime/openai-realtime-event-mapper.ts

@@ -9,7 +9,11 @@ type OpenAIRealtimeWireEvent = {
   session?: { id?: string };
   item?: { id?: string } & Record<string, unknown>;
   response?: { id?: string; status?: string };
-  error?: { message?: string; code?: string };
+  error?: {
+    message?: string | null;
+    code?: string | null;
+    event_id?: string | null;
+  } | null;
   item_id: string;
   previous_item_id?: string;
   response_id: string;
@@ -217,6 +221,7 @@ export function parseOpenAIRealtimeServerEvent(
         type: 'error',
         message: event.error?.message ?? event.message ?? 'Unknown error',
         code: event.error?.code ?? event.code,
+        clientEventId: event.error?.event_id ?? undefined,
         raw,
       };
 
@@ -238,12 +243,14 @@ export function serializeOpenAIRealtimeClientEvent(
       return {
         type: 'session.update',
         session: buildOpenAISessionConfig(event.config, modelId),
+        ...(event.eventId != null ? { event_id: event.eventId } : {}),
       };
 
     case 'input-audio-append':
       return {
         type: 'input_audio_buffer.append',
         audio: event.audio,
+        ...(event.eventId != null ? { event_id: event.eventId } : {}),
       };
 
     case 'input-audio-commit':

package/src/realtime/openai-realtime-factory.ts

@@ -0,0 +1,88 @@
+import {
+  InvalidArgumentError,
+  UnsupportedFunctionalityError,
+  type Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
+  type Experimental_RealtimeModelV4 as RealtimeModelV4,
+} from '@ai-sdk/provider';
+import { OpenAIRealtimeModelLive } from '../live/openai-realtime-model-live';
+import {
+  OpenAIRealtimeModel,
+  type OpenAIRealtimeModelConfig,
+} from './openai-realtime-model';
+
+const knownLiveModelIds = ['gpt-live-1'] as const;
+
+export type OpenAIRealtimeOptions = {
+  /** Overrides model ID routing, including for early-access models. */
+  api?: 'live' | 'realtime';
+};
+
+export interface OpenAIRealtimeFactory extends RealtimeFactoryV4 {
+  (modelId: string, options: { api: 'live' }): OpenAIRealtimeModelLive;
+  (modelId: string, options: { api: 'realtime' }): OpenAIRealtimeModel;
+  (
+    modelId: (typeof knownLiveModelIds)[number],
+    options?: { api?: undefined },
+  ): OpenAIRealtimeModelLive;
+  (modelId: string, options?: OpenAIRealtimeOptions): RealtimeModelV4;
+
+  getToken(
+    options: Parameters<RealtimeFactoryV4['getToken']>[0] &
+      OpenAIRealtimeOptions,
+  ): ReturnType<RealtimeFactoryV4['getToken']>;
+}
+
+function resolveRealtimeApi(
+  modelId: string,
+  { api }: OpenAIRealtimeOptions = {},
+): 'live' | 'realtime' {
+  if (api !== undefined) {
+    if (api !== 'live' && api !== 'realtime') {
+      throw new InvalidArgumentError({
+        argument: 'api',
+        message: 'OpenAI realtime api must be "live" or "realtime".',
+      });
+    }
+    return api;
+  }
+
+  return knownLiveModelIds.some(knownModelId => knownModelId === modelId)
+    ? 'live'
+    : 'realtime';
+}
+
+export function createOpenAIRealtimeFactory(
+  config: OpenAIRealtimeModelConfig,
+): OpenAIRealtimeFactory {
+  const createModel = (modelId: string, options?: OpenAIRealtimeOptions) => {
+    const api = resolveRealtimeApi(modelId, options);
+    const modelConfig = { ...config, provider: `${config.provider}.${api}` };
+    return api === 'live'
+      ? new OpenAIRealtimeModelLive(modelId, modelConfig)
+      : new OpenAIRealtimeModel(modelId, modelConfig);
+  };
+
+  return Object.assign(createModel, {
+    getToken: async (
+      options: Parameters<OpenAIRealtimeFactory['getToken']>[0],
+    ) => {
+      const model = createModel(options.model, options);
+      if (model instanceof OpenAIRealtimeModelLive) {
+        throw new UnsupportedFunctionalityError({
+          functionality:
+            'Short-lived OpenAI credentials for the Live API. Use server WebSocket setup via getServerWebSocketConfig() with a server-side API key instead.',
+        });
+      }
+
+      const secret = await model.doCreateClientSecret({
+        sessionConfig: options.sessionConfig,
+        expiresAfterSeconds: options.expiresAfterSeconds,
+      });
+      return {
+        token: secret.token,
+        url: secret.url,
+        expiresAt: secret.expiresAt,
+      };
+    },
+  }) as OpenAIRealtimeFactory;
+}

package/src/responses/openai-responses-language-model-options.ts

@@ -179,6 +179,15 @@ export const openaiLanguageModelResponsesOptionsSchema = lazySchema(() =>
         )
         .nullish(),
 
+      /**
+       * Whether to automatically include web search action sources in the
+       * response. Disable this for OpenAI-compatible providers that do not
+       * support the `web_search_call.action.sources` include value.
+       *
+       * Defaults to `true`.
+       */
+      includeWebSearchSources: z.boolean().optional(),
+
       /**
        * Instructions for the model.
        * They can be used to change the system or developer message when continuing a conversation using the `previousResponseId` option.

package/src/responses/openai-responses-language-model.ts

@@ -70,6 +70,7 @@ import {
   isUndeclaredParallelToolCall,
 } from './expand-parallel-tool-call';
 import { mapOpenAIResponseFinishReason } from './map-openai-responses-finish-reason';
+import { normalizeOpenAIJsonSchema } from '../normalize-openai-json-schema';
 import {
   openaiResponsesChunkSchema,
   openaiResponsesResponseSchema,
@@ -444,6 +445,14 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
     }
 
     const strictJsonSchema = openaiOptions?.strictJsonSchema ?? true;
+    const normalizedResponseFormatSchema =
+      responseFormat?.type === 'json' && responseFormat.schema != null
+        ? normalizeOpenAIJsonSchema(responseFormat.schema)
+        : undefined;
+
+    if (normalizedResponseFormatSchema != null) {
+      warnings.push(...normalizedResponseFormatSchema.warnings);
+    }
 
     let include: OpenAIResponsesIncludeOptions = openaiOptions?.include;
 
@@ -486,7 +495,11 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
       ) as LanguageModelV4ProviderTool | undefined
     )?.name;
 
-    if (webSearchToolName) {
+    if (
+      webSearchToolName &&
+      config.supportsWebSearchSourcesInclude !== false &&
+      openaiOptions?.includeWebSearchSources !== false
+    ) {
       addInclude('web_search_call.action.sources');
     }
 
@@ -513,13 +526,13 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
         text: {
           ...(responseFormat?.type === 'json' && {
             format:
-              responseFormat.schema != null
+              normalizedResponseFormatSchema != null
                 ? {
                     type: 'json_schema',
                     strict: strictJsonSchema,
                     name: responseFormat.name ?? 'response',
                     description: responseFormat.description,
-                    schema: responseFormat.schema,
+                    schema: normalizedResponseFormatSchema.schema,
                   }
                 : { type: 'json_object' },
           }),