The ImageBuilder class provides a chainable API for building image transformation URLs. Access it via client.image(imageId).
const url = client.image('img-uuid')
.resize(800, 600)
.grayscale()
.quality(80)
.setFormat('webp')
.toURL();
Every method returns the builder instance, so you can chain as many transformations as you need.
resize(width, height, scale?)
Resize the image to the given dimensions.
| Parameter | Type | Required | Description |
|---|---|---|---|
width | number | Yes | Target width in pixels (1–16384) |
height | number | Yes | Target height in pixels (1–16384) |
scale | number | No | Optional scale factor (positive number) |
client.image('img').resize(400, 300).toURL();
client.image('img').resize(400, 300, 2).toURL(); // with scale
crop(left, top, width, height)
Crop a rectangular region from the image.
| Parameter | Type | Required | Description |
|---|---|---|---|
left | number | Yes | X offset in pixels (>= 0) |
top | number | Yes | Y offset in pixels (>= 0) |
width | number | Yes | Crop width in pixels (1–16384) |
height | number | Yes | Crop height in pixels (1–16384) |
client.image('img').crop(10, 20, 400, 300).toURL();
rotate(angle, background?)
Rotate the image by the given angle.
| Parameter | Type | Required | Description |
|---|---|---|---|
angle | number | Yes | Rotation angle in degrees (any finite number) |
background | string | No | Background fill color as hex code (e.g. "#ff0000") |
client.image('img').rotate(90).toURL();
client.image('img').rotate(45, '#ffffff').toURL();
brightness(factor)
Adjust image brightness.
| Parameter | Type | Required | Description |
|---|---|---|---|
factor | number | Yes | Brightness factor (0–10) |
client.image('img').brightness(1.5).toURL();
contrast(factor)
Adjust image contrast.
| Parameter | Type | Required | Description |
|---|---|---|---|
factor | number | Yes | Contrast factor (0–10) |
client.image('img').contrast(1.5).toURL();
grayscale()
Convert the image to grayscale. Takes no parameters.
client.image('img').grayscale().toURL();
invert()
Invert the image colors. Takes no parameters.
client.image('img').invert().toURL();
blur(sigma?)
Apply a Gaussian blur.
| Parameter | Type | Required | Description |
|---|---|---|---|
sigma | number | No | Blur radius (0.01–100, default 1.0) |
client.image('img').blur().toURL(); // sigma = 1.0
client.image('img').blur(3.5).toURL(); // sigma = 3.5
sharpen(sigma?)
Sharpen the image.
| Parameter | Type | Required | Description |
|---|---|---|---|
sigma | number | No | Sharpen radius (0.01–100, default 1.0) |
client.image('img').sharpen().toURL();
client.image('img').sharpen(2.0).toURL();
emboss()
Apply an emboss effect. Takes no parameters.
client.image('img').emboss().toURL();
median(size?)
Apply a median filter (noise reduction).
| Parameter | Type | Required | Description |
|---|---|---|---|
size | number | No | Filter size — must be a positive odd integer (1–99, default 3) |
client.image('img').median().toURL(); // size = 3
client.image('img').median(5).toURL(); // size = 5
thumbnail(width, height, crop?)
Create a thumbnail, optionally using a smart crop strategy.
| Parameter | Type | Required | Description |
|---|---|---|---|
width | number | Yes | Thumbnail width (1–16384) |
height | number | Yes | Thumbnail height (1–16384) |
crop | string | No | Crop strategy: 'centre', 'entropy', or 'attention' |
client.image('img').thumbnail(150, 150).toURL();
client.image('img').thumbnail(150, 150, 'attention').toURL();
smartCrop(width, height)
Automatically crop the image to the most interesting region.
| Parameter | Type | Required | Description |
|---|---|---|---|
width | number | Yes | Target width (1–16384) |
height | number | Yes | Target height (1–16384) |
client.image('img').smartCrop(400, 400).toURL();
flip(direction)
Flip the image horizontally or vertically.
| Parameter | Type | Required | Description |
|---|---|---|---|
direction | string | Yes | 'horizontal', 'vertical', 'h', or 'v' |
client.image('img').flip('horizontal').toURL();
client.image('img').flip('v').toURL();
quality(value)
Set the output compression quality.
| Parameter | Type | Required | Description |
|---|---|---|---|
value | number | Yes | Quality from 1 (lowest) to 100 (highest) |
client.image('img').quality(85).toURL();
setFormat(format)
Set the output image format.
| Parameter | Type | Required | Description |
|---|---|---|---|
format | string | Yes | 'jpg', 'jpeg', 'png', or 'webp' |
client.image('img').setFormat('webp').quality(80).toURL();
useShort(enabled?)
Switch to the short URL format. Pass false to switch back.
| Parameter | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Enable short format (default true) |
client.image('img').resize(300, 200).useShort().toURL();
// => .../resize-300-200/img.jpg
Short Format Mapping
When useShort() is enabled, operation names are abbreviated:
| Standard Segment | Short Segment |
|---|---|
resize_width_W_height_H | resize-W-H |
crop_left_L_top_T_width_W_height_H | crop-L-T-W-H |
rotate_angle_A | rotate-A |
brightness_factor_F | bright-F |
contrast_factor_F | con-F |
grayscale | gray |
invert | inv |
blur_sigma_S | blur-S |
sharpen_sigma_S | sharp-S |
emboss | emb |
median_size_S | med-S |
thumbnail_width_W_height_H | thumb-W-H |
smartcrop_width_W_height_H | scrop-W-H |
flip_direction_D | flip-h / flip-v |
quality_value_V | q-V |
Validation
All parameters are validated before the URL is built. Invalid values throw a ViucraftValidationError immediately — no network request is made.
client.image('img').resize(-1, 100); // throws ViucraftValidationError
client.image('img').quality(200); // throws ViucraftValidationError
client.image('img').median(4); // throws ViucraftValidationError (must be odd)
Combining Transformations
Chain as many operations as you need:
const url = client.image('photo-uuid')
.resize(1200, 800)
.brightness(1.2)
.contrast(1.1)
.sharpen(1.5)
.quality(90)
.setFormat('webp')
.toURL();
Inspecting Instructions
Use getInstructions() to see the current state of the builder:
const builder = client.image('img').resize(800, 600).grayscale();
console.log(builder.getInstructions());
// { resize: { width: 800, height: 600 }, grayscale: true }