OpenAI API (unofficial showcase)
POST/files

Upload a file

Uploads a file for use across supported API endpoints. Send the file and its purpose as multipart form data, and use expires_after when you want to set an expiration policy. File uploads are limited to 512 MB per file and 2.5 TB of storage per project.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields

Multipart form data containing the file, its intended purpose, and an optional expiration policy.

filestringrequired
The File object (not file name) to be uploaded.
purposestringrequired
The intended purpose of the uploaded file. One of: - `assistants`: Used in the Assistants API - `batch`: Used in the Batch API - `fine-tune`: Used for fine-tuning - `vision`: Images used for vision fine-tuning - `user_data`: Flexible file type for any purpose - `evals`: Used for eval data sets
Allowed:assistantsbatchfine-tunevisionuser_dataevals
expires_afterobjectoptional
The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.

4 status codes
200Returns the uploaded file object, including its ID, filename, purpose, size, and timestamps.
idstringrequired
The file identifier, which can be referenced in the API endpoints.
bytesintegerrequired
The size of the file, in bytes. In a completed file upload response, this can be null when the file size is not yet available.
created_atintegerrequired
The Unix timestamp (in seconds) for when the file was created.
expires_atintegeroptional
The Unix timestamp (in seconds) for when the file will expire. In a completed file upload response, this can be null when no expiry is set.
filenamestringrequired
The name of the file.
objectstringrequired
The object type, which is always `file`.
Allowed:file
purposestringrequired
The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
Allowed:assistantsassistants_outputbatchbatch_outputfine-tunefine-tune-resultsvisionuser_data
statusstringdeprecatedrequired
Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
Allowed:uploadedprocessederror
status_detailsstringdeprecatedoptional
Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. Completed file upload responses can return null when these details are unset.
400Returned when the upload request is invalid or exceeds a file-size or storage quota limit.
errorobjectrequired
429Returned when too many file requests are made; reduce the request rate and try again later.
errorobjectrequired
500Returned when a server error prevents the file from being uploaded.
errorobjectrequired

Error handling

A 400 is returned when the upload request is invalid or exceeds a file-size or storage quota limit; file and purpose are required, and purpose must be one of assistants, batch, fine-tune, vision, user_data, or evals. If provided, expires_after.anchor must be created_at and expires_after.seconds must be between 3,600 and 2,592,000. A 429 is returned when too many file requests are made, and a 500 is returned when a server error prevents the upload.