@ai-sdk/openai 4.0.0-beta.20 → 4.0.0-beta.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.0-beta.20",
+  "version": "4.0.0-beta.21",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.0-beta.5",
-    "@ai-sdk/provider-utils": "5.0.0-beta.9"
+    "@ai-sdk/provider": "4.0.0-beta.6",
+    "@ai-sdk/provider-utils": "5.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

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

@@ -4,7 +4,11 @@ import {
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import { OpenAIChatPrompt } from './openai-chat-prompt';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
+import {
+  convertToBase64,
+  isProviderReference,
+  resolveProviderReference,
+} from '@ai-sdk/provider-utils';
 
 export function convertToOpenAIChatMessages({
   prompt,
@@ -62,6 +66,18 @@ export function convertToOpenAIChatMessages({
                 return { type: 'text', text: part.text };
               }
               case 'file': {
+                if (isProviderReference(part.data)) {
+                  return {
+                    type: 'file',
+                    file: {
+                      file_id: resolveProviderReference({
+                        reference: part.data,
+                        provider: 'openai',
+                      }),
+                    },
+                  };
+                }
+
                 if (part.mediaType.startsWith('image/')) {
                   const mediaType =
                     part.mediaType === 'image/*'
@@ -76,7 +92,6 @@ export function convertToOpenAIChatMessages({
                           ? part.data.toString()
                           : `data:${mediaType};base64,${convertToBase64(part.data)}`,
 
-                      // OpenAI specific extension: image detail
                       detail: part.providerOptions?.openai?.imageDetail,
                     },
                   };
@@ -123,14 +138,10 @@ export function convertToOpenAIChatMessages({
 
                   return {
                     type: 'file',
-                    file:
-                      typeof part.data === 'string' &&
-                      part.data.startsWith('file-')
-                        ? { file_id: part.data }
-                        : {
-                            filename: part.filename ?? `part-${index}.pdf`,
-                            file_data: `data:application/pdf;base64,${convertToBase64(part.data)}`,
-                          },
+                    file: {
+                      filename: part.filename ?? `part-${index}.pdf`,
+                      file_data: `data:application/pdf;base64,${convertToBase64(part.data)}`,
+                    },
                   };
                 } else {
                   throw new UnsupportedFunctionalityError({

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,18 @@
+import { InferSchema, lazySchema, zodSchema } 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,102 @@
+import {
+  FilesV4,
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileResult,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  FetchFunction,
+  parseProviderOptions,
+  postFormDataToApi,
+} from '@ai-sdk/provider-utils';
+import { openaiFailedResponseHandler } from '../openai-error';
+import { openaiFilesResponseSchema } from './openai-files-api';
+import {
+  openaiFilesOptionsSchema,
+  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 =
+      data instanceof Uint8Array ? data : convertBase64ToUint8Array(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/index.ts

@@ -14,6 +14,7 @@ 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,

package/src/openai-config.ts

@@ -7,12 +7,12 @@ export type OpenAIConfig = {
   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-provider.ts

@@ -1,5 +1,6 @@
 import {
   EmbeddingModelV4,
+  FilesV4,
   ImageModelV4,
   LanguageModelV4,
   ProviderV4,
@@ -18,6 +19,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';
@@ -93,6 +95,11 @@ export interface OpenAIProvider extends ProviderV4 {
    */
   speech(modelId: OpenAISpeechModelId): SpeechModelV4;
 
+  /**
+   * Returns a FilesV4 interface for uploading files to OpenAI.
+   */
+  files(): FilesV4;
+
   /**
    * OpenAI-specific tools.
    */
@@ -216,6 +223,14 @@ export function createOpenAI(
       fetch: options.fetch,
     });
 
+  const createFiles = () =>
+    new OpenAIFiles({
+      provider: `${providerName}.files`,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
   const createLanguageModel = (modelId: OpenAIResponsesModelId) => {
     if (new.target) {
       throw new Error(
@@ -232,6 +247,7 @@ export function createOpenAI(
       url: ({ path }) => `${baseURL}${path}`,
       headers: getHeaders,
       fetch: options.fetch,
+      // Soft-deprecated. TODO: remove in v8
       fileIdPrefixes: ['file-'],
     });
   };
@@ -259,6 +275,8 @@ export function createOpenAI(
   provider.speech = createSpeechModel;
   provider.speechModel = createSpeechModel;
 
+  provider.files = createFiles;
+
   provider.tools = openaiTools;
 
   return provider as OpenAIProvider;

package/src/responses/convert-to-openai-responses-input.ts

@@ -7,8 +7,10 @@ import {
 import {
   convertToBase64,
   isNonNullable,
+  isProviderReference,
   parseJSON,
   parseProviderOptions,
+  resolveProviderReference,
   ToolNameMapping,
   validateTypes,
 } from '@ai-sdk/provider-utils';
@@ -35,8 +37,10 @@ import {
 } from '../tool/tool-search';
 
 /**
- * Check if a string is a file ID based on the given prefixes
- * Returns false if prefixes is undefined (disables file ID detection)
+ * This is soft-deprecated. Use provider references instead. Kept for backward compatibility
+ * with the `fileIdPrefixes` option.
+ *
+ * TODO: remove in v8
  */
 function isFileId(data: string, prefixes?: readonly string[]): boolean {
   if (!prefixes) return false;
@@ -60,6 +64,7 @@ export async function convertToOpenAIResponsesInput({
   toolNameMapping: ToolNameMapping;
   systemMessageMode: 'system' | 'developer' | 'remove';
   providerOptionsName: string;
+  /** @deprecated Use provider references instead. */
   fileIdPrefixes?: readonly string[];
   store: boolean;
   hasConversation?: boolean; // when true, skip assistant messages that already have item IDs
@@ -113,6 +118,28 @@ export async function convertToOpenAIResponsesInput({
                 return { type: 'input_text', text: part.text };
               }
               case 'file': {
+                if (isProviderReference(part.data)) {
+                  const fileId = resolveProviderReference({
+                    reference: part.data,
+                    provider: providerOptionsName,
+                  });
+
+                  if (part.mediaType.startsWith('image/')) {
+                    return {
+                      type: 'input_image',
+                      file_id: fileId,
+                      detail:
+                        part.providerOptions?.[providerOptionsName]
+                          ?.imageDetail,
+                    };
+                  }
+
+                  return {
+                    type: 'input_file',
+                    file_id: fileId,
+                  };
+                }
+
                 if (part.mediaType.startsWith('image/')) {
                   const mediaType =
                     part.mediaType === 'image/*'