uploadFile | AI SDK

Uploads a file to a provider and returns a result whose providerReference (a ProviderReference) can be used in subsequent API calls, such as in message content parts passed to generateText or streamText.

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

import { uploadFile } from "ai"

API Signature

Parameters

api:

FilesV4 | ProviderV4

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.

data:

DataContent | { type: "stream"; stream: ReadableStream<Uint8Array> }

The file data to upload. Can be a Uint8Array, a base64-encoded string, an ArrayBuffer, a Buffer, or a tagged { type: "stream", stream } shape for providers that support streaming uploads (sent without buffering; other providers reject with an UnsupportedFunctionalityError). The provider consumes the stream — any failed upload (including validation failures before a request is made) cancels it, and it must not be reused. URLs are not supported — fetch the content first and pass the bytes.

mediaType?:

string

IANA media type of the file (e.g. image/png, application/pdf). Auto-detected from the file bytes if not provided; stream data cannot be sniffed and defaults to application/octet-stream.

filename?:

string

Filename for the uploaded file. Multipart-based providers default it to "blob" when omitted.

abortSignal?:

AbortSignal

Signal to cancel the upload.

headers?:

Record<string, string>

Additional HTTP headers to send with the request.

providerOptions?:

ProviderOptions

Additional provider-specific options. For example, OpenAI accepts a purpose field, which defaults to "assistants".

Returns

providerReference:

ProviderReference

A Record<string, string> mapping provider names to provider-specific file identifiers. Pass this as the data or image field in message content parts.

byteSize?:

number

Size of the uploaded file in bytes, if reported by the provider.

createdAt?:

Date

When the file was created, if reported by the provider.

expiresAt?:

Date

When the provider will delete the file (retention expiry, e.g. from a requested upload TTL), if reported by the provider.

providerMetadata?:

ProviderMetadata

Additional provider-specific metadata returned from the upload.

warnings:

Warning[]

Warnings from the provider (e.g. unsupported settings).