@ai-sdk/openai 4.0.108 → 4.0.110

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

@@ -53,6 +53,15 @@ import {
 import { prepareChatTools } from './openai-chat-prepare-tools';
 import { normalizeOpenAIJsonSchema } from '../normalize-openai-json-schema';
 
+type OpenAIChatLogprob = NonNullable<
+  NonNullable<
+    Extract<
+      OpenAIChatChunk,
+      { choices: unknown }
+    >['choices'][number]['logprobs']
+  >['content']
+>[number];
+
 type OpenAIChatConfig = {
   provider: string;
   /** Model ID sent to the API. Defaults to the model's reported ID. */
@@ -178,16 +187,15 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
       });
     }
 
-    const { messages, warnings: messageWarnings } = convertToOpenAIChatMessages(
-      {
+    const { messages, warnings: messageWarnings } =
+      await convertToOpenAIChatMessages({
         prompt,
         systemMessageMode:
           openaiOptions.systemMessageMode ??
           (isReasoningModel
             ? 'developer'
             : modelRequestConfig.systemMessageMode),
-      },
-    );
+      });
 
     warnings.push(...messageWarnings);
 
@@ -414,16 +422,17 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
     options: LanguageModelV4CallOptions,
   ): Promise<LanguageModelV4GenerateResult> {
     const { args: body, warnings } = await this.getArgs(options);
+    const url = this.config.url({
+      path: '/chat/completions',
+      modelId: this.config.requestModelId ?? this.modelId,
+    });
 
     const {
       responseHeaders,
       value: response,
       rawValue: rawResponse,
     } = await postJsonToApi({
-      url: this.config.url({
-        path: '/chat/completions',
-        modelId: this.config.requestModelId ?? this.modelId,
-      }),
+      url,
       headers: combineHeaders(
         await resolve(this.config.headers),
         options.headers,
@@ -447,7 +456,10 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
     const content: Array<LanguageModelV4Content> = [];
 
-    // text content:
+    // text content. When the model refuses to answer, the API returns the
+    // refusal in `refusal` and sets `content` to null, so surface it as text
+    // instead of dropping it. Content and refusal are both returned when the
+    // model refuses after answering, so keep both:
     const text =
       choice.message.content != null && choice.message.content.length > 0
         ? choice.message.content
@@ -456,6 +468,12 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
       content.push({ type: 'text', text });
     }
 
+    const refusal = choice.message.refusal;
+    const hasRefusal = refusal != null && refusal.length > 0;
+    if (hasRefusal) {
+      content.push({ type: 'text', text: refusal });
+    }
+
     // tool calls:
     for (const toolCall of choice.message.tool_calls ?? []) {
       content.push({
@@ -488,18 +506,29 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
       providerMetadata.openai.rejectedPredictionTokens =
         completionTokenDetails?.rejected_prediction_tokens;
     }
-    if (choice.logprobs?.content != null) {
-      providerMetadata.openai.logprobs = choice.logprobs.content;
+    // logprobs either follow the text content (content) or the refusal, so
+    // combine them in the order the text is emitted above. Explicitly empty
+    // logprobs are reported as an empty array, as before:
+    const contentLogprobs = choice.logprobs?.content;
+    const refusalLogprobs = choice.logprobs?.refusal;
+    if (contentLogprobs != null || refusalLogprobs != null) {
+      providerMetadata.openai.logprobs = [
+        ...(contentLogprobs ?? []),
+        ...(refusalLogprobs ?? []),
+      ];
     }
 
     return {
       content,
       finishReason: {
-        unified: mapOpenAIFinishReason(choice.finish_reason),
+        unified: mapOpenAIFinishReason({
+          finishReason: choice.finish_reason,
+          hasRefusal,
+        }),
         raw: choice.finish_reason ?? undefined,
       },
       usage: convertOpenAIChatUsage(response.usage),
-      request: { body },
+      request: { body, url },
       response: {
         ...getResponseMetadata(response),
         headers: responseHeaders,
@@ -562,6 +591,13 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
     let usage: OpenAIChatUsage | undefined = undefined;
     let metadataExtracted = false;
     let isActiveText = false;
+    let hasRefusal = false;
+    let rawFinishReason: string | undefined = undefined;
+    let hasLogprobs = false;
+
+    // logprobs of all streamed chunks (content token logprobs followed by
+    // refusal token logprobs), collected across chunks:
+    const streamedLogprobs: OpenAIChatLogprob[] = [];
 
     const providerMetadata: SharedV4ProviderMetadata = { openai: {} };
 
@@ -587,6 +623,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
             // handle failed chunk parsing / validation:
             if (!chunk.success) {
               finishReason = { unified: 'error', raw: undefined };
+              rawFinishReason = undefined;
               controller.enqueue({ type: 'error', error: chunk.error });
               return;
             }
@@ -596,6 +633,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
             // handle error chunks:
             if ('error' in value) {
               finishReason = { unified: 'error', raw: undefined };
+              rawFinishReason = undefined;
               controller.enqueue({
                 type: 'error',
                 error:
@@ -639,15 +677,29 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
             const choice = value.choices[0];
 
+            // store the raw finish reason and map it in `flush`, after all
+            // chunks have been read: some servers send the last delta (which
+            // can contain a refusal) in the same chunk as the finish reason,
+            // and a refusal turns `stop` into `content-filter`:
             if (choice?.finish_reason != null) {
-              finishReason = {
-                unified: mapOpenAIFinishReason(choice.finish_reason),
-                raw: choice.finish_reason,
-              };
+              rawFinishReason = choice.finish_reason;
             }
 
-            if (choice?.logprobs?.content != null) {
-              providerMetadata.openai.logprobs = choice.logprobs.content;
+            // logprobs either follow the text content (content) or the refusal.
+            // They are streamed token by token, so collect the logprobs of all
+            // chunks (content logprobs followed by refusal logprobs) and report
+            // the complete list at the end of the stream:
+            if (choice?.logprobs != null) {
+              const contentLogprobs = choice.logprobs.content;
+              const refusalLogprobs = choice.logprobs.refusal;
+
+              if (contentLogprobs != null || refusalLogprobs != null) {
+                hasLogprobs = true;
+                streamedLogprobs.push(
+                  ...(contentLogprobs ?? []),
+                  ...(refusalLogprobs ?? []),
+                );
+              }
             }
 
             if (choice?.delta == null) {
@@ -656,7 +708,24 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
             const delta = choice.delta;
 
-            if (delta.content != null) {
+            // When the model refuses to answer, the API streams the refusal in
+            // `refusal` instead of `content`. Content and refusal deltas can
+            // both occur, so append each to the same text part instead of
+            // dropping one:
+            const textDeltas: string[] = [];
+            if (delta.content != null && delta.content.length > 0) {
+              textDeltas.push(delta.content);
+            }
+            if (delta.refusal != null && delta.refusal.length > 0) {
+              hasRefusal = true;
+              textDeltas.push(delta.refusal);
+            }
+            // empty `content: ""` deltas keep their previous behavior:
+            if (textDeltas.length === 0 && delta.content === '') {
+              textDeltas.push(delta.content);
+            }
+
+            for (const textDelta of textDeltas) {
               if (!isActiveText) {
                 controller.enqueue({ type: 'text-start', id: '0' });
                 isActiveText = true;
@@ -665,7 +734,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
               controller.enqueue({
                 type: 'text-delta',
                 id: '0',
-                delta: delta.content,
+                delta: textDelta,
               });
             }
 
@@ -696,6 +765,25 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
             toolCallTracker.flush();
 
+            // map the stored finish reason now that all deltas (including
+            // refusals that arrived in the same chunk as the finish reason)
+            // have been read:
+            if (rawFinishReason != null) {
+              finishReason = {
+                unified: mapOpenAIFinishReason({
+                  finishReason: rawFinishReason,
+                  hasRefusal,
+                }),
+                raw: rawFinishReason,
+              };
+            }
+
+            // report the logprobs of all streamed chunks (content logprobs
+            // followed by refusal logprobs), not only the last chunk:
+            if (hasLogprobs) {
+              providerMetadata.openai.logprobs = streamedLogprobs;
+            }
+
             controller.enqueue({
               type: 'finish',
               finishReason,
@@ -705,7 +793,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
           },
         }),
       ),
-      request: { body },
+      request: { body, url },
       response: { headers: responseHeaders },
     };
 
@@ -723,6 +811,7 @@ function isOpenAIChatOutputChunk(chunk: OpenAIChatChunk): boolean {
 
     return (
       (delta?.content != null && delta.content.length > 0) ||
+      (delta?.refusal != null && delta.refusal.length > 0) ||
       (delta?.tool_calls != null && delta.tool_calls.length > 0) ||
       (delta?.annotations != null && delta.annotations.length > 0)
     );

package/src/chat/openai-chat-prompt.ts

@@ -8,16 +8,19 @@ export type ChatCompletionMessage =
   | ChatCompletionToolMessage;
 
 export interface ChatCompletionSystemMessage {
+  name?: string;
   role: 'system';
   content: string | Array<ChatCompletionContentPartText>;
 }
 
 export interface ChatCompletionDeveloperMessage {
+  name?: string;
   role: 'developer';
   content: string | Array<ChatCompletionContentPartText>;
 }
 
 export interface ChatCompletionUserMessage {
+  name?: string;
   role: 'user';
   content: string | Array<ChatCompletionContentPart>;
 }
@@ -53,6 +56,7 @@ export interface ChatCompletionContentPartFile {
 }
 
 export interface ChatCompletionAssistantMessage {
+  name?: string;
   role: 'assistant';
   content?: string | null | Array<ChatCompletionContentPartText>;
   tool_calls?: Array<ChatCompletionMessageToolCall>;

package/src/image/openai-image-model-options.ts

@@ -16,6 +16,8 @@ export type OpenAIImageModelId =
   | 'gpt-image-1-mini'
   | 'gpt-image-1.5'
   | 'gpt-image-2'
+  | 'gpt-image-2.6-flare'
+  | 'gpt-image-2.6-sunburst'
   | 'gpt-image-2.5-flare'
   | 'gpt-image-2.5-flare-2026-09-08'
   | 'gpt-image-2.5-sunburst'
@@ -64,6 +66,12 @@ const baseImageModelOptionsObject = () =>
      */
     outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
 
+    /**
+     * How much detail the model puts into the image. Supported by GPT Image
+     * 2.6 models. The API defaults to `high`.
+     */
+    complexity: z.enum(['low', 'medium', 'high']).optional(),
+
     /**
      * Compression level (0-100) for the generated image(s). Applies to the
      * `jpeg` and `webp` output formats.
@@ -75,6 +83,13 @@ const baseImageModelOptionsObject = () =>
      * to monitor and detect abuse.
      */
     user: z.string().optional(),
+
+    /**
+     * A stable identifier used to help detect users of your application that
+     * may be violating OpenAI's usage policies. Should be a hashed username
+     * or email address.
+     */
+    safetyIdentifier: z.string().max(128).optional(),
   });
 
 export const openaiImageModelOptions = lazySchema(() =>
@@ -95,6 +110,25 @@ export const openaiImageModelGenerationOptions = lazySchema(() =>
        */
       style: z.enum(['vivid', 'natural']).optional(),
 
+      /**
+       * Format in which the generated image(s) are returned. `gif` produces
+       * an animated GIF and is supported by GPT Image 2.6 models.
+       */
+      outputFormat: z.enum(['png', 'jpeg', 'webp', 'gif']).optional(),
+
+      /**
+       * Number of frames (2-64) of an animated GIF. Only applies to the `gif`
+       * output format. The API defaults to 9.
+       */
+      frameCount: z.number().int().min(2).max(64).optional(),
+
+      /**
+       * Duration of each frame in milliseconds (20-2000) of an animated GIF.
+       * The API rounds it to the nearest 10 ms. Only applies to the `gif`
+       * output format. The API defaults to 200.
+       */
+      frameDurationMs: z.number().int().min(20).max(2000).optional(),
+
       /**
        * Content moderation level for the generated image(s). `low` applies
        * less restrictive filtering.
@@ -115,6 +149,20 @@ export const openaiImageModelEditOptions = lazySchema(() =>
        * Fidelity of the output image(s) to the input image(s).
        */
       inputFidelity: z.enum(['high', 'low']).optional(),
+
+      /**
+       * A transparent PNG overlaid on the first input image to mark up the
+       * regions to change, as an HTTPS URL or a base64 data URL. It must match
+       * the dimensions of the first image. Supported by GPT Image 2.5 and 2.6
+       * models. Cannot be combined with a `mask`.
+       */
+      markup: z.string().optional(),
+
+      /**
+       * Content moderation level for the edited image(s). `low` applies
+       * less restrictive filtering. Supported by GPT Image models.
+       */
+      moderation: z.enum(['auto', 'low']).optional(),
     }),
   ),
 );

package/src/image/openai-image-model.ts

@@ -1,7 +1,8 @@
-import type {
-  ImageModelV4,
-  ImageModelV4File,
-  SharedV4Warning,
+import {
+  InvalidArgumentError,
+  type ImageModelV4,
+  type ImageModelV4File,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   resolve,
@@ -128,6 +129,13 @@ export class OpenAIImageModel implements ImageModelV4 {
           schema: openaiImageModelEditOptions,
         })) ?? {};
 
+      if (mask != null && openaiOptions.markup != null) {
+        throw new InvalidArgumentError({
+          argument: 'providerOptions.openai.markup',
+          message: '`markup` cannot be combined with `mask`.',
+        });
+      }
+
       const { value: response, responseHeaders } = await postFormDataToApi({
         url: this.config.url({
           path: '/images/edits',
@@ -156,14 +164,21 @@ export class OpenAIImageModel implements ImageModelV4 {
             ),
           ),
           mask: mask != null ? await fileToBlob(mask, abortSignal) : undefined,
+          markup:
+            openaiOptions.markup != null
+              ? await markupToBlob(openaiOptions.markup, abortSignal)
+              : undefined,
           n,
           size,
           quality: openaiOptions.quality,
           background: openaiOptions.background,
           output_format: openaiOptions.outputFormat,
           output_compression: openaiOptions.outputCompression,
+          complexity: openaiOptions.complexity,
           input_fidelity: openaiOptions.inputFidelity,
+          moderation: openaiOptions.moderation,
           user: openaiOptions.user,
+          safety_identifier: openaiOptions.safetyIdentifier,
         }),
         failedResponseHandler: openaiFailedResponseHandler,
         successfulResponseHandler: createJsonResponseHandler(
@@ -235,7 +250,11 @@ export class OpenAIImageModel implements ImageModelV4 {
         moderation: openaiOptions.moderation,
         output_format: openaiOptions.outputFormat,
         output_compression: openaiOptions.outputCompression,
+        complexity: openaiOptions.complexity,
+        frame_count: openaiOptions.frameCount,
+        frame_duration_ms: openaiOptions.frameDurationMs,
         user: openaiOptions.user,
+        safety_identifier: openaiOptions.safetyIdentifier,
         ...(!hasDefaultResponseFormat(this.modelId)
           ? { response_format: 'b64_json' }
           : {}),
@@ -326,16 +345,42 @@ type OpenAIImageEditInput = {
   prompt?: string;
   image: Blob | Blob[];
   mask?: Blob;
+  markup?: Blob;
   n?: number;
   size?: `${number}x${number}`;
   quality?: OpenAIImageModelEditOptions['quality'];
   background?: OpenAIImageModelEditOptions['background'];
   output_format?: OpenAIImageModelEditOptions['outputFormat'];
   output_compression?: OpenAIImageModelEditOptions['outputCompression'];
+  complexity?: OpenAIImageModelEditOptions['complexity'];
   input_fidelity?: OpenAIImageModelEditOptions['inputFidelity'];
+  moderation?: OpenAIImageModelEditOptions['moderation'];
   user?: OpenAIImageModelEditOptions['user'];
+  safety_identifier?: OpenAIImageModelEditOptions['safetyIdentifier'];
 };
 
+async function markupToBlob(
+  markup: string,
+  abortSignal: AbortSignal | undefined,
+): Promise<Blob> {
+  const dataUrl = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(markup);
+
+  if (dataUrl == null) {
+    return downloadBlob(markup, { abortSignal });
+  }
+
+  if (dataUrl[2] == null) {
+    throw new InvalidArgumentError({
+      argument: 'providerOptions.openai.markup',
+      message: '`markup` data URLs must be base64 encoded.',
+    });
+  }
+
+  return new Blob([convertBase64ToUint8Array(dataUrl[3]) as BlobPart], {
+    type: dataUrl[1] || 'image/png',
+  });
+}
+
 async function fileToBlob(
   file: ImageModelV4File | undefined,
   abortSignal: AbortSignal | undefined,

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
 export type { OpenAIToolOptions } from './responses/openai-responses-prepare-tools';
 export type {
   OpenAILanguageModelChatOptions,
+  OpenAIChatMessageProviderOptions,
   /** @deprecated Use `OpenAILanguageModelChatOptions` instead. */
   OpenAILanguageModelChatOptions as OpenAIChatLanguageModelOptions,
 } from './chat/openai-chat-language-model-options';

package/src/internal/index.ts

@@ -13,10 +13,14 @@ export * from '../speech/openai-speech-model-options';
 export * from '../responses/openai-responses-language-model';
 export * from '../responses/openai-responses-provider-metadata';
 export * from '../tool/apply-patch';
+export * from '../tool/custom';
 export * from '../tool/code-interpreter';
 export * from '../tool/file-search';
 export * from '../tool/image-generation';
 export * from '../tool/programmatic-tool-calling';
+export * from '../tool/shell';
 export * from '../tool/tool-search';
 export * from '../tool/web-search';
 export * from '../tool/web-search-preview';
+
+export { openaiModelCatalog } from '../openai-model-catalog';

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

@@ -2,6 +2,7 @@ import {
   type Experimental_RealtimeModelV4 as RealtimeModelV4,
   type Experimental_RealtimeModelV4ClientEvent as RealtimeModelV4ClientEvent,
   type Experimental_RealtimeModelV4SessionConfig as RealtimeModelV4SessionConfig,
+  type Experimental_RealtimeModelV4SessionIntent as RealtimeModelV4SessionIntent,
 } from '@ai-sdk/provider';
 import {
   resolveWith,
@@ -54,7 +55,10 @@ export class OpenAIRealtimeModelLive implements RealtimeModelV4 {
     return { dataChannelLabel: 'oai-events' };
   }
 
-  getServerWebSocketConfig() {
+  getServerWebSocketConfig(options?: {
+    intent?: RealtimeModelV4SessionIntent;
+  }) {
+    this.assertConversationIntent(options);
     return resolveWith(this.config.headers, configHeaders => {
       const url = new URL(`${this.config.baseURL}/live/sessions`);
       url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
@@ -103,13 +107,28 @@ export class OpenAIRealtimeModelLive implements RealtimeModelV4 {
     return createOpenAILiveServerEventParser();
   }
 
-  serializeClientEvent(event: RealtimeModelV4ClientEvent): unknown {
+  private assertConversationIntent(options?: {
+    intent?: RealtimeModelV4SessionIntent;
+  }): void {
+    if (options?.intent != null && options.intent !== 'conversation')
+      throw new Error(
+        `OpenAI Live session intent '${options.intent}' is not supported.`,
+      );
+  }
+
+  serializeClientEvent(
+    event: RealtimeModelV4ClientEvent,
+    options?: { intent?: RealtimeModelV4SessionIntent },
+  ): unknown {
+    this.assertConversationIntent(options);
     return serializeOpenAILiveClientEvent(event, this.modelId);
   }
 
   buildSessionConfig(
     config: RealtimeModelV4SessionConfig,
+    options?: { intent?: RealtimeModelV4SessionIntent },
   ): Record<string, unknown> {
+    this.assertConversationIntent(options);
     return buildOpenAILiveSessionConfig(config, this.modelId);
   }
 }

package/src/openai-batch.ts

@@ -748,6 +748,7 @@ async function convertOpenAIBatchResult(
   const content: LanguageModelV4GenerateResult['content'] = [];
   const logprobs: Array<NonNullable<OpenAIResponsesLogprobs>> = [];
   let hasFunctionCall = false;
+  let hasRefusal = false;
 
   for (const part of response.output) {
     switch (part.type) {
@@ -774,6 +775,12 @@ async function convertOpenAIBatchResult(
 
       case 'message': {
         for (const contentPart of part.content) {
+          if (contentPart.type === 'refusal') {
+            hasRefusal = true;
+            content.push({ type: 'text', text: contentPart.refusal });
+            continue;
+          }
+
           content.push({ type: 'text', text: contentPart.text });
           if (contentPart.logprobs != null) {
             logprobs.push(contentPart.logprobs);
@@ -916,6 +923,7 @@ async function convertOpenAIBatchResult(
         unified: mapOpenAIResponseFinishReason({
           finishReason: response.incomplete_details?.reason,
           hasFunctionCall,
+          hasRefusal,
         }),
         raw: response.incomplete_details?.reason ?? undefined,
       },

package/src/openai-model-catalog.ts

@@ -461,6 +461,8 @@ function createGptImageEntry(
 
 const openaiImageModelEntries: Readonly<Record<string, OpenAIImageModelEntry>> =
   {
+    'gpt-image-2.6-flare': createGptImageEntry(customImageSizes),
+    'gpt-image-2.6-sunburst': createGptImageEntry(customImageSizes),
     'gpt-image-2.5-flare': createGptImageEntry(customImageSizes),
     'gpt-image-2.5-sunburst': createGptImageEntry(customImageSizes),
     'gpt-image-2': createGptImageEntry(gptImageSizes),
@@ -757,7 +759,7 @@ const realtimeModelEntry = {
     realtime: {
       conversation: 'turn-based',
       transports: ['websocket'],
-      connections: ['client-secret-websocket'],
+      connections: ['client-secret-websocket', 'server-websocket'],
     },
   },
   requestConfig: {

package/src/openai-tools.ts

@@ -126,16 +126,17 @@ export const openaiTools = {
 
   /**
    * MCP (Model Context Protocol) allows models to call tools exposed by
-   * remote MCP servers or service connectors.
+   * remote MCP servers, service connectors, or Secure MCP tunnels.
    *
    * @param serverLabel - Label to identify the MCP server.
    * @param allowedTools - Allowed tool names or filter object.
-   * @param authorization - OAuth access token for the MCP server/connector.
+   * @param authorization - OAuth access token for the MCP server or connector (including tunneled servers).
    * @param connectorId - Identifier for a service connector.
    * @param headers - Optional headers to include in MCP requests.
-   * // param requireApproval - Approval policy ('always'|'never'|filter object). (Removed - always 'never')
+   * @param requireApproval - Approval policy ('always'|'never'|filter object).
    * @param serverDescription - Optional description of the server.
    * @param serverUrl - URL for the MCP server.
+   * @param tunnelId - Identifier for an OpenAI Secure MCP tunnel.
    */
   mcp,