Skip to content

Latest commit

 

History

History
736 lines (477 loc) · 24.4 KB

generating_the_url.md

File metadata and controls

736 lines (477 loc) · 24.4 KB

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 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, 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 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 :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 rezizing 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 rezizing type is force, imgproxy will keep the original height.

Default: 0

Min width :id=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 :id=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, 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 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: 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 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 option. When gravity 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 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 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 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 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 :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 :id=adjust

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 :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 :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 :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 valoe 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 :id=unsharpening

unsharpening:%mode:%weight:%dividor
ush:%mode:%weight:%dividor

Allows redefining unsharpening options. All arguments have the same meaning as Unsharpening configs. All arguments are optional and can be omitted.

Blur detections :id=blur-detections

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 :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 of the provided classes and draws their bounding boxes. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects.

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 :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 :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 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

Style :id=style

style:%style
st:%style

When set, imgproxy will prepend a <style> node with the provided content to the <svg> node of a source SVG image. %style is url-safe Base64-encoded CSS-styles.

Default: blank

Strip Metadata

strip_metadata:%strip_metadata
sm:%strip_metadata

When set to 1, t or true, imgproxy will strip the metadata (EXIF, IPTC, etc.) on JPEG and WebP output images. This is normally controlled by the IMGPROXY_STRIP_METADATA configuration but this procesing option allows the configuration to be set for each request.

Strip Color Profile

strip_color_profile:%strip_color_profile
scp:%strip_color_profile

When set to 1, t or true, imgproxy will transform the embedded color profile (ICC) to sRGB and remove it from the image. Otherwise, imgproxy will try to keep it as is. This is normally controlled by the IMGPROXY_STRIP_COLOR_PROFILE configuration but this procesing option allows the configuration to be set for each request.

Quality

quality:%quality
q:%quality

Redefines quality of the resulting image, as a percentage. When set to 0, quality is assumed based on IMGPROXY_QUALITY and format_quality.

Default: 0.

Format quality :id=format-quality

format_quality:%format1:%quality1:%format2:%quality2:...:%formatN:%qualityN
fq:%format1:%quality1:%format2:%quality2:...:%formatN:%qualityN

Adds or redefines IMGPROXY_FORMAT_QUALITY values.

Autoquality :id=autoquality

autoquality:%method:%target:%min_quality:%max_quality:%allowed_error
aq:%method:%target:%min_quality:%max_quality:%allowed_error

Redefines autoquality settings. All arguments have the same meaning as Autoquality configs. All arguments are optional and can be omitted.

⚠️Warning: Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.

Max Bytes

max_bytes:%bytes
mb:%bytes

When set, imgproxy automatically degrades the quality of the image until the image size is under the specified amount of bytes.

📝Note: Applicable only to jpg, webp, heic, and tiff.

⚠️Warning: When max_bytes is set, imgproxy saves image multiple times to achieve the specified image size.

Default: 0

JPEG options :id=jpeg-options

jpeg_options:%progressive:%no_subsample:%trellis_quant:%overshoot_deringing:%optimize_scans:%quant_table
jpgo:%progressive:%no_subsample:%trellis_quant:%overshoot_deringing:%optimize_scans:%quant_table

Allows redefining JPEG saving options. All arguments have the same meaning as the Advanced JPEG compression configs. All arguments are optional and can be omitted.

PNG options :id=png-options

png_options:%interlaced:%quantize:%quantization_colors
pngo:%interlaced:%quantize:%quantization_colors

Allows redefining PNG saving options. All arguments have the same meaning as with the Advanced PNG compression configs. All arguments are optional and can be omitted.

Format

format:%extension
f:%extension
ext:%extension

Specifies the resulting image format. Alias for the extension part of the URL.

Default: jpg

Page :id=page

page:%page
pg:%page

When a source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use it on. Page numeration starts from zero.

Default: 0

Video thumbnail second :id=video-thumbnail-second

video_thumbnail_second:%second
vts:%second

Allows redefining IMGPROXY_VIDEO_THUMBNAIL_SECOND config.

Fallback image URL :id=fallback-image-url

You can use a custom fallback image by specifying its URL with the fallback_image_url processing option:

fallback_image_url:%url
fiu:%url

The value of url is the Base64-encoded URL of the custom fallback image.

Default: blank

Skip processing :id=skip-processing

skip_processing:%extension1:%extension2:...:%extensionN
skp:%extension1:%extension2:...:%extensionN

When set, imgproxy will skip the processing of the listed formats. Also available as the IMGPROXY_SKIP_PROCESSING_FORMATS configuration.

📝Note: Processing can only be skipped when the requested format is the same as the source format.

📝Note: Video thumbnail processing can't be skipped.

Default: empty

Cache buster

cachebuster:%string
cb:%string

Cache buster doesn't affect image processing but it's changing allows for bypassing the CDN, proxy server and browser cache. Useful when you have changed some things that are not reflected in the URL, like image quality settings, presets, or watermark data.

It's highly recommended to prefer the cachebuster option over a URL query string because that option can be properly signed.

Default: empty

Expires :id=expires

expires:%timestamp
exp:%timestamp

When set, imgproxy will check the provided unix timestamp and return 404 when expired.

Default: empty

Filename

filename:%string
fn:%string

Defines a filename for the Content-Disposition header. When not specified, imgproxy will get the filename from the source url.

Default: empty

Preset

preset:%preset_name1:%preset_name2:...:%preset_nameN
pr:%preset_name1:%preset_name2:...:%preset_nameN

Defines a list of presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.

Read more about presets in the Presets guide.

Default: empty

Source URL

There are two ways to specify the source url:

Plain

The source URL can be provided as is, prendended by the /plain/ segment:

/plain/http://example.com/images/curiosity.jpg

📝Note: If the source URL contains a query string or @, you'll need to escape it.

When using a plain source URL, you can specify the extension after @:

/plain/http://example.com/images/curiosity.jpg@png

Base64 encoded

The source URL can be encoded with URL-safe Base64. The encoded URL can be split with / as desired:

/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn

When using an encoded source URL, you can specify the extension after .:

/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png

Extension

Extension specifies the format of the resulting image. Read more about image formats support here.

The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use jpg. You also can enable WebP support detection to use it as the default resulting format when possible.

Example

A signed imgproxy URL that uses the sharp preset, resizes http://example.com/images/curiosity.jpg to fill a 300x400 area using smart gravity without enlarging, and then converts the image to png:

http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/preset:sharp/resize:fill:300:400:0/gravity:sm/plain/http://example.com/images/curiosity.jpg@png

The same URL with shortcuts will look like this:

http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/pr:sharp/rs:fill:300:400:0/g:sm/plain/http://example.com/images/curiosity.jpg@png

The same URL with a Base64-encoded source URL will look like this:

http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/pr:sharp/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png