@ai-sdk/openai 3.0.108 → 3.0.110

package/docs/03-openai.mdx

@@ -206,9 +206,23 @@ The following provider options are available:
 
 <Note>
   Supported reasoning efforts vary by model. GPT-5.6 supports `'none'`, `'low'`,
-  `'medium'`, `'high'`, `'xhigh'`, and `'max'`.
+  `'medium'`, `'high'`, `'xhigh'`, and `'max'`. GPT-6 and later models support
+  `'low'`, `'medium'`, `'high'`, `'xhigh'`, and `'max'`.
 </Note>
 
+<Note>
+  GPT-6 and later models do not support `temperature`, `topP`, `logprobs`, or
+  the legacy `promptCacheRetention` option. The provider removes these settings
+  and returns a warning. Use the Responses API for GPT-6 tool calling.
+</Note>
+
+- **reasoningEffortUpdate** _'low' | 'medium' | 'high' | 'xhigh' | 'max'_
+  Updates the reasoning effort for GPT-6 and later models starting with the
+  current response without changing the request-level effort. Use this with
+  `previousResponseId` to preserve the original prompt prefix for caching.
+  Configuration updates require standard, single-agent mode and cannot be
+  combined with automatic truncation.
+
 - **reasoningMode** _'standard' | 'pro'_
   Controls how much model work GPT-5.6 performs before returning a final answer. `'standard'` is the default. Use `'pro'` for difficult tasks where quality matters more than latency and token usage.
 
@@ -308,6 +322,58 @@ The following OpenAI-specific metadata may be returned:
 - **reasoningContext** _(optional)_
   Effective persisted-reasoning context returned by GPT-5.6 (`'current_turn'` or `'all_turns'`).
 
+#### Changing Reasoning Effort Mid-Conversation
+
+GPT-6 and later models can change reasoning effort between responses without
+changing the request-level `reasoningEffort` setting. The provider sends
+`reasoningEffortUpdate` as an OpenAI `configuration_update` input item before
+the next user message. Keeping the request-level effort unchanged preserves the
+original prompt prefix for prompt caching.
+
+```ts highlight="13,32,34"
+import {
+  openai,
+  type OpenAILanguageModelResponsesOptions,
+  type OpenaiResponsesProviderMetadata,
+} from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const first = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  prompt: 'Draft a database migration plan.',
+  providerOptions: {
+    openai: {
+      reasoningEffort: 'low',
+    } satisfies OpenAILanguageModelResponsesOptions,
+  },
+});
+
+const metadata = first.providerMetadata as
+  | OpenaiResponsesProviderMetadata
+  | undefined;
+const previousResponseId = metadata?.openai.responseId;
+
+if (!previousResponseId) {
+  throw new Error('OpenAI did not return a response ID.');
+}
+
+const second = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  prompt: 'Analyze the failure modes and propose rollback steps.',
+  providerOptions: {
+    openai: {
+      previousResponseId,
+      reasoningEffort: 'low',
+      reasoningEffortUpdate: 'high',
+    } satisfies OpenAILanguageModelResponsesOptions,
+  },
+});
+```
+
+The response metadata continues to report the request-level reasoning effort,
+not the effective effort selected by `reasoningEffortUpdate`. Configuration
+updates are not supported with `reasoningMode: 'pro'` or `truncation: 'auto'`.
+
 #### Reasoning Output
 
 For reasoning models like `gpt-5`, you can enable reasoning summaries to see the model's thought process. Different models support different summarizers—for example, `o4-mini` supports detailed summaries. Set `reasoningSummary: "auto"` to automatically receive the richest level available.
@@ -482,6 +548,55 @@ metadata on tool-call parts. The SDK uses `providerMetadata.openai.namespace` or
 `providerOptions.openai.namespace` to round-trip the namespace back to OpenAI on
 subsequent requests.
 
+#### Async Tool Calling
+
+GPT-6 Astra and later Responses models support
+[async tool calling](https://developers.openai.com/api/docs/guides/async-tool-calling).
+An async tool lets the model continue generating independent output after issuing
+the call instead of waiting for its result. Your application still executes the
+tool and sends its result in a later request using the original tool call ID.
+
+Enable async calling on a function tool with `providerOptions.openai.async`:
+
+```ts
+import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-6-astra'),
+  tools: {
+    getWeather: tool({
+      description: 'Get the weather for a city.',
+      inputSchema: z.object({ city: z.string() }),
+      outputSchema: z.object({
+        city: z.string(),
+        temperatureC: z.number(),
+      }),
+      providerOptions: {
+        openai: { async: true } satisfies OpenAIToolOptions,
+      },
+    }),
+  },
+  prompt:
+    'Start the weather lookup for Paris, then list three general packing essentials without waiting.',
+});
+```
+
+The generated tool call exposes the provider marker as
+`providerMetadata.openai.async`. Use `providerMetadata.openai.responseId` as the
+next request's `previousResponseId`, and submit the result in a tool message with
+the original `toolCallId`.
+
+With `streamText`, OpenAI can continue streaming text after the completed
+`tool-call` part. Use the tool's `onInputAvailable` callback to start work as soon
+as that part arrives. If `execute` returns the same already-running promise, tool
+execution overlaps the rest of the model stream. Omit `execute` when the job
+should outlive the current generation and submit its result in a later request.
+
+Async calling applies to directly called function and custom tools. It does not
+apply to hosted tools.
+
 #### Web Search Tool
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.
@@ -670,6 +785,16 @@ for await (const part of result.fullStream) {
   setting `store: false`.
 </Note>
 
+To use `xhigh` or `max` quality, select `gpt-image-2.5-flare` or
+`gpt-image-2.5-sunburst` as the image generation tool's model:
+
+```ts
+openai.tools.imageGeneration({
+  model: 'gpt-image-2.5-flare',
+  quality: 'xhigh',
+});
+```
+
 For complete details on model availability, image quality controls, supported sizes, and tool-specific parameters,
 refer to the OpenAI documentation:
 
@@ -2599,6 +2724,19 @@ const { image, providerMetadata } = await generateImage({
 });
 ```
 
+The `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` models also support
+`quality: 'xhigh'` and `quality: 'max'` for both image generation and editing:
+
+```ts
+const { image } = await generateImage({
+  model: openai.image('gpt-image-2.5-sunburst'),
+  prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
+  providerOptions: {
+    openai: { quality: 'max' } satisfies OpenAIImageModelGenerationOptions,
+  },
+});
+```
+
 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
@@ -2612,7 +2750,7 @@ is available:
   - `revisedPrompt` _string_ - The revised prompt that was actually used to generate the image (OpenAI may modify your prompt for safety or clarity)
   - `created` _number_ - The Unix timestamp (in seconds) of when the image was created
   - `size` _string_ - The size of the generated image. One of `1024x1024`, `1024x1536`, or `1536x1024`
-  - `quality` _string_ - The quality of the generated image. One of `low`, `medium`, or `high`
+  - `quality` _string_ - The quality of the generated image. One of `low`, `medium`, `high`, `xhigh`, or `max`
   - `background` _string_ - The background parameter used for the image generation. Either `transparent` or `opaque`
   - `outputFormat` _string_ - The output format of the generated image. One of `png`, `webp`, or `jpeg`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.108",
+  "version": "3.0.110",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

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

@@ -97,6 +97,23 @@ export class OpenAIChatLanguageModel implements LanguageModelV3 {
     const isReasoningModel =
       openaiOptions.forceReasoning ?? modelCapabilities.isReasoningModel;
 
+    let resolvedReasoningEffort = openaiOptions.reasoningEffort;
+
+    if (
+      resolvedReasoningEffort != null &&
+      modelCapabilities.supportedReasoningEfforts != null &&
+      !modelCapabilities.supportedReasoningEfforts.includes(
+        resolvedReasoningEffort,
+      )
+    ) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'reasoningEffort',
+        details: `${this.modelId} only supports the following reasoning efforts: ${modelCapabilities.supportedReasoningEfforts.join(', ')}`,
+      });
+      resolvedReasoningEffort = undefined;
+    }
+
     if (topK != null) {
       warnings.push({ type: 'unsupported', feature: 'topK' });
     }
@@ -168,7 +185,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV3 {
       store: openaiOptions.store,
       metadata: openaiOptions.metadata,
       prediction: openaiOptions.prediction,
-      reasoning_effort: openaiOptions.reasoningEffort,
+      reasoning_effort: resolvedReasoningEffort,
       service_tier: openaiOptions.serviceTier,
       prompt_cache_key: openaiOptions.promptCacheKey,
       prompt_cache_options: openaiOptions.promptCacheOptions,
@@ -179,6 +196,19 @@ export class OpenAIChatLanguageModel implements LanguageModelV3 {
       messages,
     };
 
+    if (
+      modelCapabilities.supportedReasoningEfforts != null &&
+      baseArgs.prompt_cache_retention != null
+    ) {
+      baseArgs.prompt_cache_retention = undefined;
+      warnings.push({
+        type: 'unsupported',
+        feature: 'promptCacheRetention',
+        details:
+          'promptCacheRetention is not supported by GPT-6 and later models; use promptCacheOptions instead',
+      });
+    }
+
     // remove unsupported settings for reasoning models
     // see https://platform.openai.com/docs/guides/reasoning#limitations
     if (isReasoningModel) {

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

@@ -108,6 +108,7 @@ export const openaiLanguageModelChatOptions = lazySchema(() =>
 
       /**
        * Reasoning effort for reasoning models. Defaults to `medium`.
+       * GPT-6 and later models support 'low' | 'medium' | 'high' | 'xhigh' | 'max'.
        */
       reasoningEffort: z
         .enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])

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

@@ -45,10 +45,11 @@ const baseImageModelOptionsObject = z.object({
   /**
    * Quality of the generated image(s).
    *
-   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `auto`.
+   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`.
+   * `xhigh` and `max` are supported by GPT Image 2.5 models.
    */
   quality: z
-    .enum(['standard', 'hd', 'low', 'medium', 'high', 'auto'])
+    .enum(['standard', 'hd', 'low', 'medium', 'high', 'xhigh', 'max', 'auto'])
     .optional(),
 
   /**

package/src/index.ts

@@ -19,9 +19,11 @@ export type { OpenAILanguageModelCompletionOptions } from './completion/openai-c
 export type { OpenAIEmbeddingModelOptions } from './embedding/openai-embedding-options';
 export type { OpenAISpeechModelOptions } from './speech/openai-speech-options';
 export type { OpenAITranscriptionModelOptions } from './transcription/openai-transcription-options';
+export type { OpenAIToolOptions } from './responses/openai-responses-prepare-tools';
 export type {
   OpenaiResponsesProviderMetadata,
   OpenaiResponsesReasoningProviderMetadata,
+  OpenaiResponsesToolCallProviderMetadata,
   OpenaiResponsesTextProviderMetadata,
   OpenaiResponsesSourceDocumentProviderMetadata,
 } from './responses/openai-responses-provider-metadata';

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

@@ -3,6 +3,9 @@ export type OpenAILanguageModelCapabilities = {
   systemMessageMode: 'remove' | 'system' | 'developer';
   supportsFlexProcessing: boolean;
   supportsPriorityProcessing: boolean;
+  supportsConfigurationUpdate: boolean;
+  supportsAsyncToolCalling: boolean;
+  supportedReasoningEfforts: readonly string[] | undefined;
 
   /**
    * Allow temperature, topP, logProbs when reasoningEffort is none.
@@ -19,6 +22,7 @@ export function getOpenAILanguageModelCapabilities(
     gptVersion?.minor == null &&
     (gptVersion?.variant?.startsWith('chat') ?? false);
   const isGptNanoModel = gptVersion?.variant?.startsWith('nano') ?? false;
+  const isGpt6OrLaterModel = gptVersion != null && gptVersion.major >= 6;
 
   const supportsFlexProcessing =
     (oSeriesVersion != null && oSeriesVersion >= 3) ||
@@ -41,6 +45,7 @@ export function getOpenAILanguageModelCapabilities(
   // https://platform.openai.com/docs/guides/latest-model#gpt-5-1-parameter-compatibility
   // GPT-5.1 and later model families support temperature, topP, logProbs when reasoningEffort is none.
   const supportsNonReasoningParameters =
+    !isGpt6OrLaterModel &&
     gptVersion != null &&
     (gptVersion.major > 5 ||
       (gptVersion.major === 5 && (gptVersion.minor ?? 0) >= 1));
@@ -50,6 +55,11 @@ export function getOpenAILanguageModelCapabilities(
   return {
     supportsFlexProcessing,
     supportsPriorityProcessing,
+    supportsConfigurationUpdate: isGpt6OrLaterModel,
+    supportsAsyncToolCalling: isGpt6OrLaterModel,
+    supportedReasoningEfforts: isGpt6OrLaterModel
+      ? ['low', 'medium', 'high', 'xhigh', 'max']
+      : undefined,
     isReasoningModel,
     systemMessageMode,
     supportsNonReasoningParameters,

package/src/openai-tools.ts

@@ -27,6 +27,7 @@ export const openaiTools = {
    *
    * @param name - The name of the custom tool.
    * @param description - An optional description of the tool.
+   * @param async - Whether the model can continue without waiting for the tool result.
    * @param format - The output format constraint (grammar type, syntax, and definition).
    */
   customTool,
@@ -65,7 +66,7 @@ export const openaiTools = {
    * @param outputCompression - Compression level for the output image (0-100).
    * @param outputFormat - The output format of the generated image. One of 'png', 'jpeg', or 'webp'.
    * @param partialImages - Number of partial images to generate in streaming mode (0-3).
-   * @param quality - The quality of the generated image. One of 'auto', 'low', 'medium', or 'high'.
+   * @param quality - The quality of the generated image. One of 'auto', 'low', 'medium', 'high', 'xhigh', or 'max'. 'xhigh' and 'max' require a GPT Image 2.5 model.
    * @param size - The size of the generated image. One of 'auto', '1024x1024', '1024x1536', or '1536x1024'.
    */
   imageGeneration,

package/src/responses/convert-to-openai-responses-input.ts

@@ -589,6 +589,18 @@ export async function convertToOpenAIResponsesInput({
                 | string
                 | undefined;
 
+              const isAsync = (part.providerOptions?.[providerOptionsName]
+                ?.async ??
+                (
+                  part as {
+                    providerMetadata?: {
+                      [providerOptionsName]?: { async?: boolean };
+                    };
+                  }
+                ).providerMetadata?.[providerOptionsName]?.async) as
+                | boolean
+                | undefined;
+
               if (hasConversation && id != null) {
                 break;
               }
@@ -739,6 +751,7 @@ export async function convertToOpenAIResponsesInput({
                     typeof part.input === 'string'
                       ? part.input
                       : JSON.stringify(part.input),
+                  ...(isAsync != null && { async: isAsync }),
                   id,
                 });
                 break;
@@ -749,6 +762,7 @@ export async function convertToOpenAIResponsesInput({
                 call_id: part.toolCallId,
                 name: resolvedToolName,
                 arguments: serializeToolCallArguments(part.input),
+                ...(isAsync != null && { async: isAsync }),
                 ...(namespace != null && { namespace }),
               });
               break;

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

@@ -87,7 +87,8 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesToolSearchCall
   | OpenAIResponsesToolSearchOutput
   | OpenAIResponsesReasoning
-  | OpenAIResponsesItemReference;
+  | OpenAIResponsesItemReference
+  | OpenAIResponsesConfigurationUpdate;
 
 export type OpenAIResponsesIncludeValue =
   | 'web_search_call.action.sources'
@@ -179,6 +180,7 @@ export type OpenAIResponsesFunctionCall = {
   call_id: string;
   name: string;
   arguments: string;
+  async?: boolean;
   id?: string;
   namespace?: string;
 };
@@ -219,6 +221,7 @@ export type OpenAIResponsesCustomToolCall = {
   call_id: string;
   name: string;
   input: string;
+  async?: boolean;
 };
 
 export type OpenAIResponsesCustomToolCallOutput = {
@@ -372,6 +375,7 @@ export type OpenAIResponsesFunctionTool = {
   name: string;
   description: string | undefined;
   parameters: JSONSchema7;
+  async?: boolean;
   strict?: boolean;
   defer_loading?: boolean;
 };
@@ -466,7 +470,7 @@ export type OpenAIResponsesTool =
       output_compression: number | undefined;
       output_format: 'png' | 'jpeg' | 'webp' | undefined;
       partial_images: number | undefined;
-      quality: 'auto' | 'low' | 'medium' | 'high' | undefined;
+      quality: 'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | undefined;
       size: 'auto' | '1024x1024' | '1024x1536' | '1536x1024' | undefined;
     }
 
@@ -500,6 +504,7 @@ export type OpenAIResponsesTool =
       type: 'custom';
       name: string;
       description?: string;
+      async?: boolean;
       format?:
         | {
             type: 'grammar';
@@ -579,6 +584,13 @@ export type OpenAIResponsesReasoning = {
   }>;
 };
 
+export type OpenAIResponsesConfigurationUpdate = {
+  type: 'configuration_update';
+  reasoning: {
+    effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  };
+};
+
 // Captured from the Responses API when OpenAI returned an early
 // insufficient_quota stream error after HTTP 200. This shape differs from the
 // currently documented ResponseErrorEvent below.
@@ -764,6 +776,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
+            async: z.boolean().nullish(),
             namespace: z.string().nullish(),
           }),
           z.object({
@@ -842,6 +855,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             input: z.string(),
+            async: z.boolean().nullish(),
           }),
           z.object({
             type: z.literal('shell_call'),
@@ -909,6 +923,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
+            async: z.boolean().nullish(),
             status: z.literal('completed'),
             namespace: z.string().nullish(),
           }),
@@ -918,6 +933,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             input: z.string(),
+            async: z.boolean().nullish(),
             status: z.literal('completed'),
           }),
           z.object({
@@ -1402,6 +1418,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               name: z.string(),
               arguments: z.string(),
               id: z.string(),
+              async: z.boolean().nullish(),
               namespace: z.string().nullish(),
             }),
             z.object({
@@ -1410,6 +1427,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               name: z.string(),
               input: z.string(),
               id: z.string(),
+              async: z.boolean().nullish(),
             }),
             z.object({
               type: z.literal('computer_call'),