@ai-sdk/openai 4.0.61 → 4.0.63

package/docs/03-openai.mdx

@@ -827,6 +827,16 @@ for await (const part of result.stream) {
   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:
 
@@ -2068,65 +2078,16 @@ The metadata includes the following fields:
 - **itemId** _string_ — The ID of the compaction item in the Responses API
 - **encryptedContent** _string_ (optional) — The encrypted compaction state. This is automatically sent back to the API when the message is included in subsequent requests.
 
-### Text Batches
+### Batch
 
 <Note type="warning">
-  Text batch support is experimental and the API may change in patch releases.
+  Batch support is experimental and the API may change in patch releases.
 </Note>
 
-The OpenAI provider supports asynchronous text generation through the
-[Batch API](https://developers.openai.com/api/docs/guides/batch). Use the
-experimental text batch APIs to start a batch, poll its status, and stream its
-results:
-
-```ts
-import { openai } from '@ai-sdk/openai';
-import {
-  experimental_getBatchResults as getBatchResults,
-  experimental_getBatchStatus as getBatchStatus,
-  experimental_startBatch as startBatch,
-} from 'ai';
-import { setTimeout } from 'node:timers/promises';
-
-const model = 'gpt-4.1-nano';
-
-const batch = await startBatch({
-  provider: openai,
-  requests: [
-    {
-      id: 'capital-france',
-      type: 'text',
-      model,
-      prompt: 'What is the capital of France?',
-    },
-    {
-      id: 'capital-germany',
-      type: 'text',
-      model,
-      prompt: 'What is the capital of Germany?',
-    },
-  ],
-});
-
-let status = batch.status;
-while (status === 'pending') {
-  await setTimeout(60_000);
-  ({ status } = await getBatchStatus({ provider: openai, batch }));
-}
-
-for await (const item of getBatchResults({ provider: openai, batch })) {
-  if (item.status === 'succeeded') {
-    console.log(item.id, item.text);
-  } else {
-    console.error(item.id, item.error);
-  }
-}
-```
-
-`startBatch` returns a serializable batch reference. Persist this reference
-to check the batch status or retrieve its results from another process. Results
-can arrive in a different order from the input requests, so match each result by
-its `id`.
+The OpenAI provider supports asynchronous text generation through the [Batch
+API](https://developers.openai.com/api/docs/guides/batch). Pass the OpenAI
+provider to the AI SDK's [Batch](/docs/ai-sdk-core/batch) API for
+the complete workflow, including polling, persistence, and result handling.
 
 Each request specifies its `type` and `model`. OpenAI requires every text
 request in a batch to use the same model and throws before submission when the
@@ -2984,7 +2945,7 @@ Transform an existing image using text prompts:
 const imageBuffer = readFileSync('./input-image.png');
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-2'),
+  model: openai.image('gpt-image-2.5-sunburst'),
   prompt: {
     text: 'Turn the cat into a dog but retain the style of the original image',
     images: [imageBuffer],
@@ -3001,7 +2962,7 @@ const image = readFileSync('./input-image.png');
 const mask = readFileSync('./mask.png'); // Transparent areas = edit regions
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-2'),
+  model: openai.image('gpt-image-2.5-sunburst'),
   prompt: {
     text: 'A sunlit indoor lounge area with a pool containing a flamingo',
     images: [image],
@@ -3046,7 +3007,7 @@ const owl = readFileSync('./owl.png');
 const bear = readFileSync('./bear.png');
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-2'),
+  model: openai.image('gpt-image-2.5-sunburst'),
   prompt: {
     text: 'Combine these animals into a group photo, retaining the original style',
     images: [cat, dog, owl, bear],
@@ -3062,14 +3023,23 @@ const { images } = await generateImage({
 
 ### Model Capabilities
 
-| Model              | Sizes                           |
-| ------------------ | ------------------------------- |
-| `gpt-image-2`      | 1024x1024, 1536x1024, 1024x1536 |
-| `gpt-image-1.5`    | 1024x1024, 1536x1024, 1024x1536 |
-| `gpt-image-1-mini` | 1024x1024, 1536x1024, 1024x1536 |
-| `gpt-image-1`      | 1024x1024, 1536x1024, 1024x1536 |
-| `dall-e-3`         | 1024x1024, 1792x1024, 1024x1792 |
-| `dall-e-2`         | 256x256, 512x512, 1024x1024     |
+| Model                    | Sizes                                  |
+| ------------------------ | -------------------------------------- |
+| `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        |
+| `gpt-image-1.5`          | 1024x1024, 1536x1024, 1024x1536        |
+| `gpt-image-1-mini`       | 1024x1024, 1536x1024, 1024x1536        |
+| `gpt-image-1`            | 1024x1024, 1536x1024, 1024x1536        |
+| `dall-e-3`               | 1024x1024, 1792x1024, 1024x1792        |
+| `dall-e-2`               | 256x256, 512x512, 1024x1024            |
+
+Use `gpt-image-2.5-flare` for fast, general-purpose image generation and
+`gpt-image-2.5-sunburst` when editing precision and instruction following are
+the priority. Both models accept custom `WIDTHxHEIGHT` sizes whose dimensions
+are multiples of 16, with aspect ratios from 1:3 through 3:1, no edge longer
+than 3840 pixels, and a total area from 655,360 through 8,294,400 pixels.
+Resolutions above 2560x1440 are experimental.
 
 You can pass optional `providerOptions` to the image model. These are prone to change by OpenAI and are model dependent. For example, the `gpt-image-*` models support the `quality` option:
 
@@ -3078,7 +3048,7 @@ import { openai, type OpenAIImageModelGenerationOptions } from '@ai-sdk/openai';
 import { generateImage } from 'ai';
 
 const { image, providerMetadata } = await generateImage({
-  model: openai.image('gpt-image-2'),
+  model: openai.image('gpt-image-2.5-flare'),
   prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
   providerOptions: {
     openai: { quality: 'high' } satisfies OpenAIImageModelGenerationOptions,
@@ -3086,6 +3056,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
@@ -3098,7 +3081,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": "4.0.61",
+  "version": "4.0.63",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

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

@@ -12,6 +12,10 @@ export type OpenAIImageModelId =
   | 'gpt-image-1-mini'
   | 'gpt-image-1.5'
   | 'gpt-image-2'
+  | 'gpt-image-2.5-flare'
+  | 'gpt-image-2.5-flare-2026-09-08'
+  | 'gpt-image-2.5-sunburst'
+  | 'gpt-image-2.5-sunburst-2026-09-08'
   | 'chatgpt-image-latest'
   | (string & {});
 
@@ -23,6 +27,10 @@ export const modelMaxImagesPerCall: Record<OpenAIImageModelId, number> = {
   'gpt-image-1-mini': 10,
   'gpt-image-1.5': 10,
   'gpt-image-2': 10,
+  'gpt-image-2.5-flare': 10,
+  'gpt-image-2.5-flare-2026-09-08': 10,
+  'gpt-image-2.5-sunburst': 10,
+  'gpt-image-2.5-sunburst-2026-09-08': 10,
   'chatgpt-image-latest': 10,
 };
 
@@ -45,10 +53,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/openai-config.ts

@@ -17,6 +17,13 @@ export type OpenAIConfig = {
   fetch?: FetchFunction;
   webSocket?: WebSocketConstructor;
   generateId?: () => string;
+  /**
+   * Whether Responses API message input items must include an explicit
+   * `type: 'message'` discriminator.
+   *
+   * @see https://github.com/vercel/ai/issues/20180
+   */
+  explicitMessageItemType?: 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-tools.ts

@@ -77,7 +77,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

@@ -341,6 +341,7 @@ export async function convertToOpenAIResponsesInput({
   toolNameMapping,
   systemMessageMode,
   providerOptionsName,
+  explicitMessageItemType = false,
   fileIdPrefixes,
   passThroughUnsupportedFiles = false,
   store,
@@ -358,6 +359,7 @@ export async function convertToOpenAIResponsesInput({
   toolNameMapping: ToolNameMapping;
   systemMessageMode: 'system' | 'developer' | 'remove';
   providerOptionsName: string;
+  explicitMessageItemType?: boolean;
   /** @deprecated Use provider references instead. */
   fileIdPrefixes?: readonly string[];
   passThroughUnsupportedFiles?: boolean;
@@ -378,6 +380,7 @@ export async function convertToOpenAIResponsesInput({
   let input: OpenAIResponsesInput = [];
   const warnings: Array<SharedV4Warning> = [];
   const processedApprovalIds = new Set<string>();
+  const programmaticToolCallIds = new Set<string>();
   const parallelToolResultGroups =
     hasConversation || hasPreviousResponseId
       ? collectCompleteParallelToolResultGroups({
@@ -398,6 +401,7 @@ export async function convertToOpenAIResponsesInput({
               providerOptionsName,
             );
             input.push({
+              ...(explicitMessageItemType && { type: 'message' as const }),
               role: 'system',
               content:
                 promptCacheBreakpoint == null
@@ -418,6 +422,7 @@ export async function convertToOpenAIResponsesInput({
               providerOptionsName,
             );
             input.push({
+              ...(explicitMessageItemType && { type: 'message' as const }),
               role: 'developer',
               content:
                 promptCacheBreakpoint == null
@@ -451,6 +456,7 @@ export async function convertToOpenAIResponsesInput({
 
       case 'user': {
         input.push({
+          ...(explicitMessageItemType && { type: 'message' as const }),
           role: 'user',
           content: content.map((part, index) => {
             switch (part.type) {
@@ -603,6 +609,7 @@ export async function convertToOpenAIResponsesInput({
               }
 
               input.push({
+                ...(explicitMessageItemType && { type: 'message' as const }),
                 role: 'assistant',
                 content: [{ type: 'output_text', text: part.text }],
                 id,
@@ -694,6 +701,10 @@ export async function convertToOpenAIResponsesInput({
                 | { type: 'program'; callerId: string }
                 | undefined;
 
+              if (caller?.type === 'program') {
+                programmaticToolCallIds.add(part.toolCallId);
+              }
+
               if (hasConversation && id != null) {
                 break;
               }
@@ -1568,6 +1579,23 @@ export async function convertToOpenAIResponsesInput({
             continue;
           }
 
+          const resultCaller = part.providerOptions?.[providerOptionsName]
+            ?.caller as
+            | { type: 'direct' }
+            | { type: 'program'; callerId: string }
+            | undefined;
+
+          if (
+            output.type === 'execution-denied' &&
+            (resultCaller?.type === 'program' ||
+              programmaticToolCallIds.has(part.toolCallId))
+          ) {
+            throw new UnsupportedFunctionalityError({
+              functionality:
+                'execution-denied results for programmatic tool calls',
+            });
+          }
+
           const contentValue = await convertFunctionToolResultOutput({
             output,
             toolName: part.toolName,
@@ -1581,12 +1609,7 @@ export async function convertToOpenAIResponsesInput({
             warnings,
           });
 
-          const caller = mapToolCaller(
-            part.providerOptions?.[providerOptionsName]?.caller as
-              | { type: 'direct' }
-              | { type: 'program'; callerId: string }
-              | undefined,
-          );
+          const caller = mapToolCaller(resultCaller);
 
           input.push({
             type: 'function_call_output',

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

@@ -214,6 +214,7 @@ export type OpenAIResponsesApplyPatchOperationDiffDoneChunk = {
 };
 
 export type OpenAIResponsesSystemMessage = {
+  type?: 'message';
   role: 'system' | 'developer';
   content:
     | string
@@ -225,6 +226,7 @@ export type OpenAIResponsesSystemMessage = {
 };
 
 export type OpenAIResponsesUserMessage = {
+  type?: 'message';
   role: 'user';
   content: Array<
     | {
@@ -262,6 +264,7 @@ export type OpenAIResponsesUserMessage = {
 };
 
 export type OpenAIResponsesAssistantMessage = {
+  type?: 'message';
   role: 'assistant';
   content: Array<{ type: 'output_text'; text: string }>;
   id?: string;
@@ -626,7 +629,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'

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

@@ -391,6 +391,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
             ? 'developer'
             : modelCapabilities.systemMessageMode),
         providerOptionsName,
+        explicitMessageItemType: config.explicitMessageItemType,
         fileIdPrefixes: config.fileIdPrefixes,
         passThroughUnsupportedFiles:
           openaiOptions?.passThroughUnsupportedFiles ?? false,
@@ -1349,6 +1350,8 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
         }
 
         case 'apply_patch_call': {
+          hasFunctionCall = true;
+
           content.push({
             type: 'tool-call',
             toolCallId: part.call_id,
@@ -2291,6 +2294,8 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
 
                 // Emit the final tool-call with complete diff when status is 'completed'
                 if (toolCall && value.item.status === 'completed') {
+                  hasFunctionCall = true;
+
                   controller.enqueue({
                     type: 'tool-call',
                     toolCallId: toolCall.toolCallId,

package/src/tool/image-generation.ts

@@ -23,7 +23,9 @@ export const imageGenerationArgsSchema = lazySchema(() =>
         outputCompression: z.number().int().min(0).max(100).optional(),
         outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
         partialImages: z.number().int().min(0).max(3).optional(),
-        quality: z.enum(['auto', 'low', 'medium', 'high']).optional(),
+        quality: z
+          .enum(['auto', 'low', 'medium', 'high', 'xhigh', 'max'])
+          .optional(),
         size: z
           .union([
             z.enum(['1024x1024', '1024x1536', '1536x1024', 'auto']),
@@ -101,14 +103,16 @@ type ImageGenerationArgs = {
 
   /**
    * The quality of the generated image.
-   * One of low, medium, high, or auto. Default: auto.
+   * One of low, medium, high, xhigh, max, or auto. Default: auto.
+   * xhigh and max are supported by GPT Image 2.5 models.
    */
-  quality?: 'auto' | 'low' | 'medium' | 'high';
+  quality?: 'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
   /**
    * The size of the generated image.
-   * One of 1024x1024, 1024x1536, 1536x1024, or auto. gpt-image-2 also accepts
-   * arbitrary WIDTHxHEIGHT sizes where both are divisible by 16, e.g. 1536x864.
+   * One of 1024x1024, 1024x1536, 1536x1024, or auto. GPT Image 2 and 2.5
+   * models also accept arbitrary WIDTHxHEIGHT sizes where both are divisible
+   * by 16, e.g. 1536x864.
    * Default: auto.
    */
   size?: 'auto' | '1024x1024' | '1024x1536' | '1536x1024' | (string & {});