Image Transforms

Transform images on the fly with resizing, format conversion, and quality optimization. The original file is never changed. Each size / format of an image is made once and kept: later requests for the same options are served from the cache and don't count as a new transform.

Transform Parameters#

Any other value for f or fit, or blur / sharpen out of range, is refused with invalid_transform. The SDKs check the options before they build a URL.

Which images can be transformed

JPEG, PNG, WebP, GIF, AVIF, HEIC / HEIF (iPhone and Android camera photos), TIFF and SVG. For animated GIF and PNG, the first frame is used. The orientation a phone stores is applied, so portrait photos come out upright. Images up to 25 MB and 50 megapixels can be transformed.

Showing a transformed image#

Public buckets: a link with no headers

Add the options to the file's public link:

https://storage.abrova.ir/public/<bucketId>/<path>?w=600&f=webp

It needs no key, token or header, so it goes straight into <img src>, srcset, CSS, e-mails or Image.network(url). The SDKs build it for you with getPublicUrl(fileId, …options), and publicImageUrl(link, …options) builds it from a public link you stored earlier, without a request:

// Web (React Native and Node.js are the same)
import { publicImageUrl } from '@abrova/storage-web';

img.src = await storage.getPublicUrl(file.id, { width: 600, format: 'webp' });

const at = (width: number) => publicImageUrl(savedLink, { width, format: 'webp' });
img.srcset = `${at(600)} 600w, ${at(1200)} 1200w`;

// Flutter
final url = await storage.getPublicUrl(file.id,
    transforms: const ImageTransforms(width: 600, format: 'webp'));
Image.network(url);

• Same options, same URL. Options are read in any order with defaults applied, so ?w=300&f=webp and ?f=webp&w=300&q=80 are the same image. Other query parameters are ignored.
• Cached. Browsers and other caches may keep an image for up to a day. When you replace a file's content, new requests get the new image; copies already cached can show the old one until they expire.
• Use a few fixed sizes. One image keeps at most 50 different option sets. A new set beyond that is refused with too_many_variants (429); the existing ones keep working. Pick a few sizes (for example 200, 600 and 1200 wide) instead of the exact size of every view.
• Private buckets have no public link: getPublicUrl fails with 403, and a /public link answers 404.

Private buckets: send the headers

getTransformUrl() returns https://storage.abrova.ir/api/v1/transform/<fileId>?…. That address needs the x-api-key and x-user-token headers and follows the bucket's read rules, so a plain <img src> or Image.network(url) without headers is refused. Load it with something that sends headers:

// Flutter: Image.network can send headers
Image.network(
  storage.getTransformUrl(fileId, transforms: ImageTransforms(width: 200, height: 200, fit: 'cover', format: 'webp')),
  headers: {'x-api-key': 'ab_live_xxxxxxxxxxxx', 'x-user-token': userToken},
);

// Browser: fetch with headers, then show the bytes
const res = await fetch(storage.getTransformUrl(fileId, { width: 200, height: 200, fit: 'cover', format: 'webp' }), {
  headers: { 'x-api-key': 'ab_live_xxxxxxxxxxxx', 'x-user-token': userToken },
});
img.src = URL.createObjectURL(await res.blob());

React Native's <Image source={{ uri, headers }}>, and Coil or Glide on Android, can send the same headers. You can also download() the file, or show it from a signed link your server makes.

Usage and billing#

500 transforms are free every month; the price above that is set at launch and will be paid from your prepaid wallet. When the free transforms are used up and the wallet cannot pay for more, transform requests answer plan_feature_locked (403); the plain file and its public link always work. Transforms count each new size / format of an image once; showing it again doesn't count as a new transform. Bandwidth counts the bytes of the transformed image.

Transform errors#

When an image can't be made, the answer is JSON instead of an image, with statusCode, code and a message you can show to your users. The SDKs expose the codes as StorageErrorCode constants.

Common Use Cases#

// Avatar thumbnail (100x100, square crop)
?w=100&h=100&fit=cover&f=webp&q=80

// Responsive image (max 800px wide, maintain ratio)
?w=800&f=webp&q=85

// Low-quality placeholder (tiny, blurred - for lazy loading)
?w=20&blur=10&f=webp&q=30

// Product image (exact size, white background for contain)
?w=600&h=600&fit=contain&f=jpeg&q=90

// Gallery preview (medium size, optimized)
?w=400&h=300&fit=cover&f=webp&q=75

// Hero image (large, high quality)
?w=1920&h=1080&fit=cover&f=webp&q=90

Fit Modes Explained#

• cover — Resize to cover the target dimensions, cropping if necessary. Best for avatars and thumbnails.
• contain — Resize to fit within dimensions, preserving aspect ratio. May add padding.
• fill — Stretch to exactly match dimensions. May distort the image.
• inside — Resize to fit inside dimensions without upscaling.
• outside — Resize to cover dimensions without downscaling.