Upload provider files with AI SDK

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.

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

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)

A ProviderReference is a Record<string, string> 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',
}

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.

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' },
  ],
}

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,
  },
});

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' }

These providers support files() and file uploads:

A provider without file upload support throws an UnsupportedFunctionalityError if it encounters a provider reference in a message.

• Read the uploadFile reference for the full signature and return fields.
• See Skill uploads, which use the same ProviderReference pattern for skills.
• Learn how message content parts work in Prompts.
• Check Providers and models for provider support and setup.