@ai-sdk/openai 4.0.0-beta.3 → 4.0.0-beta.31

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

@@ -1,7 +1,7 @@
 import {
-  ImageModelV3,
-  ImageModelV3File,
-  SharedV3Warning,
+  ImageModelV4,
+  ImageModelV4File,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -11,6 +11,9 @@ import {
   downloadBlob,
   postFormDataToApi,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
@@ -27,8 +30,22 @@ interface OpenAIImageModelConfig extends OpenAIConfig {
   };
 }
 
-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 +71,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 +97,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 +175,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 +349,7 @@ type OpenAIImageEditInput = {
 };
 
 async function fileToBlob(
-  file: ImageModelV3File | undefined,
+  file: ImageModelV4File | undefined,
 ): Promise<Blob | undefined> {
   if (!file) return undefined;
 

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

@@ -3,16 +3,16 @@ import { 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';

package/src/openai-provider.ts

@@ -1,10 +1,12 @@
 import {
-  EmbeddingModelV3,
-  ImageModelV3,
-  LanguageModelV3,
-  ProviderV3,
-  SpeechModelV3,
-  TranscriptionModelV3,
+  EmbeddingModelV4,
+  FilesV4,
+  ImageModelV4,
+  LanguageModelV4,
+  ProviderV4,
+  SpeechModelV4,
+  SkillsV4,
+  TranscriptionModelV4,
 } from '@ai-sdk/provider';
 import {
   FetchFunction,
@@ -18,6 +20,7 @@ import { OpenAIChatModelId } from './chat/openai-chat-options';
 import { OpenAICompletionLanguageModel } from './completion/openai-completion-language-model';
 import { OpenAICompletionModelId } from './completion/openai-completion-options';
 import { OpenAIEmbeddingModel } from './embedding/openai-embedding-model';
+import { OpenAIFiles } from './files/openai-files';
 import { OpenAIEmbeddingModelId } from './embedding/openai-embedding-options';
 import { OpenAIImageModel } from './image/openai-image-model';
 import { OpenAIImageModelId } from './image/openai-image-options';
@@ -28,70 +31,81 @@ import { OpenAISpeechModel } from './speech/openai-speech-model';
 import { OpenAISpeechModelId } from './speech/openai-speech-options';
 import { OpenAITranscriptionModel } from './transcription/openai-transcription-model';
 import { OpenAITranscriptionModelId } from './transcription/openai-transcription-options';
+import { OpenAISkills } from './skills/openai-skills';
 import { VERSION } from './version';
 
-export interface OpenAIProvider extends ProviderV3 {
-  (modelId: OpenAIResponsesModelId): LanguageModelV3;
+export interface OpenAIProvider extends ProviderV4 {
+  (modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI model for text generation.
    */
-  languageModel(modelId: OpenAIResponsesModelId): LanguageModelV3;
+  languageModel(modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI chat model for text generation.
    */
-  chat(modelId: OpenAIChatModelId): LanguageModelV3;
+  chat(modelId: OpenAIChatModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI responses API model for text generation.
    */
-  responses(modelId: OpenAIResponsesModelId): LanguageModelV3;
+  responses(modelId: OpenAIResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an OpenAI completion model for text generation.
    */
-  completion(modelId: OpenAICompletionModelId): LanguageModelV3;
+  completion(modelId: OpenAICompletionModelId): LanguageModelV4;
 
   /**
    * Creates a model for text embeddings.
    */
-  embedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  embedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for text embeddings.
    */
-  embeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  embeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * @deprecated Use `embedding` instead.
    */
-  textEmbedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  textEmbedding(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
    */
-  textEmbeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV3;
+  textEmbeddingModel(modelId: OpenAIEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for image generation.
    */
-  image(modelId: OpenAIImageModelId): ImageModelV3;
+  image(modelId: OpenAIImageModelId): ImageModelV4;
 
   /**
    * Creates a model for image generation.
    */
-  imageModel(modelId: OpenAIImageModelId): ImageModelV3;
+  imageModel(modelId: OpenAIImageModelId): ImageModelV4;
 
   /**
    * Creates a model for transcription.
    */
-  transcription(modelId: OpenAITranscriptionModelId): TranscriptionModelV3;
+  transcription(modelId: OpenAITranscriptionModelId): TranscriptionModelV4;
 
   /**
    * Creates a model for speech generation.
    */
-  speech(modelId: OpenAISpeechModelId): SpeechModelV3;
+  speech(modelId: OpenAISpeechModelId): SpeechModelV4;
+
+  /**
+   * Returns a FilesV4 interface for uploading files to OpenAI.
+   */
+  files(): FilesV4;
+
+  /**
+   * Returns a SkillsV4 interface for uploading skills to OpenAI.
+   */
+  skills(): SkillsV4;
 
   /**
    * OpenAI-specific tools.
@@ -216,6 +230,22 @@ export function createOpenAI(
       fetch: options.fetch,
     });
 
+  const createFiles = () =>
+    new OpenAIFiles({
+      provider: `${providerName}.files`,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const createSkills = () =>
+    new OpenAISkills({
+      provider: `${providerName}.skills`,
+      url: ({ path }) => `${baseURL}${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
   const createLanguageModel = (modelId: OpenAIResponsesModelId) => {
     if (new.target) {
       throw new Error(
@@ -232,6 +262,7 @@ export function createOpenAI(
       url: ({ path }) => `${baseURL}${path}`,
       headers: getHeaders,
       fetch: options.fetch,
+      // Soft-deprecated. TODO: remove in v8
       fileIdPrefixes: ['file-'],
     });
   };
@@ -240,7 +271,7 @@ export function createOpenAI(
     return createLanguageModel(modelId);
   };
 
-  provider.specificationVersion = 'v3' as const;
+  provider.specificationVersion = 'v4' as const;
   provider.languageModel = createLanguageModel;
   provider.chat = createChatModel;
   provider.completion = createCompletionModel;
@@ -258,6 +289,8 @@ export function createOpenAI(
 
   provider.speech = createSpeechModel;
   provider.speechModel = createSpeechModel;
+  provider.files = createFiles;
+  provider.skills = createSkills;
 
   provider.tools = openaiTools;
 

package/src/openai-tools.ts

@@ -5,6 +5,7 @@ import { fileSearch } from './tool/file-search';
 import { imageGeneration } from './tool/image-generation';
 import { localShell } from './tool/local-shell';
 import { shell } from './tool/shell';
+import { toolSearch } from './tool/tool-search';
 import { webSearch } from './tool/web-search';
 import { webSearchPreview } from './tool/web-search-preview';
 import { mcp } from './tool/mcp';
@@ -24,7 +25,6 @@ export const openaiTools = {
    * Lark syntax). The model returns a `custom_tool_call` output item whose
    * `input` field is a string matching the specified grammar.
    *
-   * @param name - The name of the custom tool.
    * @param description - An optional description of the tool.
    * @param format - The output format constraint (grammar type, syntax, and definition).
    */
@@ -123,4 +123,15 @@ export const openaiTools = {
    * @param serverUrl - URL for the MCP server.
    */
   mcp,
+
+  /**
+   * Tool search allows the model to dynamically search for and load deferred
+   * tools into the model's context as needed. This helps reduce overall token
+   * usage, cost, and latency by only loading tools when the model needs them.
+   *
+   * To use tool search, mark functions or namespaces with `defer_loading: true`
+   * in the tools array. The model will use tool search to load these tools
+   * when it determines they are needed.
+   */
+  toolSearch,
 };

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

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { LanguageModelV4Usage } from '@ai-sdk/provider';
 
 export type OpenAIResponsesUsage = {
   input_tokens: number;
@@ -13,7 +13,7 @@ export type OpenAIResponsesUsage = {
 
 export function convertOpenAIResponsesUsage(
   usage: OpenAIResponsesUsage | undefined | null,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
   if (usage == null) {
     return {
       inputTokens: {