@ai-sdk/openai 4.0.0-beta.4 → 4.0.0-beta.41

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

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { LanguageModelV4Usage } from '@ai-sdk/provider';
 
 export type OpenAICompletionUsage = {
   prompt_tokens?: number | null;
@@ -8,7 +8,7 @@ export type OpenAICompletionUsage = {
 
 export function convertOpenAICompletionUsage(
   usage: OpenAICompletionUsage | undefined | null,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
   if (usage == null) {
     return {
       inputTokens: {

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

@@ -1,15 +1,14 @@
 import {
   InvalidPromptError,
-  LanguageModelV3Prompt,
   UnsupportedFunctionalityError,
+  type LanguageModelV4Prompt,
 } from '@ai-sdk/provider';
-
 export function convertToOpenAICompletionPrompt({
   prompt,
   user = 'user',
   assistant = 'assistant',
 }: {
-  prompt: LanguageModelV3Prompt;
+  prompt: LanguageModelV4Prompt;
   user?: string;
   assistant?: string;
 }): {

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

@@ -1,8 +1,8 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import type { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 export function mapOpenAIFinishReason(
   finishReason: string | null | undefined,
-): LanguageModelV3FinishReason['unified'] {
+): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'stop':
       return 'stop';

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

@@ -1,7 +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
 export const openaiCompletionResponseSchema = lazySchema(() =>

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

@@ -1,49 +1,51 @@
-import {
-  LanguageModelV3,
-  LanguageModelV3CallOptions,
-  LanguageModelV3FinishReason,
-  LanguageModelV3GenerateResult,
-  LanguageModelV3StreamPart,
-  LanguageModelV3StreamResult,
-  SharedV3ProviderMetadata,
-  SharedV3Warning,
+import type {
+  LanguageModelV4,
+  LanguageModelV4CallOptions,
+  LanguageModelV4FinishReason,
+  LanguageModelV4GenerateResult,
+  LanguageModelV4StreamPart,
+  LanguageModelV4StreamResult,
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createEventSourceResponseHandler,
   createJsonResponseHandler,
-  FetchFunction,
   parseProviderOptions,
-  ParseResult,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+  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 = {
   provider: string;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   url: (options: { modelId: string; path: string }) => string;
   fetch?: FetchFunction;
 };
 
-export class OpenAICompletionLanguageModel implements LanguageModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAICompletionLanguageModel implements LanguageModelV4 {
+  readonly specificationVersion = 'v4';
 
   readonly modelId: OpenAICompletionModelId;
 
@@ -53,6 +55,20 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
     return this.config.provider.split('.')[0].trim();
   }
 
+  static [WORKFLOW_SERIALIZE](model: OpenAICompletionLanguageModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: OpenAICompletionModelId;
+    config: OpenAICompletionConfig;
+  }) {
+    return new OpenAICompletionLanguageModel(options.modelId, options.config);
+  }
+
   constructor(
     modelId: OpenAICompletionModelId,
     config: OpenAICompletionConfig,
@@ -83,8 +99,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
     toolChoice,
     seed,
     providerOptions,
-  }: LanguageModelV3CallOptions) {
-    const warnings: SharedV3Warning[] = [];
+  }: LanguageModelV4CallOptions) {
+    const warnings: SharedV4Warning[] = [];
 
     // Parse provider options
     const openaiOptions = {
@@ -161,8 +177,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
   }
 
   async doGenerate(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3GenerateResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4GenerateResult> {
     const { args, warnings } = await this.getArgs(options);
 
     const {
@@ -174,7 +190,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
         path: '/completions',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body: args,
       failedResponseHandler: openaiFailedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(
@@ -186,7 +202,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
 
     const choice = response.choices[0];
 
-    const providerMetadata: SharedV3ProviderMetadata = { openai: {} };
+    const providerMetadata: SharedV4ProviderMetadata = { openai: {} };
 
     if (choice.logprobs != null) {
       providerMetadata.openai.logprobs = choice.logprobs;
@@ -211,8 +227,8 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
   }
 
   async doStream(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3StreamResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4StreamResult> {
     const { args, warnings } = await this.getArgs(options);
 
     const body = {
@@ -229,7 +245,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
         path: '/completions',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body,
       failedResponseHandler: openaiFailedResponseHandler,
       successfulResponseHandler: createEventSourceResponseHandler(
@@ -239,11 +255,11 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
       fetch: this.config.fetch,
     });
 
-    let finishReason: LanguageModelV3FinishReason = {
+    let finishReason: LanguageModelV4FinishReason = {
       unified: 'other',
       raw: undefined,
     };
-    const providerMetadata: SharedV3ProviderMetadata = { openai: {} };
+    const providerMetadata: SharedV4ProviderMetadata = { openai: {} };
     let usage: OpenAICompletionUsage | undefined = undefined;
     let isFirstChunk = true;
 
@@ -251,7 +267,7 @@ export class OpenAICompletionLanguageModel implements LanguageModelV3 {
       stream: response.pipeThrough(
         new TransformStream<
           ParseResult<OpenAICompletionChunk>,
-          LanguageModelV3StreamPart
+          LanguageModelV4StreamPart
         >({
           start(controller) {
             controller.enqueue({ type: 'stream-start', warnings });

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,29 +1,46 @@
 import {
-  EmbeddingModelV3,
   TooManyEmbeddingValuesForCallError,
+  type EmbeddingModelV4,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createJsonResponseHandler,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
 } 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';
 
-export class OpenAIEmbeddingModel implements EmbeddingModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAIEmbeddingModel implements EmbeddingModelV4 {
+  readonly specificationVersion = 'v4';
   readonly modelId: OpenAIEmbeddingModelId;
   readonly maxEmbeddingsPerCall = 2048;
   readonly supportsParallelCalls = true;
 
   private readonly config: OpenAIConfig;
 
+  static [WORKFLOW_SERIALIZE](model: OpenAIEmbeddingModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: OpenAIEmbeddingModelId;
+    config: OpenAIConfig;
+  }) {
+    return new OpenAIEmbeddingModel(options.modelId, options.config);
+  }
+
   get provider(): string {
     return this.config.provider;
   }
@@ -38,8 +55,8 @@ export class OpenAIEmbeddingModel implements EmbeddingModelV3 {
     headers,
     abortSignal,
     providerOptions,
-  }: Parameters<EmbeddingModelV3['doEmbed']>[0]): Promise<
-    Awaited<ReturnType<EmbeddingModelV3['doEmbed']>>
+  }: Parameters<EmbeddingModelV4['doEmbed']>[0]): Promise<
+    Awaited<ReturnType<EmbeddingModelV4['doEmbed']>>
   > {
     if (values.length > this.maxEmbeddingsPerCall) {
       throw new TooManyEmbeddingValuesForCallError({
@@ -67,7 +84,7 @@ export class OpenAIEmbeddingModel implements EmbeddingModelV3 {
         path: '/embeddings',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), headers),
+      headers: combineHeaders(this.config.headers?.(), headers),
       body: {
         model: this.modelId,
         input: values,

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/files/openai-files-api.ts

@@ -0,0 +1,17 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const openaiFilesResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      object: z.string().nullish(),
+      bytes: z.number().nullish(),
+      created_at: z.number().nullish(),
+      filename: z.string().nullish(),
+      purpose: z.string().nullish(),
+      status: z.string().nullish(),
+      expires_at: z.number().nullish(),
+    }),
+  ),
+);

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

@@ -0,0 +1,22 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const openaiFilesOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /*
+       * Required by the OpenAI API, but optional here because
+       * the SDK defaults to "assistants" — by far the most common
+       * purpose when uploading files in this context.
+       */
+      purpose: z.string().optional(),
+      expiresAfter: z.number().optional(),
+    }),
+  ),
+);
+
+export type OpenAIFilesOptions = InferSchema<typeof openaiFilesOptionsSchema>;

package/src/files/openai-files.ts

@@ -0,0 +1,100 @@
+import type {
+  FilesV4,
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileResult,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertInlineFileDataToUint8Array,
+  createJsonResponseHandler,
+  parseProviderOptions,
+  postFormDataToApi,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { openaiFailedResponseHandler } from '../openai-error';
+import { openaiFilesResponseSchema } from './openai-files-api';
+import {
+  openaiFilesOptionsSchema,
+  type OpenAIFilesOptions,
+} from './openai-files-options';
+interface OpenAIFilesConfig {
+  provider: string;
+  baseURL: string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+}
+
+export class OpenAIFiles implements FilesV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: OpenAIFilesConfig) {}
+
+  async uploadFile({
+    data,
+    mediaType,
+    filename,
+    providerOptions,
+  }: FilesV4UploadFileCallOptions): Promise<FilesV4UploadFileResult> {
+    const openaiOptions = (await parseProviderOptions({
+      provider: 'openai',
+      providerOptions,
+      schema: openaiFilesOptionsSchema,
+    })) as OpenAIFilesOptions | undefined;
+
+    const fileBytes = convertInlineFileDataToUint8Array(data);
+
+    const blob = new Blob([fileBytes], {
+      type: mediaType,
+    });
+
+    const formData = new FormData();
+    if (filename != null) {
+      formData.append('file', blob, filename);
+    } else {
+      formData.append('file', blob);
+    }
+    formData.append('purpose', openaiOptions?.purpose ?? 'assistants');
+
+    if (openaiOptions?.expiresAfter != null) {
+      formData.append('expires_after', String(openaiOptions.expiresAfter));
+    }
+
+    const { value: response } = await postFormDataToApi({
+      url: `${this.config.baseURL}/files`,
+      headers: combineHeaders(this.config.headers()),
+      formData,
+      failedResponseHandler: openaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        openaiFilesResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      warnings: [],
+      providerReference: { openai: response.id },
+      ...((response.filename ?? filename)
+        ? { filename: response.filename ?? filename }
+        : {}),
+      ...(mediaType != null ? { mediaType } : {}),
+      providerMetadata: {
+        openai: {
+          ...(response.filename != null ? { filename: response.filename } : {}),
+          ...(response.purpose != null ? { purpose: response.purpose } : {}),
+          ...(response.bytes != null ? { bytes: response.bytes } : {}),
+          ...(response.created_at != null
+            ? { createdAt: response.created_at }
+            : {}),
+          ...(response.status != null ? { status: response.status } : {}),
+          ...(response.expires_at != null
+            ? { expiresAt: response.expires_at }
+            : {}),
+        },
+      },
+    };
+  }
+}

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

@@ -1,7 +1,7 @@
-import {
-  ImageModelV3,
-  ImageModelV3File,
-  SharedV3Warning,
+import type {
+  ImageModelV4,
+  ImageModelV4File,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -11,24 +11,40 @@ import {
   downloadBlob,
   postFormDataToApi,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
 } 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,
+  type OpenAIImageModelId,
 } from './openai-image-options';
-
 interface OpenAIImageModelConfig extends OpenAIConfig {
   _internal?: {
     currentDate?: () => Date;
   };
 }
 
-export class OpenAIImageModel implements ImageModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAIImageModel implements ImageModelV4 {
+  readonly specificationVersion = 'v4';
+
+  static [WORKFLOW_SERIALIZE](model: OpenAIImageModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: OpenAIImageModelId;
+    config: OpenAIImageModelConfig;
+  }) {
+    return new OpenAIImageModel(options.modelId, options.config);
+  }
 
   get maxImagesPerCall(): number {
     return modelMaxImagesPerCall[this.modelId] ?? 1;
@@ -54,10 +70,10 @@ export class OpenAIImageModel implements ImageModelV3 {
     providerOptions,
     headers,
     abortSignal,
-  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
-    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  }: Parameters<ImageModelV4['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV4['doGenerate']>>
   > {
-    const warnings: Array<SharedV3Warning> = [];
+    const warnings: Array<SharedV4Warning> = [];
 
     if (aspectRatio != null) {
       warnings.push({
@@ -80,7 +96,7 @@ export class OpenAIImageModel implements ImageModelV3 {
           path: '/images/edits',
           modelId: this.modelId,
         }),
-        headers: combineHeaders(this.config.headers(), headers),
+        headers: combineHeaders(this.config.headers?.(), headers),
         formData: convertToFormData<OpenAIImageEditInput>({
           model: this.modelId,
           prompt,
@@ -158,7 +174,7 @@ export class OpenAIImageModel implements ImageModelV3 {
         path: '/images/generations',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), headers),
+      headers: combineHeaders(this.config.headers?.(), headers),
       body: {
         model: this.modelId,
         prompt,
@@ -332,7 +348,7 @@ type OpenAIImageEditInput = {
 };
 
 async function fileToBlob(
-  file: ImageModelV3File | undefined,
+  file: ImageModelV4File | undefined,
 ): Promise<Blob | undefined> {
   if (!file) return undefined;
 

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

@@ -4,6 +4,7 @@ export type OpenAIImageModelId =
   | 'gpt-image-1'
   | 'gpt-image-1-mini'
   | 'gpt-image-1.5'
+  | 'gpt-image-2'
   | 'chatgpt-image-latest'
   | (string & {});
 
@@ -14,6 +15,7 @@ export const modelMaxImagesPerCall: Record<OpenAIImageModelId, number> = {
   'gpt-image-1': 10,
   'gpt-image-1-mini': 10,
   'gpt-image-1.5': 10,
+  'gpt-image-2': 10,
   'chatgpt-image-latest': 10,
 };
 
@@ -22,6 +24,7 @@ const defaultResponseFormatPrefixes = [
   'gpt-image-1-mini',
   'gpt-image-1.5',
   'gpt-image-1',
+  'gpt-image-2',
 ];
 
 export function hasDefaultResponseFormat(modelId: string): boolean {

package/src/index.ts

@@ -14,7 +14,9 @@ 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 { OpenAIFilesOptions } from './files/openai-files-options';
 export type {
+  OpenaiResponsesCompactionProviderMetadata,
   OpenaiResponsesProviderMetadata,
   OpenaiResponsesReasoningProviderMetadata,
   OpenaiResponsesTextProviderMetadata,

package/src/openai-config.ts

@@ -1,18 +1,18 @@
-import { FetchFunction } from '@ai-sdk/provider-utils';
+import type { FetchFunction } from '@ai-sdk/provider-utils';
 
 export type OpenAIConfig = {
   provider: string;
   url: (options: { modelId: string; path: string }) => string;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   fetch?: FetchFunction;
   generateId?: () => string;
   /**
-   * File ID prefixes used to identify file IDs in Responses API.
-   * When undefined, all file data is treated as base64 content.
+   * 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
+   * in Responses API. When undefined, all string file data is treated as
+   * base64 content.
    *
-   * Examples:
-   * - OpenAI: ['file-'] for IDs like 'file-abc123'
-   * - Azure OpenAI: ['assistant-'] for IDs like 'assistant-abc123'
+   * TODO: remove in v8
    */
   fileIdPrefixes?: readonly string[];
 };

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

@@ -20,10 +20,10 @@ export function getOpenAILanguageModelCapabilities(
 
   const supportsPriorityProcessing =
     modelId.startsWith('gpt-4') ||
-    modelId.startsWith('gpt-5-mini') ||
     (modelId.startsWith('gpt-5') &&
       !modelId.startsWith('gpt-5-nano') &&
-      !modelId.startsWith('gpt-5-chat')) ||
+      !modelId.startsWith('gpt-5-chat') &&
+      !modelId.startsWith('gpt-5.4-nano')) ||
     modelId.startsWith('o3') ||
     modelId.startsWith('o4-mini');
 
@@ -40,6 +40,7 @@ export function getOpenAILanguageModelCapabilities(
   const supportsNonReasoningParameters =
     modelId.startsWith('gpt-5.1') ||
     modelId.startsWith('gpt-5.2') ||
+    modelId.startsWith('gpt-5.3') ||
     modelId.startsWith('gpt-5.4');
 
   const systemMessageMode = isReasoningModel ? 'developer' : 'system';