Skip to content

Image Transformation

Apply on-the-fly transformations to images without re-uploading. All transformation commands use ImageMagick syntax — the industry-standard tool for image processing.

How it works

Pass ImageMagick commands via the format query parameter. GFile executes the transformation, caches the result as a sub-file, and returns the processed image. Use $INPUT and $OUTPUT.<ext> as placeholders for the source and destination files.

/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=<imagemagick-command>&apiKey=<your-api-key>

Available transformations

Operation Command Description
Resize -resize 300x200 Resize to width×height
Rotate -rotate 90 Rotate by angle (degrees)
Flip -flip Flip vertically
Flop -flop Flip horizontally
Grayscale -colorspace Gray Convert to grayscale
Blur -blur 0x5 Apply Gaussian blur (radius×sigma)
Sharpen -sharpen 0x1 Sharpen image
Format conversion -format webp Convert to another format
Quality -quality 80 Set output compression quality (1-100)
Crop -crop 200x200+50+50 Crop to width×height at offset +x+y
Thumbnail -thumbnail 150x150^ Create a thumbnail with aspect fill
Strip metadata -strip Remove EXIF and metadata

Examples

Resize an image

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=-resize 200x200&apiKey=<your-api-key>"
  • -resize 200x200 resizes to fit within 200×200 pixels, preserving aspect ratio

Convert format and set quality

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT -quality 80 $OUTPUT.webp&apiKey=<your-api-key>"
  • $INPUT references the original file
  • -quality 80 sets compression quality to 80%
  • $OUTPUT.webp outputs as WebP format

Create a centered thumbnail

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT -resize 150x150^ -gravity center -extent 150x150 $OUTPUT.png&apiKey=<your-api-key>"
  • -resize 150x150^ resizes to fill the 150×150 area (may overflow)
  • -gravity center anchors the crop to the center
  • -extent 150x150 crops to exactly 150×150 pixels

Compose images (watermark overlay)

Reference other files in your transformation pipeline using $<file-uuid>:

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?format=$INPUT $<watermark-file-uuid>.png -gravity southeast -composite $OUTPUT.png&apiKey=<your-api-key>"
  • $<watermark-file-uuid>.png references another file stored in GFile
  • -gravity southeast positions the overlay at the bottom-right
  • -composite merges the images together

Get image metadata

Retrieve detailed technical information (dimensions, format, color space):

curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/info?apiKey=<your-api-key>"

Returns ImageMagick JSON output with dimensions, format, color space, and more.