Processing an image
Processing images with imgproxy is really easy: just send an HTTP GET
request to imgproxy and imgproxy will respond with a processed image.
imgproxy responds with an image file and uses an image/*
Content-Type
header, so you can put imgproxy's URLs right into src
attributes of your <img/>
HTML tags or into url()
CSS values
The request URL path should consist of a signature, processing options, a source URL, and optionally an extension, like this:
http://imgproxy.example.com/%signature/%processing_options/plain/%source_url@%extension
http://imgproxy.example.com/%signature/%processing_options/%encoded_source_url.%extension
http://imgproxy.example.com/%signature/%processing_options/enc/%encrypted_source_url.%extension
Check out the example at the end of this guide.
Signature
The signature part should always be present in a URL. If the signature check is disabled (no key/salt pairs are provided), the signature part may contain anything (for example, unsafe
or _
).
A signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs when imgproxy is being used in production.
Once you set up your URL signature, check out the Signing the URL guide to find out how to sign your URLs. Otherwise, since the signature still needs to be present, feel free to use any string here.
Processing options
Processing options should be specified as URL parts divided by slashes (/
). A processing option has the following format:
%option_name:%argument1:%argument2:...:%argumentN
The list of processing options does not define imgproxy's processing pipeline. Instead, imgproxy already comes with a specific, built-in image processing pipeline for maximum performance. Read more about this in the About processing pipeline guide.
imgproxy supports the following processing options:
Resize
resize:%resizing_type:%width:%height:%enlarge:%extend
rs:%resizing_type:%width:%height:%enlarge:%extend
This is a meta-option that defines the resizing type, width, height, enlarge, and extend. All arguments are optional and can be omitted to use their default values.
Size
size:%width:%height:%enlarge:%extend
s:%width:%height:%enlarge:%extend
This is a meta-option that defines the width, height, enlarge, and extend. All arguments are optional and can be omitted to use their default values.
Resizing type
resizing_type:%resizing_type
rt:%resizing_type
Defines how imgproxy will resize the source image. Supported resizing types are:
fit
: resizes the image while keeping aspect ratio to fit a given size.fill
: resizes the image while keeping aspect ratio to fill a given size and crops projecting parts.fill-down
: the same asfill
, but if the resized image is smaller than the requested size, imgproxy will crop the result to keep the requested aspect ratio.force
: resizes the image without keeping the aspect ratio.auto
: if both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will usefill
. Otherwise, it will usefit
.
Default: fit
Resizing algorithm pro
resizing_algorithm:%algorithm
ra:%algorithm
Defines the algorithm that imgproxy will use for resizing. Supported algorithms are nearest
, linear
, cubic
, lanczos2
, and lanczos3
.
Default: lanczos3
Width
width:%width
w:%width
Defines the width of the resulting image. When set to 0
, imgproxy will calculate width using the defined height and source aspect ratio. When set to 0
and resizing type is force
, imgproxy will keep the original width.
Default: 0
Height
height:%height
h:%height
Defines the height of the resulting image. When set to 0
, imgproxy will calculate resulting height using the defined width and source aspect ratio. When set to 0
and resizing type is force
, imgproxy will keep the original height.
Default: 0
Min width
min-width:%width
mw:%width
Defines the minimum width of the resulting image.
When both width
and min-width
are set, the final image will be cropped according to width
, so use this combination with care.
Default: 0
Min height
min-height:%height
mh:%height
Defines the minimum height of the resulting image.
When both height
and min-height
are set, the final image will be cropped according to height
, so use this combination with care.
Default: 0
Zoom
zoom:%zoom_x_y
z:%zoom_x_y
zoom:%zoom_x:%zoom_y
z:%zoom_x:%zoom_y
When set, imgproxy will multiply the image dimensions according to these factors. The values must be greater than 0.
Can be combined with width
and height
options. In this case, imgproxy calculates scale factors for the provided size and then multiplies it with the provided zoom factors.
Unlike the dpr
option, the zoom
option doesn't affect gravities offsets, watermark offsets, and paddings.
Default: 1
Dpr
dpr:%dpr
When set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices. The value must be greater than 0.
The dpr
option affects gravities offsets, watermark offsets, and paddings to make the resulting image structures with and without the dpr
option applied match.
Default: 1
Enlarge
enlarge:%enlarge
el:%enlarge
When set to 1
, t
or true
, imgproxy will enlarge the image if it is smaller than the given size.
Default: false
Extend
extend:%extend:%gravity
ex:%extend:%gravity
- When
extend
is set to1
,t
ortrue
, imgproxy will extend the image if it is smaller than the given size. gravity
(optional) accepts the same values as the gravity option, exceptsm
. Whengravity
is not set, imgproxy will usece
gravity without offsets.
Default: false:ce:0:0
Extend aspect ratio
extend_aspect_ratio:%extend:%gravity
extend_ar:%extend:%gravity
exar:%extend:%gravity
- When
extend
is set to1
,t
ortrue
, imgproxy will extend the image to the requested aspect ratio. gravity
(optional) accepts the same values as the gravity option, exceptsm
. Whengravity
is not set, imgproxy will usece
gravity without offsets.
Default: false:ce:0:0
Gravity
gravity:%type:%x_offset:%y_offset
g:%type:%x_offset:%y_offset
When imgproxy needs to cut some parts of the image, it is guided by the gravity option.
type
- specifies the gravity type. Available values:no
: north (top edge)so
: south (bottom edge)ea
: east (right edge)we
: west (left edge)noea
: north-east (top-right corner)nowe
: north-west (top-left corner)soea
: south-east (bottom-right corner)sowe
: south-west (bottom-left corner)ce
: center
x_offset
,y_offset
- (optional) specifies the gravity offset along the X and Y axes.
Default: ce:0:0
Special gravities:
gravity:sm
: smart gravity.libvips
detects the most "interesting" section of the image and considers it as the center of the resulting image. Offsets are not applicable here.gravity:obj:%class_name1:%class_name2:...:%class_nameN
: pro object-oriented gravity. imgproxy detects objects of provided classes on the image and calculates the resulting image center using their positions. If class names are omited, imgproxy will use all the detected objects.gravity:fp:%x:%y
: the gravity focus point .x
andy
are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image. Treat 0 and 1 as right/left forx
and top/bottom fory
.
Crop
crop:%width:%height:%gravity
c:%width:%height:%gravity
Defines an area of the image to be processed (crop before resize).
width
andheight
define the size of the area:- When
width
orheight
is greater than or equal to1
, imgproxy treats it as an absolute value. - When
width
orheight
is less than1
, imgproxy treats it as a relative value. - When
width
orheight
is set to0
, imgproxy will use the full width/height of the source image.
- When
gravity
(optional) accepts the same values as the gravity option. Whengravity
is not set, imgproxy will use the value of the gravity option.
Trim
trim:%threshold:%color:%equal_hor:%equal_ver
t:%threshold:%color:%equal_hor:%equal_ver
Removes surrounding background.
threshold
- color similarity tolerance.color
- (optional) a hex-coded value of the color that needs to be cut off.equal_hor
- (optional) set to1
,t
ortrue
, imgproxy will cut only equal parts from left and right sides. That means that if 10px of background can be cut off from the left and 5px from the right, then 5px will be cut off from both sides. For example, this can be useful if objects on your images are centered but have non-symmetrical shadow.equal_ver
- (optional) acts likeequal_hor
but for top/bottom sides.
Trimming requires an image to be fully loaded into memory. This disables scale-on-load and significantly increases memory usage and processing time. Use it carefully with large images.
If you know background color of your images then setting it explicitly via color
will also save some resources because imgproxy won't need to automatically detect it.
Use a color
value of FF00FF
for trimming transparent backgrounds as imgproxy uses magenta as a transparency key.
The trimming of animated images is not supported.
Padding
padding:%top:%right:%bottom:%left
pd:%top:%right:%bottom:%left
Defines padding size using CSS-style syntax. All arguments are optional but at least one dimension must be set. Padded space is filled according to the background option.
top
- top padding (and for all other sides if they haven't been explicitly st)right
- right padding (and left if it hasn't been explicitly set)bottom
- bottom paddingleft
- left padding
Padding is applied after all image transformations (except watermarking) and enlarges the generated image. This means that if your resize dimensions were 100x200px and you applied the padding:10
option, then you will end up with an image with dimensions of 120x220px.
Padding follows the dpr option so it will also be scaled if you've set it.
Auto rotate
auto_rotate:%auto_rotate
ar:%auto_rotate
When set to 1
, t
or true
, imgproxy will automatically rotate images based on the EXIF Orientation parameter (if available in the image meta data). The orientation tag will be removed from the image in all cases. Normally this is controlled by the IMGPROXY_AUTO_ROTATE configuration but this processing option allows the configuration to be set for each request.
Rotate
rotate:%angle
rot:%angle
Rotates the image on the specified angle. The orientation from the image metadata is applied before the rotation unless autorotation is disabled.
Only 0, 90, 180, 270, etc., degree angles are supported.
Default: 0
Background
background:%R:%G:%B
bg:%R:%G:%B
background:%hex_color
bg:%hex_color
When set, imgproxy will fill the resulting image background with the specified color. R
, G
, and B
are the red, green and blue channel values of the background color (0-255). hex_color
is a hex-coded value of the color. Useful when you convert an image with alpha-channel to JPEG.
With no arguments provided, disables any background manipulations.
Default: disabled
Background alpha pro
background_alpha:%alpha
bga:%alpha
Adds an alpha channel to background
. The value of alpha
is a positive floating point number between 0
and 1
.
Default: 1
Adjust pro
adjust:%brightness:%contrast:%saturation
a:%brightness:%contrast:%saturation
This is a meta-option that defines the brightness, contrast, and saturation. All arguments are optional and can be omitted to use their default values.
Brightness pro
brightness:%brightness
br:%brightness
When set, imgproxy will adjust brightness of the resulting image. brightness
is an integer number ranging from -255
to 255
.
Default: 0
Contrast pro
contrast:%contrast
co:%contrast
When set, imgproxy will adjust the contrast of the resulting image. contrast
is a positive floating point number, where a value of 1
leaves the contrast unchanged.
Default: 1
Saturation pro
saturation:%saturation
sa:%saturation
When set, imgproxy will adjust saturation of the resulting image. saturation
is a positive floating-point number, where a value of 1
leaves the saturation unchanged.
Default: 1
Blur
blur:%sigma
bl:%sigma
When set, imgproxy will apply a gaussian blur filter to the resulting image. The value of sigma
defines the size of the mask imgproxy will use.
Default: disabled
Sharpen
sharpen:%sigma
sh:%sigma
When set, imgproxy will apply the sharpen filter to the resulting image. The value of sigma
defines the size of the mask imgproxy will use.
As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution), 1.0 for 12 pixels/mm and 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm).
Default: disabled
Pixelate
pixelate:%size
pix:%size
When set, imgproxy will apply the pixelate filter to the resulting image. The value of size
defines individual pixel size.
Default: disabled
Unsharp masking pro
unsharp_masking:%mode:%weight:%divider
ush:%mode:%weight:%divider
Allows redefining unsharp masking options. All arguments have the same meaning as Unsharp masking configs. All arguments are optional and can be omitted.
Blur detections pro
blur_detections:%sigma:%class_name1:%class_name2:...:%class_nameN
bd:%sigma:%class_name1:%class_name2:...:%class_nameN
imgproxy detects objects of the provided classes and blurs them. If class names are omitted, imgproxy blurs all the detected objects.
The value of sigma
defines the size of the mask imgproxy will use.
Draw detections pro
draw_detections:%draw:%class_name1:%class_name2:...:%class_nameN
dd:%draw:%class_name1:%class_name2:...:%class_nameN
When draw
is set to 1
, t
or true
, imgproxy detects objects of the provided classes and draws their bounding boxes. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects.