# Generating the URL The URL should contain the signature, processing options, and source URL, like this: ``` /%signature/%processing_options/plain/%source_url@%extension /%signature/%processing_options/%encoded_source_url.%extension ``` Check out the [example](#example) at the end of this guide. ## Signature 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](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) 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](about_processing_pipeline.md) 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](#resizing-type), [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#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](#width), [height](#height), [enlarge](#enlarge), and [extend](#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 as `fill`, 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 use `fill`. Otherwise, it will use `fit`. Default: `fit` ### Resizing algorithm![pro](/assets/pro.svg) :id=resizing-algorithm ``` 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. **⚠️Warning:** 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. **⚠️Warning:** 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. **📝Note:** Unlike [dpr](#dpr), `zoom` doesn't set the `Content-DPR` header in the response. 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. **📝Note:** `dpr` also sets the `Content-DPR` header in the response so the browser can correctly render the image. 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 to `1`, `t` or `true`, imgproxy will extend the image if it is smaller than the given size. * `gravity` _(optional)_ accepts the same values as the [gravity](#gravity) option, except `sm`. When `gravity` is not set, imgproxy will use `ce` 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](/assets/pro.svg) object-oriented gravity. imgproxy [detects objects](object_detection.md) 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` and `y` 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 for `x` and top/bottom for `y`. ### Crop ``` crop:%width:%height:%gravity c:%width:%height:%gravity ``` Defines an area of the image to be processed (crop before resize). * `width` and `height` define the size of the area: * When `width` or `height` is greater than or equal to `1`, imgproxy treats it as an absolute value. * When `width` or `height` is less than `1`, imgproxy treats it as a relative value. * When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image. * `gravity` _(optional)_ accepts the same values as the [gravity](#gravity) option. When `gravity` is not set, imgproxy will use the value of the [gravity](#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 to `1`, `t` or `true`, 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 like `equal_hor` but for top/bottom sides. **⚠️Warning:** 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. **📝Note:** 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. **📝Note:** Use a `color` value of `FF00FF` for trimming transparent backgrounds as imgproxy uses magenta as a transparency key. **📝Note:** 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](#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 padding * `left` - left padding **📝Note:** 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. **📝Note:** Padding follows the [dpr](#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.md#miscellaneous) configuration but this procesing 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. **📝Note:** 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](/assets/pro.svg) :id=background-alpha ``` 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](/assets/pro.svg) :id=adjust ``` adjust:%brightness:%contrast:%saturation a:%brightness:%contrast:%saturation ``` This is a meta-option that defines the [brightness](#brightness), [contrast](#contrast), and [saturation](#saturation). All arguments are optional and can be omitted to use their default values. ### Brightness![pro](/assets/pro.svg) :id=brightness ``` 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](/assets/pro.svg) :id=contrast ``` 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](/assets/pro.svg) :id=saturation ``` 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 ### Unsharpening![pro](/assets/pro.svg) :id=unsharpening ``` unsharpening:%mode:%weight:%dividor ush:%mode:%weight:%dividor ``` Allows redefining unsharpening options. All arguments have the same meaning as [Unsharpening](configuration.md#unsharpening) configs. All arguments are optional and can be omitted. ### Blur detections![pro](/assets/pro.svg) :id=blur-detections ``` blur_detections:%sigma:%class_name1:%class_name2:...:%class_nameN bd:%sigma:%class_name1:%class_name2:...:%class_nameN ``` imgproxy [detects objects](object_detection.md) 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](/assets/pro.svg) :id=draw-detections ``` 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](object_detection.md) of the provided classes and draws their bounding boxes. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects. ### Gradient![pro](/assets/pro.svg) :id=gradient ``` gradient:%opacity:%color:%direction:%start%stop gr:%opacity:%color:%direction:%start%stop ``` Places a gradient on the processed image. The placed gradient transitions from transparency to the specified color. * `opacity`: specifies gradient opacity. When set to `0`, gradient is not applied. * `color`: _(optional)_ a hex-coded value of the gradient color. Default: `000` (black). * `direction`: _(optional)_ specifies the direction of the gradient. Available values: * `down`: _(default)_ the top side of the gradient is transparrent, the bottom side is opaque * `up`: the bottom side of the gradient is transparrent, the top side is opaque * `right`: the left side of the gradient is transparrent, the right side is opaque * `left`: the right side of the gradient is transparrent, the left side is opaque * `start`, `stop`: floating point numbers that define relative positions of where the gradient starts and where it ends. Default values are `0.0` and `1.0` respectively. ### Watermark ``` watermark:%opacity:%position:%x_offset:%y_offset:%scale wm:%opacity:%position:%x_offset:%y_offset:%scale ``` Places a watermark on the processed image. * `opacity`: watermark opacity modifier. Final opacity is calculated like `base_opacity * opacity`. * `position`: (optional) specifies the position of the watermark. Available values: * `ce`: (default) center * `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) * `re`: repeat and tile the watermark to fill the entire image * `x_offset`, `y_offset` - (optional) specify watermark offset by X and Y axes. When using `re` position, these values define the spacing between the tiles. * `scale`: (optional) a floating-point number that defines the watermark size relative to the resultant image size. When set to `0` or when omitted, the watermark size won't be changed. Default: disabled ### Watermark URL![pro](/assets/pro.svg) :id=watermark-url ``` watermark_url:%url wmu:%url ``` When set, imgproxy will use the image from the specified URL as a watermark. `url` is the Base64-encoded URL of the custom watermark. Default: blank ### Watermark text![pro](/assets/pro.svg) :id=watermark-text ``` watermark_text:%text wmt:%text ``` When set, imgproxy will generate an image from the provided text and use it as a watermark. `text` is the Base64-encoded text of the custom watermark. By default, the text color is black and the font is `sans 16`. You can use [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) in the `text` value to change the style. If you want to use a custom font, you need to put it in `/usr/share/fonts` inside a container. Default: blank ### Watermark Size![pro](/assets/pro.svg) :id=watermark-size ``` watermark_size:%width:%height wms:%width:%height ``` Defines the desired width and height of the watermark. imgproxy always uses `fit` resizing type when resizing watermarks and enlarges them when needed. When `%width` is set to `0`, imgproxy will calculate the width using the defined height and watermark's aspect ratio. When `%height` is set to `0`, imgproxy will calculate the height using the defined width and watermark's aspect ratio. **📝Note:** This processing option takes effect only when the `scale` argument of the `watermark` option is set to zero. Default: `0:0` ### Watermark Shadow![pro](/assets/pro.svg) :id=watermark-shadow ``` watermark_shadow:%sigma wmsh:%sigma ``` When set, imgproxy will add a shadow to the watermark. The value of `sigma` defines the size of the mask imgproxy will use to blur the shadow. Default: disabled ### Style![pro](/assets/pro.svg) :id=style ``` style:%style st:%style ``` When set, imgproxy will prepend a `