Media Transformations

Dynamically crop, resize, and edit media via the CDN using Just-In-Time (JIT) APIs and Async Jobs.

Media Transformations (JIT)

GET

/api/v2/transform/:appName/*objectKey

Transform public images on-the-fly. You can use pre-configured App Variants or generate arbitrary transformations using an HMAC signature.

Original

Transformed

Example of resizing and cropping an image to a 200x200 square using the 'cover' crop mode.

GEThttps://api.buzstorage.com/api/v2/transform/my-app/assets/shoes.jpg?w=200&h=200&c=cover&sig=...

Query Param	Type	Description
variant	string	Use a preset variant defined in your App Settings (e.g., `thumbnail`). No signature required.
w, h	number	Width and Height for arbitrary transformations.
c	string	Crop mode (`fill`, `fit`, `cover`, `inside`).
blur	number	Applies a gaussian blur to the image. Value specifies the sigma of the blur (e.g. `0.3` to `1000`).
q	number	Output quality (1-100). Default is `80`.
f	string	Target format (`auto`, `webp`, `avif`, `jpeg`, `png`). Default is `auto`.
sig	string	Required for arbitrary transformations. A SHA256 HMAC signature of the parameters.

Generating HMAC Signatures

To prevent malicious abuse, arbitrary resizing requires a signature using your Environment Secret. Construct a payload string joining the appName, objectKey, and parameters separated by colons (in alphabetical order of keys: w, h, c, blur, q, f). Leave empty values for omitted parameters.

<img src="https://api.buzstorage.com/api/v2/transform/my-app/assets/image.png?variant=thumbnail" />

Video Transformation Jobs (Async)

POST

/api/v2/transform/video/jobs

Unlike images, video transformations (trimming, GIF conversions) are computationally heavy and cannot be performed Just-In-Time. Instead, submit a JSON payload to queue an asynchronous processing job.

Webhooks & Storage

When a video job completes, the resulting file is saved as a new distinct file in your storage. You can provide a saveAs path and a webhookUrl to be notified the moment your new video is ready!

Original

Transformed

Example of an asynchronous video job trimming 5 seconds from a raw MP4 and converting it into a high-quality looping GIF.

GET{ "trim": { "start": "00:00:10", "duration": 5 }, "format": "gif" }

curl -X POST https://api.buzstorage.com/api/v2/transform/video/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "appName": "my-app",
    "objectKey": "assets/raw-video.mp4",
    "saveAs": "assets/clip-preview.gif",
    "webhookUrl": "https://my-app.com/webhooks/video-ready",
    "operations": {
      "trim": { "start": "00:00:10", "duration": 5 },
      "format": "gif"
    }
  }'

DRM Watermarking (JIT)

PATCH

/api/protected/folder/:folderId/watermark

Update the DRM watermark settings for an existing folder. When enabled, all images served from this folder will be auto-watermarked on-the-fly without permanently altering the original files.

{
  "isWatermarkEnabled": true,
  "watermarkFileId": "f1749123456789-abc123",
  "watermarkOpacity": 0.5
}

Folder Level Activation

Watermarking is applied at the folder level. You can also enable it during folder creation by passing "isWatermarkEnabled": true to the POST /api/protected/folders/create endpoint.

curl -X PUT https://api.buzstorage.com/v1/folders/123/watermark \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "isWatermarkEnabled": true,
    "watermarkOpacity": 0.6
  }'

PreviousPrivate Files & Folders

NextDeveloper Experience

Query Param

Type

Description

variant

string

Use a preset variant defined in your App Settings (e.g., thumbnail). No signature required.

w, h

number

Width and Height for arbitrary transformations.

string

Crop mode (fill, fit, cover, inside).

blur

number

Applies a gaussian blur to the image. Value specifies the sigma of the blur (e.g. 0.3 to 1000).

number

Output quality (1-100). Default is 80.

string

Target format (auto, webp, avif, jpeg, png). Default is auto.

sig

string

Required for arbitrary transformations. A SHA256 HMAC signature of the parameters.

curl -X POST https://api.buzstorage.com/api/v2/transform/video/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "appName": "my-app", "objectKey": "assets/raw-video.mp4", "saveAs": "assets/clip-preview.gif", "webhookUrl": "https://my-app.com/webhooks/video-ready", "operations": { "trim": { "start": "00:00:10", "duration": 5 }, "format": "gif" } }'

curl -X PUT https://api.buzstorage.com/v1/folders/123/watermark \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "isWatermarkEnabled": true, "watermarkOpacity": 0.6 }'