Image transformations

Getting started

To transform an image, use the transform() method from the images API:

import GetProntoClient from "getpronto-sdk";

const client = new GetProntoClient({
  apiKey: "YOUR_API_KEY"
});

// Start a transformation chain
const transformer = client.images.transform("file_id");

Transformation methods

Methods collect transformation options for a fixed server pipeline. Their order in the chain does not control the processing order. Automatic format and quality options are available in SDK 1.4.1; update an older installation before using them.

// Resize to 800x600 using contain mode
client.images
  .transform(fileId)
  .resize(800, 600, "contain")

// Set quality to 90
client.images
  .transform(fileId)
  .quality(90)

// Or choose per image
client.images
  .transform(fileId)
  .quality("auto")

// Apply blur with radius 5
client.images
  .transform(fileId)
  .blur(5)

// Apply sharpening
client.images
  .transform(fileId)
  .sharpen()

// Convert to grayscale
client.images
  .transform(fileId)
  .grayscale()

// Rotate 90 degrees clockwise
client.images
  .transform(fileId)
  .rotate(90)

// Add a 5px red border
client.images
  .transform(fileId)
  .border(5, "FF0000")

// Crop a 500x500 square from position (100,100)
client.images
  .transform(fileId)
  .crop(100, 100, 500, 500)

// Convert to WebP format
client.images
  .transform(fileId)
  .format("webp")

// Or let Get Pronto choose
client.images
  .transform(fileId)
  .format("auto")

Responsive images with imageProps()

Available in SDK 1.4.1, imageProps(file, options) builds image attributes locally. It is synchronous, makes no network request and needs no API key, so it can run in a Client Component. Pass uploaded file metadata or a public secureUrl string.

import { imageProps, type FileMetadata } from "getpronto-sdk";

// Pass the metadata returned by your upload route to this component.
export function ProductImage({ file }: { file: FileMetadata }) {
  const props = imageProps(file, {
    widths: [400, 800, 1200],
    sizes: "(max-width: 768px) 100vw, 50vw",
    format: "auto",
    q: "auto",
  });

  return <img {...props} alt="Product photo" style={{ width: "100%", height: "auto" }} />;
}

• widths defaults to 400, 800, 1200 and 1600 pixels. Widths must be integers from 1 to 5000. Invalid values are dropped; duplicates are removed and the list is sorted. An empty valid list or more than six unique valid widths throws an error.
• When metadata includes the source width, larger candidates are dropped. If all candidates are larger, the source width is used. A URL string alone cannot supply this information.
• Supply sizes to describe the image's display width in your layout. It is omitted when not supplied. The browser chooses a srcSet candidate using the layout hint and pixel density; there is no w=auto or h=auto API option.
• The result contains src (the largest candidate), srcSet and your sizes, if supplied. width and height are included only when both source dimensions are known. Metadata for older uploads may lack them.
• Options also accept transformation settings such as format, q, fit and effects. Use widthsinstead of w or h. For cropping or rotation that changes the aspect ratio, set dimensions matching the output instead of relying on the original metadata.

Each width can create a separate transformation when requested. Building the attributes does not generate every variant immediately. Keep the candidate list short, and set alt text, styling and loading behaviour in your application.

The dashboard transform builder also offers copyable responsive HTML. Adjust its sizes value and alt text to match your page.

Defaults and fallback behaviour

Automatic format lets Get Pronto choose an efficient output format. SVG/BMP originals are passed through. It does not negotiate formats by browser. Automatic quality uses a starting quality for the output format and adjusts it for simple graphics or transparency; it does not target a file size. Omitting quality uses 80 when encoding. Neither automatic option is enabled by default.

Resizes do not enlarge the source. Animation is retained for GIF/WebP output; an incompatible output returns the original. JPEG conversion replaces transparency with white. Read the full format and fallback reference before relying on exact output dimensions or formats.

Getting results

After configuring your transformations, you can either:

• Use toURL() to get a URL for the transformed image
• Use transform() to get the transformed image data as a Blob

Complete examples

// Get a URL for a resized, optimized thumbnail
const thumbnailUrl = await client.images
  .transform(fileId)
  .resize(300, 200)
  .quality(90)
  .format("webp")
  .toURL();

console.log("Transformed URL:", thumbnailUrl);

// Get the transformed image data
const imageBlob = await client.images
  .transform(fileId)
  .resize(800, 600)
  .grayscale()
  .quality(85)
  .transform();

// Use with an image element
const imageUrl = URL.createObjectURL(imageBlob);
imageElement.src = imageUrl;

const processedImage = await client.images
  .transform(fileId)
  .resize(800, 600)           // Request a resize
  .crop(100, 100, 400, 300)   // Crop within the resized image
  .rotate(90)                // Request rotation
  .grayscale()               // Convert to grayscale
  .quality(85)               // Set quality
  .format("webp")            // Convert to WebP
  .transform();              // Get the final image