Implementation:Openai Openai node Uploads Resource

Knowledge Sources	Openai_Openai_node
Domains	SDK, Uploads
Last Updated	2026-02-15 12:00 GMT

Overview

The Uploads class provides the API resource for creating, completing, and cancelling large file uploads using the multi-part upload workflow.

Description

The Uploads class extends APIResource and exposes three methods for managing the Upload lifecycle, plus a parts sub-resource for adding chunked data. The create method initializes an Upload object with metadata including filename, bytes (intended file size), mime_type, purpose, and an optional expires_after policy. Uploads can accept at most 8 GB in total and expire one hour after creation.

The complete method finalizes the Upload by providing an ordered list of Part IDs and an optional MD5 checksum for verification. Upon completion, the API creates a standard File object that can be used throughout the platform. The cancel method terminates an Upload, preventing any further Parts from being added.

The Upload interface describes the upload object with fields for id, bytes, created_at, expires_at, filename, purpose, status (pending/completed/cancelled/expired), and an optional file reference to the resulting File object after completion. The UploadCreateParams.ExpiresAfter nested interface defines the expiration policy with an anchor (always 'created_at') and seconds (between 3600 and 2592000).

Usage

Use this resource when you need to upload files larger than what the standard Files API supports in a single request. The chunked upload workflow provides resilience against network failures and enables parallel Part uploads for better throughput.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/uploads/uploads.ts

Signature

export class Uploads extends APIResource {
  parts: Parts;

  create(body: UploadCreateParams, options?: RequestOptions): APIPromise<Upload>;
  cancel(uploadID: string, options?: RequestOptions): APIPromise<Upload>;
  complete(uploadID: string, body: UploadCompleteParams, options?: RequestOptions): APIPromise<Upload>;
}

export interface Upload {
  id: string;
  bytes: number;
  created_at: number;
  expires_at: number;
  filename: string;
  object: 'upload';
  purpose: string;
  status: 'pending' | 'completed' | 'cancelled' | 'expired';
  file?: FileObject | null;
}

export interface UploadCreateParams {
  bytes: number;
  filename: string;
  mime_type: string;
  purpose: FilePurpose;
  expires_after?: UploadCreateParams.ExpiresAfter;
}

export interface UploadCompleteParams {
  part_ids: Array<string>;
  md5?: string;
}

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
body.filename	string	Yes (create)	The name of the file to upload.
body.bytes	number	Yes (create)	The total number of bytes in the file.
body.mime_type	string	Yes (create)	The MIME type of the file.
body.purpose	FilePurpose	Yes (create)	The intended purpose of the uploaded file.
body.expires_after	ExpiresAfter	No (create)	Expiration policy with anchor and seconds.
uploadID	string	Yes (complete/cancel)	The identifier of the Upload to act upon.
body.part_ids	Array<string>	Yes (complete)	Ordered list of Part IDs defining the file assembly order.
body.md5	string	No (complete)	Optional MD5 checksum for verification.
options	RequestOptions	No	Additional request configuration.

Outputs

Name	Type	Description
id	string	Unique Upload identifier.
bytes	number	The intended number of bytes.
created_at	number	Unix timestamp (seconds) when the Upload was created.
expires_at	number	Unix timestamp (seconds) when the Upload will expire.
filename	string	The name of the file being uploaded.
purpose	string	The intended purpose of the file.
status	'completed' | 'cancelled' | 'expired'	Current status of the Upload.
file	null	The resulting File object after completion (null before completion).

Usage Examples

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI();

// Step 1: Create an upload
const upload = await client.uploads.create({
  filename: 'training-data.jsonl',
  bytes: 50_000_000,
  mime_type: 'application/jsonl',
  purpose: 'fine-tune',
});

// Step 2: Add parts
const part1 = await client.uploads.parts.create(upload.id, {
  data: fs.createReadStream('part1.bin'),
});
const part2 = await client.uploads.parts.create(upload.id, {
  data: fs.createReadStream('part2.bin'),
});

// Step 3: Complete the upload
const completed = await client.uploads.complete(upload.id, {
  part_ids: [part1.id, part2.id],
});
console.log(completed.status); // 'completed'
console.log(completed.file?.id); // The resulting File ID

// Cancel an upload if needed
const cancelled = await client.uploads.cancel('upload_xyz');
console.log(cancelled.status); // 'cancelled'

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime