Upload Files

Endpoint

POST /upload

Auth: API Key, session, or a presigned signature from Sign Upload Content-Type: multipart/form-data

Form fields

files

file[]

required

One or more files to upload. Each file is validated for type and size.Allowed types: JPEG, PNG, WebP, AVIF, GIF, HEIC/HEIF, PSD, MP4, MOV, WebMMax size per file: Configurable via MAX_FILE_SIZE_MB (default: 50 MB)

HEIC/HEIF files are transcoded to JPEG on upload. The returned filename, path, and url will have a .jpg extension instead of the original .heic/.heif.

folder

string

Destination folder path within storage. Nested folders are supported.photos · uploads/2024/januaryIf omitted, files are stored at the root.

names

string[]

Custom filenames for each uploaded file, in the same order as files. If omitted, the original filename is used.Must include the file extension.

transformations

string[]

Transformation segments to prewarm (pre-generate and cache) immediately after upload. Supports up to 20 variants.w_800,h_600,c_fill · w_400,f_webp,q_85Pre-warming ensures the first user request is served from cache without any processing delay.

Response

200, All files uploaded successfully 207, Partial success (some files failed) 400, Validation error (invalid type, size exceeded, etc.)

{
  "success": true,
  "files": [
    {
      "filename": "photo.jpg",
      "path": "photos/photo.jpg",
      "size": 204800,
      "url": "http://localhost:3000/t/photos/photo.jpg",
      "prewarmedUrls": [
        "http://localhost:3000/t/w_800,h_600,c_fill/photos/photo.jpg"
      ],
      "prewarmErrors": [],
      "queuedTransformationUrls": [],
      "queueErrors": []
    }
  ],
  "errors": []
}

success

boolean

true if all files were processed without error.

files

array

Successfully uploaded files.

Show File object

filename

string

Original or custom filename.

path

string

Storage path relative to root.

size

number

File size in bytes.

url

string

Public URL to access the file.

prewarmedUrls

string[]

URLs that were successfully pre-generated and cached.

prewarmErrors

string[]

Prewarm failures (file still uploaded successfully).

queuedTransformationUrls

string[]

Video transformation URLs queued for background processing.

queueErrors

string[]

Queue submission errors.

errors

array

Files that failed to upload.

Show Error object

filename

string

Name of the failed file.

error

string

Error message.

Examples

Single file
Upload to folder
Upload with prewarm
Multiple files with custom names

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg"

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg" \
  -F "folder=products/2024"

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@photo.jpg" \
  -F "folder=photos" \
  -F "transformations=w_800,h_600,c_fill,f_webp" \
  -F "transformations=w_400,h_400,c_fill,g_face"

Uploads the file and immediately generates two cached variants.

curl -X POST http://localhost:3000/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "files=@IMG_001.jpg" \
  -F "files=@IMG_002.jpg" \
  -F "names=hero-banner.jpg" \
  -F "names=thumbnail.jpg" \
  -F "folder=assets"

Create Folder

Create an empty folder in storage.

Upload & Cache Warming

Prewarm strategy guide.

Delete File

Remove a file and its cached variants.

Sign Upload

Let an untrusted client upload without your API key.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

Endpoint

Form fields

Response

Examples

Create Folder

Upload & Cache Warming

Delete File

Sign Upload

​Endpoint

​Form fields

​Response

​Examples

​Related

Create Folder

Upload & Cache Warming

Delete File

Sign Upload

Endpoint

Form fields

Response

Examples

Related