@ai-sdk/openai 3.0.54 → 3.0.57

package/docs/03-openai.mdx

@@ -2316,6 +2316,9 @@ const { images } = await generateImage({
 Remove the background from an image by setting `background` to `transparent`:
 
 ```ts
+import { openai, type OpenAIImageModelEditOptions } from '@ai-sdk/openai';
+import { generateImage } from 'ai';
+
 const imageBuffer = readFileSync('./input-image.png');
 
 const { images } = await generateImage({
@@ -2327,8 +2330,8 @@ const { images } = await generateImage({
   providerOptions: {
     openai: {
       background: 'transparent',
-      output_format: 'png',
-    },
+      outputFormat: 'png',
+    } satisfies OpenAIImageModelEditOptions,
   },
 });
 ```
@@ -2371,11 +2374,17 @@ const { images } = await generateImage({
 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-1` model supports the `quality` option:
 
 ```ts
+import {
+  openai,
+  type OpenAIImageModelGenerationOptions,
+} from '@ai-sdk/openai';
+import { generateImage } from 'ai';
+
 const { image, providerMetadata } = await generateImage({
   model: openai.image('gpt-image-1.5'),
   prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
   providerOptions: {
-    openai: { quality: 'high' },
+    openai: { quality: 'high' } satisfies OpenAIImageModelGenerationOptions,
   },
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.54",
+  "version": "3.0.57",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -36,15 +36,15 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.9",
-    "@ai-sdk/provider-utils": "4.0.24"
+    "@ai-sdk/provider": "3.0.10",
+    "@ai-sdk/provider-utils": "4.0.26"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.4",
+    "@ai-sdk/test-server": "1.0.5",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {

package/src/chat/convert-openai-chat-usage.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { LanguageModelV3Usage } from '@ai-sdk/provider';
 
 export type OpenAIChatUsage = {
   prompt_tokens?: number | null;

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

@@ -1,9 +1,9 @@
 import {
-  SharedV3Warning,
-  LanguageModelV3Prompt,
   UnsupportedFunctionalityError,
+  type SharedV3Warning,
+  type LanguageModelV3Prompt,
 } from '@ai-sdk/provider';
-import { OpenAIChatPrompt } from './openai-chat-prompt';
+import type { OpenAIChatPrompt } from './openai-chat-prompt';
 import { convertToBase64 } from '@ai-sdk/provider-utils';
 
 function serializeToolCallArguments(input: unknown): string {

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

@@ -1,4 +1,4 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import type { LanguageModelV3FinishReason } from '@ai-sdk/provider';
 
 export function mapOpenAIFinishReason(
   finishReason: string | null | undefined,

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

@@ -1,5 +1,9 @@
-import { JSONSchema7 } from '@ai-sdk/provider';
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import type { JSONSchema7 } from '@ai-sdk/provider';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import { openaiErrorDataSchema } from '../openai-error';
 

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

@@ -1,18 +1,16 @@
 import {
   InvalidResponseDataError,
-  LanguageModelV3,
-  LanguageModelV3CallOptions,
-  LanguageModelV3Content,
-  LanguageModelV3FinishReason,
-  LanguageModelV3GenerateResult,
-  LanguageModelV3StreamPart,
-  LanguageModelV3StreamResult,
-  SharedV3ProviderMetadata,
-  SharedV3Warning,
+  type LanguageModelV3,
+  type LanguageModelV3CallOptions,
+  type LanguageModelV3Content,
+  type LanguageModelV3FinishReason,
+  type LanguageModelV3GenerateResult,
+  type LanguageModelV3StreamPart,
+  type LanguageModelV3StreamResult,
+  type SharedV3ProviderMetadata,
+  type SharedV3Warning,
 } from '@ai-sdk/provider';
 import {
-  FetchFunction,
-  ParseResult,
   combineHeaders,
   createEventSourceResponseHandler,
   createJsonResponseHandler,
@@ -20,24 +18,26 @@ import {
   isParsableJson,
   parseProviderOptions,
   postJsonToApi,
+  type FetchFunction,
+  type ParseResult,
 } from '@ai-sdk/provider-utils';
 import { openaiFailedResponseHandler } from '../openai-error';
 import { getOpenAILanguageModelCapabilities } from '../openai-language-model-capabilities';
 import {
-  OpenAIChatUsage,
   convertOpenAIChatUsage,
+  type OpenAIChatUsage,
 } from './convert-openai-chat-usage';
 import { convertToOpenAIChatMessages } from './convert-to-openai-chat-messages';
 import { getResponseMetadata } from './get-response-metadata';
 import { mapOpenAIFinishReason } from './map-openai-finish-reason';
 import {
-  OpenAIChatChunk,
   openaiChatChunkSchema,
   openaiChatResponseSchema,
+  type OpenAIChatChunk,
 } from './openai-chat-api';
 import {
-  OpenAIChatModelId,
   openaiLanguageModelChatOptions,
+  type OpenAIChatModelId,
 } from './openai-chat-options';
 import { prepareChatTools } from './openai-chat-prepare-tools';
 

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

@@ -1,4 +1,8 @@
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // https://platform.openai.com/docs/models

package/src/chat/openai-chat-prepare-tools.ts

@@ -1,9 +1,9 @@
 import {
-  LanguageModelV3CallOptions,
-  SharedV3Warning,
   UnsupportedFunctionalityError,
+  type LanguageModelV3CallOptions,
+  type SharedV3Warning,
 } from '@ai-sdk/provider';
-import {
+import type {
   OpenAIChatToolChoice,
   OpenAIChatFunctionTool,
 } from './openai-chat-api';

package/src/completion/convert-openai-completion-usage.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { LanguageModelV3Usage } from '@ai-sdk/provider';
 
 export type OpenAICompletionUsage = {
   prompt_tokens?: number | null;

package/src/completion/convert-to-openai-completion-prompt.ts

@@ -1,7 +1,7 @@
 import {
   InvalidPromptError,
-  LanguageModelV3Prompt,
   UnsupportedFunctionalityError,
+  type LanguageModelV3Prompt,
 } from '@ai-sdk/provider';
 
 export function convertToOpenAICompletionPrompt({

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

@@ -1,4 +1,4 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import type { LanguageModelV3FinishReason } from '@ai-sdk/provider';
 
 export function mapOpenAIFinishReason(
   finishReason: string | null | undefined,

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

@@ -1,6 +1,10 @@
 import { z } from 'zod/v4';
 import { openaiErrorDataSchema } from '../openai-error';
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 
 // limited version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency

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

@@ -1,4 +1,4 @@
-import {
+import type {
   LanguageModelV3,
   LanguageModelV3CallOptions,
   LanguageModelV3FinishReason,
@@ -12,27 +12,27 @@ import {
   combineHeaders,
   createEventSourceResponseHandler,
   createJsonResponseHandler,
-  FetchFunction,
   parseProviderOptions,
-  ParseResult,
   postJsonToApi,
+  type FetchFunction,
+  type ParseResult,
 } from '@ai-sdk/provider-utils';
 import { openaiFailedResponseHandler } from '../openai-error';
 import {
   convertOpenAICompletionUsage,
-  OpenAICompletionUsage,
+  type OpenAICompletionUsage,
 } from './convert-openai-completion-usage';
 import { convertToOpenAICompletionPrompt } from './convert-to-openai-completion-prompt';
 import { getResponseMetadata } from './get-response-metadata';
 import { mapOpenAIFinishReason } from './map-openai-finish-reason';
 import {
-  OpenAICompletionChunk,
   openaiCompletionChunkSchema,
   openaiCompletionResponseSchema,
+  type OpenAICompletionChunk,
 } from './openai-completion-api';
 import {
-  OpenAICompletionModelId,
   openaiLanguageModelCompletionOptions,
+  type OpenAICompletionModelId,
 } from './openai-completion-options';
 
 type OpenAICompletionConfig = {

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

@@ -1,4 +1,8 @@
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // https://platform.openai.com/docs/models

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

@@ -1,6 +1,6 @@
 import {
-  EmbeddingModelV3,
   TooManyEmbeddingValuesForCallError,
+  type EmbeddingModelV3,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -8,11 +8,11 @@ import {
   parseProviderOptions,
   postJsonToApi,
 } from '@ai-sdk/provider-utils';
-import { OpenAIConfig } from '../openai-config';
+import type { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
 import {
-  OpenAIEmbeddingModelId,
   openaiEmbeddingModelOptions,
+  type OpenAIEmbeddingModelId,
 } from './openai-embedding-options';
 import { openaiTextEmbeddingResponseSchema } from './openai-embedding-api';
 

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

@@ -1,4 +1,8 @@
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 export type OpenAIEmbeddingModelId =

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

@@ -0,0 +1,123 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export type OpenAIImageModelId =
+  | 'dall-e-3'
+  | 'dall-e-2'
+  | 'gpt-image-1'
+  | 'gpt-image-1-mini'
+  | 'gpt-image-1.5'
+  | 'gpt-image-2'
+  | 'chatgpt-image-latest'
+  | (string & {});
+
+// https://platform.openai.com/docs/guides/images
+export const modelMaxImagesPerCall: Record<OpenAIImageModelId, number> = {
+  'dall-e-3': 1,
+  'dall-e-2': 10,
+  'gpt-image-1': 10,
+  'gpt-image-1-mini': 10,
+  'gpt-image-1.5': 10,
+  'gpt-image-2': 10,
+  'chatgpt-image-latest': 10,
+};
+
+const defaultResponseFormatPrefixes = [
+  'chatgpt-image-',
+  'gpt-image-1-mini',
+  'gpt-image-1.5',
+  'gpt-image-1',
+  'gpt-image-2',
+];
+
+export function hasDefaultResponseFormat(modelId: string): boolean {
+  return defaultResponseFormatPrefixes.some(prefix =>
+    modelId.startsWith(prefix),
+  );
+}
+
+const baseImageModelOptionsObject = z.object({
+  /**
+   * Quality of the generated image(s).
+   *
+   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `auto`.
+   */
+  quality: z
+    .enum(['standard', 'hd', 'low', 'medium', 'high', 'auto'])
+    .optional(),
+
+  /**
+   * Background behavior for the generated image(s).
+   *
+   * If `transparent`, the output format must support transparency
+   * (i.e. `png` or `webp`).
+   */
+  background: z.enum(['transparent', 'opaque', 'auto']).optional(),
+
+  /**
+   * Format in which the generated image(s) are returned.
+   */
+  outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
+
+  /**
+   * Compression level (0-100) for the generated image(s). Applies to the
+   * `jpeg` and `webp` output formats.
+   */
+  outputCompression: z.number().int().min(0).max(100).optional(),
+
+  /**
+   * A unique identifier representing your end-user, which can help OpenAI
+   * to monitor and detect abuse.
+   */
+  user: z.string().optional(),
+});
+
+export const openaiImageModelOptions = lazySchema(() =>
+  zodSchema(baseImageModelOptionsObject),
+);
+
+export type OpenAIImageModelOptions = InferSchema<
+  typeof openaiImageModelOptions
+>;
+
+export const openaiImageModelGenerationOptions = lazySchema(() =>
+  zodSchema(
+    baseImageModelOptionsObject.extend({
+      /**
+       * Style of the generated image. `vivid` produces hyper-real and
+       * dramatic images; `natural` produces more subdued, less hyper-real
+       * looking images.
+       */
+      style: z.enum(['vivid', 'natural']).optional(),
+
+      /**
+       * Content moderation level for the generated image(s). `low` applies
+       * less restrictive filtering.
+       */
+      moderation: z.enum(['auto', 'low']).optional(),
+    }),
+  ),
+);
+
+export type OpenAIImageModelGenerationOptions = InferSchema<
+  typeof openaiImageModelGenerationOptions
+>;
+
+export const openaiImageModelEditOptions = lazySchema(() =>
+  zodSchema(
+    baseImageModelOptionsObject.extend({
+      /**
+       * Fidelity of the output image(s) to the input image(s).
+       */
+      inputFidelity: z.enum(['high', 'low']).optional(),
+    }),
+  ),
+);
+
+export type OpenAIImageModelEditOptions = InferSchema<
+  typeof openaiImageModelEditOptions
+>;

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

@@ -1,4 +1,4 @@
-import {
+import type {
   ImageModelV3,
   ImageModelV3File,
   SharedV3Warning,
@@ -9,17 +9,21 @@ import {
   convertToFormData,
   createJsonResponseHandler,
   downloadBlob,
+  parseProviderOptions,
   postFormDataToApi,
   postJsonToApi,
 } from '@ai-sdk/provider-utils';
-import { OpenAIConfig } from '../openai-config';
+import type { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
 import { openaiImageResponseSchema } from './openai-image-api';
 import {
-  OpenAIImageModelId,
   hasDefaultResponseFormat,
   modelMaxImagesPerCall,
-} from './openai-image-options';
+  openaiImageModelEditOptions,
+  openaiImageModelGenerationOptions,
+  type OpenAIImageModelEditOptions,
+  type OpenAIImageModelId,
+} from './openai-image-model-options';
 
 interface OpenAIImageModelConfig extends OpenAIConfig {
   _internal?: {
@@ -75,6 +79,13 @@ export class OpenAIImageModel implements ImageModelV3 {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
 
     if (files != null) {
+      const openaiOptions =
+        (await parseProviderOptions({
+          provider: 'openai',
+          providerOptions,
+          schema: openaiImageModelEditOptions,
+        })) ?? {};
+
       const { value: response, responseHeaders } = await postFormDataToApi({
         url: this.config.url({
           path: '/images/edits',
@@ -105,7 +116,12 @@ export class OpenAIImageModel implements ImageModelV3 {
           mask: mask != null ? await fileToBlob(mask) : undefined,
           n,
           size,
-          ...(providerOptions.openai ?? {}),
+          quality: openaiOptions.quality,
+          background: openaiOptions.background,
+          output_format: openaiOptions.outputFormat,
+          output_compression: openaiOptions.outputCompression,
+          input_fidelity: openaiOptions.inputFidelity,
+          user: openaiOptions.user,
         }),
         failedResponseHandler: openaiFailedResponseHandler,
         successfulResponseHandler: createJsonResponseHandler(
@@ -153,6 +169,13 @@ export class OpenAIImageModel implements ImageModelV3 {
       };
     }
 
+    const openaiOptions =
+      (await parseProviderOptions({
+        provider: 'openai',
+        providerOptions,
+        schema: openaiImageModelGenerationOptions,
+      })) ?? {};
+
     const { value: response, responseHeaders } = await postJsonToApi({
       url: this.config.url({
         path: '/images/generations',
@@ -164,7 +187,13 @@ export class OpenAIImageModel implements ImageModelV3 {
         prompt,
         n,
         size,
-        ...(providerOptions.openai ?? {}),
+        quality: openaiOptions.quality,
+        style: openaiOptions.style,
+        background: openaiOptions.background,
+        moderation: openaiOptions.moderation,
+        output_format: openaiOptions.outputFormat,
+        output_compression: openaiOptions.outputCompression,
+        user: openaiOptions.user,
         ...(!hasDefaultResponseFormat(this.modelId)
           ? { response_format: 'b64_json' }
           : {}),
@@ -251,84 +280,18 @@ function distributeTokenDetails(
 }
 
 type OpenAIImageEditInput = {
-  /**
-   * Allows to set transparency for the background of the generated image(s).
-   * This parameter is only supported for `gpt-image-1`. Must be one of
-   * `transparent`, `opaque` or `auto` (default value). When `auto` is used, the
-   * model will automatically determine the best background for the image.
-   *
-   * If `transparent`, the output format needs to support transparency, so it
-   * should be set to either `png` (default value) or `webp`.
-   *
-   */
-  background?: 'transparent' | 'opaque' | 'auto';
-  /**
-   * The image(s) to edit. Must be a supported image file or an array of images.
-   *
-   * For `gpt-image-1`, each image should be a `png`, `webp`, or `jpg` file less
-   * than 50MB. You can provide up to 16 images.
-   *
-   * For `dall-e-2`, you can only provide one image, and it should be a square
-   * `png` file less than 4MB.
-   *
-   */
+  model: OpenAIImageModelId;
+  prompt?: string;
   image: Blob | Blob[];
-  input_fidelity?: ('high' | 'low') | null;
-  /**
-   * An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`.
-   */
   mask?: Blob;
-  /**
-   * The model to use for image generation. Only `dall-e-2` and `gpt-image-1` are supported. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used.
-   */
-  model?: 'dall-e-2' | 'gpt-image-1' | 'gpt-image-1-mini' | (string & {});
-  /**
-   * The number of images to generate. Must be between 1 and 10.
-   */
   n?: number;
-  /**
-   * The compression level (0-100%) for the generated images. This parameter
-   * is only supported for `gpt-image-1` with the `webp` or `jpeg` output
-   * formats, and defaults to 100.
-   *
-   */
-  output_compression?: number;
-  /**
-   * The format in which the generated images are returned. This parameter is
-   * only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`.
-   * The default value is `png`.
-   *
-   */
-  output_format?: 'png' | 'jpeg' | 'webp';
-  partial_images?: number | null;
-  /**
-   * A text description of the desired image(s). The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for `gpt-image-1`.
-   */
-  prompt?: string;
-  /**
-   * The quality of the image that will be generated. `high`, `medium` and `low` are only supported for `gpt-image-1`. `dall-e-2` only supports `standard` quality. Defaults to `auto`.
-   *
-   */
-  quality?: 'standard' | 'low' | 'medium' | 'high' | 'auto';
-  /**
-   * The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter is only supported for `dall-e-2`, as `gpt-image-1` will always return base64-encoded images.
-   */
-  response_format?: 'url' | 'b64_json';
-  /**
-   * The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, and one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`.
-   */
   size?: `${number}x${number}`;
-  /**
-   * Edit the image in streaming mode. Defaults to `false`. See the
-   * [Image generation guide](https://platform.openai.com/docs/guides/image-generation) for more information.
-   *
-   */
-  stream?: boolean;
-  /**
-   * A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
-   *
-   */
-  user?: string;
+  quality?: OpenAIImageModelEditOptions['quality'];
+  background?: OpenAIImageModelEditOptions['background'];
+  output_format?: OpenAIImageModelEditOptions['outputFormat'];
+  output_compression?: OpenAIImageModelEditOptions['outputCompression'];
+  input_fidelity?: OpenAIImageModelEditOptions['inputFidelity'];
+  user?: OpenAIImageModelEditOptions['user'];
 };
 
 async function fileToBlob(

package/src/index.ts

@@ -10,6 +10,11 @@ export type {
   /** @deprecated Use `OpenAILanguageModelChatOptions` instead. */
   OpenAILanguageModelChatOptions as OpenAIChatLanguageModelOptions,
 } from './chat/openai-chat-options';
+export type {
+  OpenAIImageModelOptions,
+  OpenAIImageModelGenerationOptions,
+  OpenAIImageModelEditOptions,
+} from './image/openai-image-model-options';
 export type { OpenAILanguageModelCompletionOptions } from './completion/openai-completion-options';
 export type { OpenAIEmbeddingModelOptions } from './embedding/openai-embedding-options';
 export type { OpenAISpeechModelOptions } from './speech/openai-speech-options';

package/src/internal/index.ts

@@ -5,7 +5,7 @@ export * from '../completion/openai-completion-options';
 export * from '../embedding/openai-embedding-model';
 export * from '../embedding/openai-embedding-options';
 export * from '../image/openai-image-model';
-export * from '../image/openai-image-options';
+export * from '../image/openai-image-model-options';
 export * from '../transcription/openai-transcription-model';
 export * from '../transcription/openai-transcription-options';
 export * from '../speech/openai-speech-model';

package/src/openai-config.ts

@@ -1,4 +1,4 @@
-import { FetchFunction } from '@ai-sdk/provider-utils';
+import type { FetchFunction } from '@ai-sdk/provider-utils';
 
 export type OpenAIConfig = {
   provider: string;