Files and uploads

Purpose and Scope

Files are the SDK surface for moving user data, training data, batch inputs, and tool knowledge into OpenAI-managed storage. In openai-node, the Files resource wraps the REST /files endpoints and turns file creation into a multipart request so callers can pass SDK-supported upload values rather than manually constructing form-data payloads. The same file IDs then appear in higher-level workflows such as Assistants, fine-tuning, Batch API jobs, vector-store ingestion, file search, and Responses API input_file items. Sources: src/resources/files.ts, tests/api-resources/files.test.ts

Use this page when you need to choose between uploading a reusable file, sending a file directly as model input, or staging a larger upload through the uploads resource family. The official platform guidance treats file IDs as reusable handles: a file can be uploaded once through the Files API and then referenced by model or tool APIs, while file search uses vector stores as the knowledge-base layer over previously uploaded files. GPT Actions can also receive file references through an openaiFileIdRefs parameter, where each object includes metadata such as name, stable file ID, MIME type, and a short-lived download link.

Relevant Source Files

• api.md - Generated SDK API reference surface for the OpenAI client, including file and upload resource entries.
• src/resources/files.ts - Generated Files resource implementation for create, retrieve, list, delete, content download, authentication, binary response handling, and multipart file creation.
• src/resources/uploads/index.ts - Barrel export for upload resources and upload-part types: Parts, UploadPart, PartCreateParams, Uploads, Upload, UploadCreateParams, and UploadCompleteParams.
• tests/api-resources/files.test.ts - Resource tests showing client.files.create, retrieve, list, delete, request option propagation, toFile, pagination parameters, and APIPromise response helpers.
• tests/uploads.test.ts - Upload helper tests showing supported toFile inputs, filename inference, File and Blob assignability, type-level string discouragement, and the runtime error when File is unavailable.

Core Primitives

The main primitive is client.files, an instance of the generated Files resource. Its create method accepts a body with a file-like value and a purpose, then sends a multipart POST to /files. The source describes important platform limits directly in the SDK docs: individual files can be up to 512 MB, projects can store up to 2.5 TB of files, and uploads to the endpoint are rate-limited per authenticated user. The same comments distinguish purpose-specific constraints, including .jsonl for fine-tuning and Batch inputs, and vector-store attachment limits for retrieval or file_search. Sources: src/resources/files.ts

The upload value is represented by the SDK’s Uploadable type, and callers commonly use toFile to normalize runtime values into a File object with a name and content. The resource tests create a file from Buffer.from('Example data') using await toFile(..., 'README.md'), which is the practical pattern for Node callers who already have bytes in memory. The helper tests add important runtime expectations: toFile can infer names from a Response URL, a browser or Node File, and an fs.ReadStream, and it returns existing File objects without copying them. Sources: tests/api-resources/files.test.ts, tests/uploads.test.ts

Uploads are a separate resource family from ordinary file creation. The supplied uploads index exports both Uploads and Parts, plus request and response types for creating uploads, completing uploads, and adding parts. That split is useful when a workflow needs an upload lifecycle rather than a single multipart /files request. The index file is intentionally small because this SDK is generated from the OpenAPI specification, but its exports define the public namespace readers will see when navigating generated API docs or TypeScript definitions. Sources: src/resources/uploads/index.ts, api.md

File API Workflow

A typical reusable-file workflow starts with client.files.create, stores the returned file ID, and then passes that ID to another API. For file search, the platform flow is to upload the source document to the File API and then attach it to a vector store, either one by one or through vector-store file batches for multiple files. For model input, the Responses API can accept an input_file item as base64 data, a file ID returned by /v1/files, or an external URL; choosing the file ID route is best when the same document will be reused or managed by OpenAI-hosted tools.

import fs from 'fs';
import OpenAI, { toFile } from 'openai';
 
const client = new OpenAI();
 
const file = await client.files.create({
  file: await toFile(fs.createReadStream('manual.pdf')),
  purpose: 'assistants',
});
 
console.log(file.id);

The SDK resource implementation handles transport details that application code should not duplicate. File creation calls this._client.post('/files', multipartFormRequestOptions(...)), which means the request body is converted into multipart form data using the SDK’s upload machinery and sent with bearer authentication. Other file methods use ordinary authenticated GET or DELETE requests, except content retrieval, which sets an Accept: application/binary header and marks the response as binary so the caller receives a Response object rather than a JSON-decoded resource. Sources: src/resources/files.ts

API Components

The tests also document the promise ergonomics exposed by generated SDK methods. A file request returns an APIPromise, so callers can await it for parsed data, call .asResponse() to inspect the raw Response, or call .withResponse() to receive both parsed data and the raw response object. The file resource tests exercise that pattern for create, retrieve, list, and delete. They also verify request option propagation by passing a custom path override to client.files.list and expecting an SDK NotFoundError. Sources: tests/api-resources/files.test.ts

Multipart Inputs and Runtime Constraints

The most common pitfall is passing a plain string where the SDK expects file contents. The upload helper tests intentionally reject unsupported object shapes with a descriptive error, and they include a type-level check showing that strings are not supported as file uploads to discourage confusing a filesystem path with file contents. In the test, a string can still be forced through with a TypeScript error comment, but the documented intent is clear: pass bytes, a stream, a Blob, a File, or a response-like object, and provide or infer a filename. Sources: tests/uploads.test.ts

Runtime support depends on the JavaScript File abstraction being available through the environment or the SDK’s Node compatibility path. The missing-File test resets modules, removes both globalThis.File and node:buffer.File, imports the upload helpers, and verifies that toFile throws: ``File is not defined as a global, which is required for file uploads. This is a useful deployment signal for unusual runtimes, test sandboxes, or bundler setups that remove standard web file primitives. Sources: tests/uploads.test.ts

How Files Fit With Tools and File Inputs

Files are not only storage records; they are integration handles. File search uses uploaded files as the raw material for vector stores, and the hosted tool then retrieves relevant content automatically when a model decides to use it. Direct file inputs are different: they send a document into a model request as an input_file item. The platform docs distinguish behavior by file type: PDFs can contribute text and page images on vision-capable models, non-PDF documents and text files contribute extracted text, and spreadsheets use a spreadsheet-specific augmentation flow.

For GPT Actions, file references are passed to external APIs rather than uploaded through this SDK at request time. The platform convention is an OpenAPI parameter named openaiFileIdRefs, populated with objects that include a file name, stable ID, MIME type, and a download URL valid for a short period. That pattern differs from client.files.create: the SDK uploads bytes to OpenAI, while Actions receive references from a conversation so an external service can fetch user-uploaded, generated, or Code Interpreter-created files.

Testing Signals and Next Steps

Before building higher-level workflows, copy the tested shape from tests/api-resources/files.test.ts: create a client, normalize content with toFile, pass a specific purpose, and await the returned SDK promise. Add expires_after when your workflow should constrain file lifetime; the resource test covers { anchor: 'created_at', seconds: 3600 } as an optional create parameter. Use list filters such as purpose, order, limit, and after when building administrative or cleanup tasks around uploaded files. Sources: tests/api-resources/files.test.ts

Next, read the file-specific reference page when you need every generated parameter and response type, the vector stores page when you are building file search, and the Responses API pages when your goal is direct input_file model reasoning. If you are implementing very large or lifecycle-oriented uploads, follow the uploads namespace and part types exported from src/resources/uploads/index.ts rather than assuming every workflow should use the simple /files multipart create call. Sources: src/resources/uploads/index.ts, api.md