@ai-sdk/openai 3.0.55 → 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.55",
+  "version": "3.0.57",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.10",
-    "@ai-sdk/provider-utils": "4.0.25"
+    "@ai-sdk/provider-utils": "4.0.26"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

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

@@ -9,6 +9,7 @@ import {
   convertToFormData,
   createJsonResponseHandler,
   downloadBlob,
+  parseProviderOptions,
   postFormDataToApi,
   postJsonToApi,
 } from '@ai-sdk/provider-utils';
@@ -18,8 +19,11 @@ import { openaiImageResponseSchema } from './openai-image-api';
 import {
   hasDefaultResponseFormat,
   modelMaxImagesPerCall,
+  openaiImageModelEditOptions,
+  openaiImageModelGenerationOptions,
+  type OpenAIImageModelEditOptions,
   type OpenAIImageModelId,
-} from './openai-image-options';
+} 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-provider.ts

@@ -20,7 +20,7 @@ import type { OpenAICompletionModelId } from './completion/openai-completion-opt
 import { OpenAIEmbeddingModel } from './embedding/openai-embedding-model';
 import type { OpenAIEmbeddingModelId } from './embedding/openai-embedding-options';
 import { OpenAIImageModel } from './image/openai-image-model';
-import type { OpenAIImageModelId } from './image/openai-image-options';
+import type { OpenAIImageModelId } from './image/openai-image-model-options';
 import { openaiTools } from './openai-tools';
 import { OpenAIResponsesLanguageModel } from './responses/openai-responses-language-model';
 import type { OpenAIResponsesModelId } from './responses/openai-responses-options';

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

@@ -1,34 +0,0 @@
-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),
-  );
-}