Upload Image

Upload an image with server-side processing and named variant generation

POST /:projectId/api/v7/storage/images

Upload Image

cURL

curl --request POST \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/storage/images \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "<string>",
  "dimensions": {},
  "aspectRatio": {},
  "widths": {},
  "heights": {},
  "sizes": {},
  "aspectRatios": [
    {}
  ],
  "fit": "<string>",
  "quality": 123,
  "format": "<string>",
  "stripExif": true,
  "pathParts": [
    {}
  ],
  "entityId": "<string>",
  "commentId": "<string>",
  "spaceId": "<string>",
  "userId": "<string>"
}
'

Uploads an image, processes it with Sharp, and stores the original plus all requested variants. Returns proxy URLs for all variants immediately.

This endpoint accepts multipart/form-data. Requires an authenticated user.

Rate limit: 20 requests per 5 minutes.

Body Parameters

file · file · required

The image file to upload. Must be a valid image format recognized by Sharp (JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG). Maximum 50 MB.

mode · string · required

Processing mode. One of: exact-dimensions, aspect-ratio-width-based, aspect-ratio-height-based, original-aspect, multi-aspect-ratio.

dimensions · object

Required for exact-dimensions mode. An object mapping variant names to { width, height } pairs.

{ "thumbnail": { "width": 64, "height": 64 }, "card": { "width": 400, "height": 300 } }

aspectRatio · object

Required for aspect-ratio-width-based and aspect-ratio-height-based modes. { width, height } ratio.

widths · object

Required for aspect-ratio-width-based mode. An object mapping variant names to pixel widths.

heights · object

Required for aspect-ratio-height-based mode. An object mapping variant names to pixel heights.

sizes · object

Required for original-aspect and multi-aspect-ratio modes. An object mapping variant names to longest-edge pixel sizes.

aspectRatios · array

Required for multi-aspect-ratio mode. Array of { width, height } aspect ratio objects.

fit · string

Sharp fit strategy. Defaults to cover. Valid values depend on the mode:

• exact-dimensions, aspect-ratio-width-based, aspect-ratio-height-based, multi-aspect-ratio: cover, contain, inside, or outside
• original-aspect: inside or outside only (cover/contain are not valid for this mode)

quality · number

Output quality (1–100). Applies to JPEG and WebP. Defaults to 85.

format · string

Output format: webp, jpeg, png, or original. Defaults to webp.

stripExif · boolean

Remove EXIF metadata from output. Defaults to true.

pathParts · array

Storage path segments as a JSON-encoded array. Defaults to ["images", "<fileId>"].

entityId · string

Associates the file with an entity for cascade deletion.

commentId · string

Associates the file with a comment for cascade deletion.

spaceId · string

Associates the file with a space.

userId · string

Attribute the upload to a specific user. With a user token the upload is already attributed to the caller; only service/master keys may name a different user. Omit for a backend/project-owned file (no owning user).

Response

{
  "fileId": "uuid",
  "type": "image",
  "originalPath": "/internal/files/...",
  "originalSize": 204800,
  "originalWidth": 1920,
  "originalHeight": 1080,
  "variants": {
    "thumbnail": {
      "publicPath": "/internal/files/...",
      "width": 64,
      "height": 64,
      "size": 3200,
      "format": "webp"
    }
  },
  "format": "webp",
  "quality": 85,
  "createdAt": "2025-01-01T00:00:00.000Z"
}

Error Responses

No File — 400 Bad Request

{ "error": "No file provided", "code": "storage/no-file" }

File Too Large — 413

{ "error": "File size exceeds the allowed limit of 50MB", "code": "storage/file-too-large" }

Invalid Image — 422

{ "error": "Invalid image file", "code": "storage/invalid-image" }