@ai-sdk/openai 4.0.108 → 4.0.110

package/docs/03-openai.mdx

@@ -1005,7 +1005,20 @@ const result = await generateText({
 
 The code interpreter tool can be configured with:
 
-- **container**: Either a container ID string or an object with `fileIds` to specify uploaded files that should be available to the code interpreter
+- **container**: Either:
+  - a container ID (`string`) to reuse an existing container, or
+  - a configuration `object` to create and configure a new container.
+
+- **container configuration object**
+  - **fileIds** _string[]_ — File IDs to make available in the container at startup
+  - **memoryLimit** _'1g' | '4g' | '16g' | '64g'_ — Memory limit for the container
+  - **networkPolicy** — Network access policy for outbound requests:
+    - `{ type: 'disabled' }` — No outbound network access
+    - `{ type: 'allowlist', allowedDomains: string[], domainSecrets?: Array<{ domain, name, value }> }`
+      — Allow outbound access only to the specified domains, with optional per-domain secrets
+
+The organization's hosted tool settings must permit the requested network policy.
+An allowlist request cannot enable networking when the organization disables it.
 
 <Note>
   When working with files generated by the Code Interpreter, reference
@@ -1016,7 +1029,7 @@ The code interpreter tool can be configured with:
 
 #### MCP Tool
 
-The OpenAI responses API supports connecting to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers through the `openai.tools.mcp` tool. This allows models to call tools exposed by remote MCP servers or service connectors.
+The OpenAI responses API supports connecting to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers through the `openai.tools.mcp` tool. This allows models to call tools exposed by remote MCP servers, service connectors, or [Secure MCP tunnels](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels).
 
 ```ts
 import { openai } from '@ai-sdk/openai';
@@ -1035,19 +1048,47 @@ const result = await generateText({
 });
 ```
 
+For a private MCP server exposed through an OpenAI Secure MCP tunnel, provide
+its tunnel ID instead of a server URL or connector ID. First configure the tunnel
+in OpenAI and run its tunnel client against your MCP server. The SDK uses the
+existing tunnel; it does not create or discover one:
+
+```ts
+const result = await generateText({
+  model: openai.responses('gpt-5-mini'),
+  prompt: 'Search the private knowledge base',
+  tools: {
+    mcp: openai.tools.mcp({
+      serverLabel: 'private-knowledge',
+      tunnelId: 'tunnel_0123456789abcdef0123456789abcdef',
+      serverDescription: 'A private knowledge base',
+      allowedTools: { readOnly: true },
+      requireApproval: 'always',
+    }),
+  },
+});
+```
+
+When reading a tunnel ID from an environment variable, check that it is defined
+before passing it to `tunnelId`, which requires a string.
+
 The MCP tool can be configured with:
 
 - **serverLabel** _string_ (required)
 
   A label to identify the MCP server. This label is used in tool calls to distinguish between multiple MCP servers.
 
-- **serverUrl** _string_ (required if `connectorId` is not provided)
+- **serverUrl** _string_ (required if `connectorId` and `tunnelId` are not provided)
 
-  The URL for the MCP server. Either `serverUrl` or `connectorId` must be provided.
+  The URL for the MCP server. Cannot be combined with `tunnelId`.
 
-- **connectorId** _string_ (required if `serverUrl` is not provided)
+- **connectorId** _string_ (required if `serverUrl` and `tunnelId` are not provided)
 
-  Identifier for a service connector. Either `serverUrl` or `connectorId` must be provided.
+  Identifier for a service connector. Cannot be combined with `tunnelId`.
+
+- **tunnelId** _string_ (required if `serverUrl` and `connectorId` are not provided)
+
+  Identifier for a configured OpenAI Secure MCP tunnel. Cannot be combined with `serverUrl` or `connectorId`. At least one target must be provided; existing URL and connector configurations remain compatible.
 
 - **serverDescription** _string_ (optional)
 
@@ -1067,7 +1108,7 @@ The MCP tool can be configured with:
 
 - **authorization** _string_ (optional)
 
-  OAuth access token for authenticating with the MCP server or connector.
+  OAuth access token for authenticating with the MCP server or connector (including tunneled servers).
 
 - **headers** _Record&lt;string, string&gt;_ (optional)
 
@@ -1964,6 +2005,47 @@ message into `result.output`. This prevents commentary or repeated final answers
 from being joined into invalid JSON. The returned `text`, `content`, response
 messages, and token usage still include the complete response as before.
 
+#### Refusals
+
+The Responses API can answer a request with a `refusal` content part instead of
+`output_text`. The provider surfaces the refusal explanation as text, and
+reports a `content-filter` finish reason in both `generateText` and
+`streamText`. When the same response also contains a client-side function call,
+the finish reason is `tool-calls` instead, so the tools are still executed; the
+refusal text remains part of the content.
+
+Refusal content parts mainly appear with structured outputs (`Output.object` or
+a JSON schema passed to the model). With structured output, a refusal means no
+object can be generated: `generateText` throws `NoObjectGeneratedError` with the
+refusal text on `error.text` and `error.finishReason` set to `'content-filter'`.
+
+```ts
+import { NoObjectGeneratedError, Output, generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+try {
+  await generateText({
+    model: openai.responses('gpt-4o'),
+    output: Output.object({
+      schema: z.object({ steps: z.array(z.string()) }),
+    }),
+    prompt: '...',
+  });
+} catch (error) {
+  if (NoObjectGeneratedError.isInstance(error)) {
+    // the model's refusal explanation
+    console.log(error.text);
+    // 'content-filter'
+    console.log(error.finishReason);
+  }
+}
+```
+
+Without structured output, the model may still decline in plain text. Such a
+response arrives as ordinary text with a `stop` finish reason, so check the text
+in your application if you need to detect declines.
+
 #### Typed providerMetadata in Text Parts
 
 When using the OpenAI Responses API, the SDK attaches OpenAI-specific metadata to output parts via `providerMetadata`.
@@ -2501,6 +2583,49 @@ The following optional provider options are available for OpenAI chat models:
 
   Force treating this model as a reasoning model. This is useful for "stealth" reasoning models (e.g. via a custom baseURL) where the model ID is not recognized by the SDK's allowlist. When enabled, the SDK applies reasoning-model parameter compatibility rules and defaults `systemMessageMode` to `developer` unless overridden.
 
+#### Message Names
+
+Chat Completions accepts an optional participant name on each system, developer,
+user, or assistant message. Set `providerOptions.openai.name` on the message to
+help the model distinguish participants with the same role. Use pseudonyms instead
+of personal identifiers when possible; names are sent to the provider with the
+message.
+
+```ts
+import { openai, type OpenAIChatMessageProviderOptions } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai.chat('gpt-4.1-mini'),
+  messages: [
+    {
+      role: 'user',
+      content: 'My favorite color is blue.',
+      providerOptions: {
+        openai: { name: 'alice' } satisfies OpenAIChatMessageProviderOptions,
+      },
+    },
+    {
+      role: 'user',
+      content: 'My favorite color is green. What are our favorite colors?',
+      providerOptions: {
+        openai: { name: 'bob' } satisfies OpenAIChatMessageProviderOptions,
+      },
+    },
+  ],
+});
+```
+
+Names also work with `streamText`. Configure them on the message, rather than on
+individual content parts or in the call-level provider options. Non-string values
+are rejected during provider option validation. Tool messages do not support
+participant names: a configured name is omitted with an `unsupported` warning.
+
+This option applies to Chat Completions through `openai.chat()`, including Azure
+Chat models using `providerOptions.openai.name`. The default OpenAI Responses
+model does not support message names. A name identifies a conversation participant;
+it is separate from the call-level `user` and `safetyIdentifier` options.
+
 #### Reasoning
 
 OpenAI has introduced the `o1`,`o3`, and `o4` series of [reasoning models](https://platform.openai.com/docs/guides/reasoning).
@@ -2621,6 +2746,33 @@ You need to change Zod `.nullish()` and `.optional()` to `.nullable()`.
 
 </Note>
 
+#### Refusals
+
+Refusals mainly happen when you request structured outputs. When OpenAI declines
+a request, the provider surfaces the refusal explanation as text and reports a
+`content-filter` finish reason in both `generateText` and `streamText`:
+
+```ts
+const { text, finishReason } = await generateText({
+  model: openai.chat('gpt-4o'),
+  prompt: '...',
+});
+
+if (finishReason === 'content-filter') {
+  // `text` contains the model's refusal explanation
+}
+```
+
+When you request structured output, a refusal means that no object can be
+generated: `generateText` throws `NoObjectGeneratedError` with the refusal text
+on `error.text`.
+
+When you request logprobs, `providerMetadata.openai.logprobs` contains the
+logprobs of all emitted tokens: the content logprobs first, followed by the
+refusal logprobs. This is the same for `generateText` and `streamText`; with
+`streamText`, the logprobs of all streamed tokens are reported when the stream
+finishes.
+
 #### Logprobs
 
 OpenAI provides logprobs information for completion/chat models.
@@ -3164,6 +3316,8 @@ is supported.
 
 ## Realtime Models
 
+OpenAI Realtime also supports trusted [server-owned connections](/docs/ai-sdk-core/realtime#server-owned-connections) through `getServerWebSocketConfig({ intent })`, with conversation and transcription intents and normalized completion usage. Use the same intent for connection setup and event serialization. OpenAI Live retains its conversation-only server connection API and duration snapshots.
+
 <Note type="warning">Realtime is an experimental feature.</Note>
 
 Use `.experimental_realtime()` for both [OpenAI Realtime](https://platform.openai.com/docs/guides/realtime)
@@ -3422,6 +3576,31 @@ const { images } = await generateImage({
 });
 ```
 
+#### Moderation
+
+GPT Image models accept a `moderation` level on edits as well as on generations. The default, `auto`, is the standard filtering; `low` applies less restrictive filtering:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { openai, type OpenAIImageModelEditOptions } from '@ai-sdk/openai';
+import { generateImage } from 'ai';
+
+const imageBuffer = readFileSync('./input-image.png');
+
+const { images } = await generateImage({
+  model: openai.image('gpt-image-2.5-flare'),
+  prompt: {
+    text: 'Draw the same scene at dusk',
+    images: [imageBuffer],
+  },
+  providerOptions: {
+    openai: {
+      moderation: 'low',
+    } satisfies OpenAIImageModelEditOptions,
+  },
+});
+```
+
 #### Multi-Image Combining
 
 Combine multiple reference images into a single output. `gpt-image-*` models support up to 16 input images:
@@ -3453,6 +3632,8 @@ const { images } = await generateImage({
 
 | Model                    | Sizes                                  |
 | ------------------------ | -------------------------------------- |
+| `gpt-image-2.6-flare`    | Standard presets and custom dimensions |
+| `gpt-image-2.6-sunburst` | Standard presets and custom dimensions |
 | `gpt-image-2.5-flare`    | Standard presets and custom dimensions |
 | `gpt-image-2.5-sunburst` | Standard presets and custom dimensions |
 | `gpt-image-2`            | 1024x1024, 1536x1024, 1024x1536        |
@@ -3499,6 +3680,28 @@ const { image } = await generateImage({
 });
 ```
 
+The `gpt-image-2.6-flare` and `gpt-image-2.6-sunburst` models support these additional options:
+
+- **complexity** _'low' | 'medium' | 'high'_ - how much detail the model puts into the image (generation and editing). The API defaults to `high`.
+- **outputFormat: 'gif'** _(generation only)_ - generates an animated GIF. Use **frameCount** (2-64, API default 9) and **frameDurationMs** (20-2000, API default 200) to control the animation.
+- **markup** _string_ _(editing only)_ - a transparent PNG (HTTPS URL or base64 data URL) overlaid on the first input image to mark up the regions to change. Supported by `gpt-image-2.5-*` and `gpt-image-2.6-*` models. It cannot be combined with `mask`; providing both throws an error.
+
+```ts
+const { image } = await generateImage({
+  model: openai.image('gpt-image-2.6-flare'),
+  prompt: 'A red panda waving hello, flat illustration',
+  providerOptions: {
+    openai: {
+      outputFormat: 'gif',
+      frameCount: 9,
+      frameDurationMs: 200,
+    } satisfies OpenAIImageModelGenerationOptions,
+  },
+});
+```
+
+All image options also accept `safetyIdentifier` (max 128 characters) to help OpenAI detect abuse by your end users.
+
 For more on `generateImage()` see [Image Generation](/docs/ai-sdk-core/image-generation).
 
 OpenAI's image models return additional metadata in the response that can be
@@ -3569,27 +3772,30 @@ The API validates model support and language codes. These two options currently
 apply to REST transcription; the provider reports unsupported-option warnings
 if they are supplied to `experimental_streamTranscribe`.
 
-To get word-level timestamps, specify the granularity:
+To get word and caption timings together, use the shared setting with a
+model that supports `verbose_json`, such as Whisper:
 
-```ts highlight="8-9"
+```ts
 import { transcribe } from 'ai';
-import { openai, type OpenAITranscriptionModelOptions } from '@ai-sdk/openai';
+import { openai } from '@ai-sdk/openai';
 
 const result = await transcribe({
   model: openai.transcription('whisper-1'),
   audio: new Uint8Array([1, 2, 3, 4]),
-  providerOptions: {
-    openai: {
-      //timestampGranularities: ['word'],
-      timestampGranularities: ['segment'],
-    } satisfies OpenAITranscriptionModelOptions,
-  },
+  timestampGranularities: ['word', 'segment'],
 });
 
-// Access word-level timestamps
-console.log(result.segments); // Array of segments with startSecond/endSecond
+console.log(result.words);
+console.log(result.segments);
 ```
 
+`providerOptions.openai.timestampGranularities` takes precedence over the shared
+setting. If neither is set, `verbose_json` defaults to segment timings.
+`timestamp_granularities` is sent only for `verbose_json`; other formats warn
+about unavailable requested timings. `diarized_json` provides segment timings
+but does not provide word timings. Existing segment behavior is preserved:
+if the response has words but no segments, `segments` also contains those words.
+
 `gpt-4o-transcribe-diarize` identifies speakers in a recording. It defaults to
 the `diarized_json` response format and automatic chunking:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.108",
+  "version": "4.0.110",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.35",
-    "@ai-sdk/provider-utils": "5.0.74"
+    "@ai-sdk/provider": "4.0.36",
+    "@ai-sdk/provider-utils": "5.0.75"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

package/src/chat/convert-to-openai-chat-messages.ts

@@ -6,6 +6,7 @@ import {
 } from '@ai-sdk/provider';
 import type { OpenAIChatPrompt } from './openai-chat-prompt';
 import {
+  parseProviderOptions,
   secureJsonParse,
   stringifyWithBigIntAndCycles,
   convertToBase64,
@@ -14,6 +15,8 @@ import {
   resolveProviderReference,
 } from '@ai-sdk/provider-utils';
 
+import { openaiChatMessageProviderOptions } from './openai-chat-language-model-options';
+
 function serializeToolCallArguments(input: unknown): string {
   if (typeof input === 'string') {
     try {
@@ -47,20 +50,27 @@ function getPromptCacheBreakpoint(
     | undefined;
 }
 
-export function convertToOpenAIChatMessages({
+export async function convertToOpenAIChatMessages({
   prompt,
   systemMessageMode = 'system',
 }: {
   prompt: LanguageModelV4Prompt;
   systemMessageMode?: 'system' | 'developer' | 'remove';
-}): {
+}): Promise<{
   messages: OpenAIChatPrompt;
   warnings: Array<SharedV4Warning>;
-} {
+}> {
   const messages: OpenAIChatPrompt = [];
   const warnings: Array<SharedV4Warning> = [];
 
   for (const { role, content, providerOptions } of prompt) {
+    const messageOptions = await parseProviderOptions({
+      provider: 'openai',
+      providerOptions,
+      schema: openaiChatMessageProviderOptions,
+    });
+    const name = messageOptions?.name;
+
     switch (role) {
       case 'system': {
         switch (systemMessageMode) {
@@ -69,6 +79,7 @@ export function convertToOpenAIChatMessages({
               getPromptCacheBreakpoint(providerOptions);
             messages.push({
               role: 'system',
+              ...(name != null && { name }),
               content:
                 promptCacheBreakpoint == null
                   ? content
@@ -87,6 +98,7 @@ export function convertToOpenAIChatMessages({
               getPromptCacheBreakpoint(providerOptions);
             messages.push({
               role: 'developer',
+              ...(name != null && { name }),
               content:
                 promptCacheBreakpoint == null
                   ? content
@@ -123,12 +135,17 @@ export function convertToOpenAIChatMessages({
           content[0].type === 'text' &&
           getPromptCacheBreakpoint(content[0].providerOptions) == null
         ) {
-          messages.push({ role: 'user', content: content[0].text });
+          messages.push({
+            role: 'user',
+            content: content[0].text,
+            ...(name != null && { name }),
+          });
           break;
         }
 
         messages.push({
           role: 'user',
+          ...(name != null && { name }),
           content: content.map((part, index) => {
             switch (part.type) {
               case 'text': {
@@ -311,6 +328,7 @@ export function convertToOpenAIChatMessages({
 
         messages.push({
           role: 'assistant',
+          ...(name != null && { name }),
           content: hasPromptCacheBreakpoint
             ? textParts
             : toolCalls.length > 0
@@ -323,6 +341,13 @@ export function convertToOpenAIChatMessages({
       }
 
       case 'tool': {
+        if (name != null) {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'message name on tool messages',
+          });
+        }
+
         for (const toolResponse of content) {
           if (toolResponse.type === 'tool-approval-response') {
             continue;

package/src/chat/map-openai-finish-reason.ts

@@ -1,11 +1,18 @@
 import type { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
-export function mapOpenAIFinishReason(
-  finishReason: string | null | undefined,
-): LanguageModelV4FinishReason['unified'] {
+export function mapOpenAIFinishReason({
+  finishReason,
+  hasRefusal = false,
+}: {
+  finishReason: string | null | undefined;
+  // flag that checks if the model refused to answer:
+  hasRefusal?: boolean;
+}): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'stop':
-      return 'stop';
+      // OpenAI reports a completed response for refusals, so the refusal is
+      // the reason the response ended:
+      return hasRefusal ? 'content-filter' : 'stop';
     case 'length':
       return 'length';
     case 'content_filter':

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

@@ -36,6 +36,8 @@ export const openaiChatResponseSchema = lazySchema(() =>
           message: z.object({
             role: z.literal('assistant').nullish(),
             content: z.string().nullish(),
+            // set instead of `content` when the model refuses to answer:
+            refusal: z.string().nullish(),
             audio: z
               .object({
                 transcript: z.string().nullish(),
@@ -84,6 +86,22 @@ export const openaiChatResponseSchema = lazySchema(() =>
                   }),
                 )
                 .nullish(),
+              // logprobs of the refusal tokens (set instead of `content` when
+              // the model refuses to answer):
+              refusal: z
+                .array(
+                  z.object({
+                    token: z.string(),
+                    logprob: z.number(),
+                    top_logprobs: z.array(
+                      z.object({
+                        token: z.string(),
+                        logprob: z.number(),
+                      }),
+                    ),
+                  }),
+                )
+                .nullish(),
             })
             .nullish(),
           finish_reason: z.string().nullish(),
@@ -128,6 +146,8 @@ export const openaiChatChunkSchema = lazySchema(() =>
               .object({
                 role: z.enum(['assistant']).nullish(),
                 content: z.string().nullish(),
+                // set instead of `content` when the model refuses to answer:
+                refusal: z.string().nullish(),
                 tool_calls: z
                   .array(
                     z.object({
@@ -172,6 +192,22 @@ export const openaiChatChunkSchema = lazySchema(() =>
                     }),
                   )
                   .nullish(),
+                // logprobs of the refusal tokens (set instead of `content` when
+                // the model refuses to answer):
+                refusal: z
+                  .array(
+                    z.object({
+                      token: z.string(),
+                      logprob: z.number(),
+                      top_logprobs: z.array(
+                        z.object({
+                          token: z.string(),
+                          logprob: z.number(),
+                        }),
+                      ),
+                    }),
+                  )
+                  .nullish(),
               })
               .nullish(),
             finish_reason: z.string().nullish(),

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

@@ -232,3 +232,16 @@ export const openaiLanguageModelChatOptions = lazySchema(() =>
 export type OpenAILanguageModelChatOptions = InferSchema<
   typeof openaiLanguageModelChatOptions
 >;
+
+export const openaiChatMessageProviderOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /** The participant name on a system, developer, user, or assistant message. */
+      name: z.string().optional(),
+    }),
+  ),
+);
+
+export type OpenAIChatMessageProviderOptions = InferSchema<
+  typeof openaiChatMessageProviderOptions
+>;