# Upload provider files with AI SDK **Author:** Ben Sabic --- AI SDK's `uploadFile` function uploads a file to a provider and returns a `ProviderReference` that you reuse in later API calls. Upload a large image, PDF, or document once, then reference it by ID in your messages instead of re-sending the bytes on every request. If you switch providers mid-conversation, you can merge references so the same file works across them. Anthropic, Google, OpenAI, and xAI support file uploads. ## Overview In this guide, you'll learn how to: - Upload a file with `uploadFile` and get a `ProviderReference` - Reference an uploaded file in a `generateText` or `streamText` message - Pass provider-specific upload options, such as OpenAI's `purpose` - Reuse one file across multiple providers by merging references ## Prerequisites Before you begin, make sure you have: - The `ai` package - A provider package that supports file uploads, such as `@ai-sdk/openai` or `@ai-sdk/anthropic`, with provider credentials - A file to upload (an image, PDF, text file, or other supported document) ## What is a provider reference? A `ProviderReference` is a `Record` that maps each provider's name to that provider's own file identifier, such as `{ openai: 'file-abc123' }`. When you upload a file, `uploadFile` returns one. Pass the reference in the message content, and the provider looks up its own file ID. If the reference has no entry for the provider handling the request, the SDK throws an error. The same `ProviderReference` shape identifies other provider assets, too, such as uploaded skills. `// Example ProviderReference { openai: 'file-abc123', }` ## Step 1: Upload a file Call `uploadFile` with the provider's files API and the file data. It returns a `providerReference` that points to the uploaded file. `import { uploadFile } from 'ai'; import { openai } from '@ai-sdk/openai'; import fs from 'node:fs'; const { providerReference } = await uploadFile({ api: openai.files(), data: fs.readFileSync('./photo.png'), filename: 'photo.png', });` As a shorthand, pass the provider instance directly to `api` (for example, `api: openai`) and the SDK calls `.files()` for you. The media type is auto-detected from the file bytes, so set `mediaType` explicitly only when you need to, such as `'application/pdf'` for a PDF. ## Step 2: Reference the file in a message Pass the `providerReference` in a message content part. For an image, use an `image` part, and the provider resolves the reference to its own file when it processes the request. `import { generateText } from 'ai'; import { openai } from '@ai-sdk/openai'; // providerReference comes from uploadFile const { text } = await generateText({ model: openai.responses('gpt-5.2'), messages: [{ role: 'user', content: [ { type: 'text', text: 'Describe what you see in this image.' }, { type: 'image', image: providerReference }, ], }, ], });` For a document such as a PDF, use a `file` part with the reference as `data` and the media type: `{ role: 'user', content: [ { type: 'text', text: 'Summarize this document.' }, { type: 'file', data: providerReference, mediaType: 'application/pdf' }, ], }` ## Provider-specific options Some providers accept extra upload options through `providerOptions`. OpenAI, for example, requires a `purpose` field. Each provider exports an options type you can apply with `satisfies` for type safety. `import { uploadFile } from 'ai'; import { openai, type OpenAIFilesOptions } from '@ai-sdk/openai'; import fs from 'node:fs'; const { providerReference } = await uploadFile({ api: openai.files(), data: fs.readFileSync('./photo.png'), providerOptions: { openai: { purpose: 'assistants', } satisfies OpenAIFilesOptions, }, });` ## Reuse a file across multiple providers To use one file with more than one provider, upload it to each provider and merge the references into a single `ProviderReference`. The merged reference works no matter which provider processes the request, because each provider finds its own file ID. `import { uploadFile } from 'ai'; import { openai } from '@ai-sdk/openai'; import { anthropic } from '@ai-sdk/anthropic'; import fs from 'node:fs'; const imageBytes = fs.readFileSync('./photo.png'); const openaiResult = await uploadFile({ api: openai.files(), data: imageBytes, filename: 'photo.png', }); const anthropicResult = await uploadFile({ api: anthropic.files(), data: imageBytes, filename: 'photo.png', }); const mergedReference = { ...openaiResult.providerReference, ...anthropicResult.providerReference, }; // mergedReference: { openai: 'file-abc123', anthropic: 'file-xyz789' }` ## uploadFile reference ### Parameters | Parameter | Type | Required | Description | | ----------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------- | | `api` | `FilesV4` or `ProviderV4` | Yes | The provider's files API, such as `openai.files()`, or a provider instance as shorthand | | `data` | `DataContent` | Yes | The file contents, such as a `Buffer`, `Uint8Array`, or base64 string | | `mediaType` | `string` | No | The file's media type; auto-detected from the bytes when omitted | | `filename` | `string` | No | The file name to send to the provider | | `providerOptions` | `ProviderOptions` | No | Provider-specific upload options, such as OpenAI's `purpose` | ### Returns | Field | Type | Description | | ------------------- | ------------------- | ----------------------------------------------------------------------- | | `providerReference` | `ProviderReference` | Maps provider names to their file IDs; pass it in message content parts | | `providerMetadata` | `ProviderMetadata?` | Additional provider-specific metadata, when available | | `warnings` | `Warning[]` | Warnings for unsupported options | ## Supported providers These providers support `files()` and file uploads: | Provider | Factory method | | --------- | ------------------- | | Anthropic | `anthropic.files()` | | Google | `google.files()` | | OpenAI | `openai.files()` | | xAI | `xai.files()` | A provider without file upload support throws an `UnsupportedFunctionalityError` if it encounters a provider reference in a message. ## Next steps - Read the [`uploadFile`](https://ai-sdk.dev/v7/docs/reference/ai-sdk-core/upload-file) [reference](https://ai-sdk.dev/v7/docs/reference/ai-sdk-core/upload-file) for the full signature and return fields. - See [Skill uploads](https://ai-sdk.dev/v7/docs/ai-sdk-core/skill-uploads), which use the same `ProviderReference` pattern for skills. - Learn how message content parts work in [Prompts](https://ai-sdk.dev/docs/foundations/prompts). - Check [Providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models) for provider support and setup. --- [View full KB sitemap](/kb/sitemap.md)