ai/docs/07-reference/01-ai-sdk-core/14-upload-file.mdx

AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.

---
title: uploadFile
description: API Reference for uploadFile.
---

# `uploadFile()`

Uploads a file to a provider and returns a `ProviderReference` that can be used in
subsequent API calls, such as in message content parts passed to `generateText` or
`streamText`.

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

## Import

<Snippet text={`import { uploadFile } from "ai"`} prompt={false} />

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'api',
      type: 'FilesV4 | ProviderV4',
      description:
        'The files API interface to use for uploading. Can be a `FilesV4` instance (e.g. `openai.files()`) or a provider instance directly (e.g. `openai`), in which case `.files()` is called automatically.',
    },
    {
      name: 'data',
      type: 'DataContent',
      description:
        'The file data to upload. Can be a `Uint8Array`, a base64-encoded string, an `ArrayBuffer`, or a `Buffer`. URLs are not supported — fetch the content first and pass the bytes.',
    },
    {
      name: 'mediaType',
      type: 'string',
      isOptional: true,
      description:
        'IANA media type of the file (e.g. `image/png`, `application/pdf`). Auto-detected from the file bytes if not provided.',
    },
    {
      name: 'filename',
      type: 'string',
      isOptional: true,
      description: 'Filename for the uploaded file.',
    },
    {
      name: 'providerOptions',
      type: 'ProviderOptions',
      isOptional: true,
      description:
        'Additional provider-specific options. For example, OpenAI requires a `purpose` field.',
    },
  ]}
/>

### Returns

<PropertiesTable
  content={[
    {
      name: 'providerReference',
      type: 'ProviderReference',
      description:
        'A `Record<string, string>` mapping provider names to provider-specific file identifiers. Pass this as the `data` or `image` field in message content parts.',
    },
    {
      name: 'providerMetadata',
      type: 'ProviderMetadata',
      isOptional: true,
      description:
        'Additional provider-specific metadata returned from the upload.',
    },
    {
      name: 'warnings',
      type: 'Warning[]',
      description: 'Warnings from the provider (e.g. unsupported settings).',
    },
  ]}
/>