Image processing API V2

WARNING

The Image processing API V2 is currently in beta

To export the image base url for this api you need to export the item with the task table-export-items. And you need to have this feature flag export_item_resource_attribute enabled.

Overview

This API provides an interface to process images linked to an item through an IMAGE field. The API is designed to be able to perform various image processing operations on the image, such as resizing, cropping, and performing format conversion.

Technical details

This API is built uppon the imgproxy processing API. the current version used in production is the 3.7. In this documentation we tend to restrict ourselves to the API features that are available in the current version. Also, the logic and the name used in the provided API tend (every time it's possible) to follow the imgproxy API.

Limitations

The API is currently limited to processing images that are linked to an item through an IMAGE or ATTACHMENT field.

Url generation

The url for an image processing operation is generated with the following pattern:

https://asset.product-live.com/documents/[accountId]/[imageHash]/[%option_name:%argument1:%argument2:...:argumentN (ex: resize:100:100)]

Here is a concrete example:

https://asset.product-live.com/documents/5f0818d27ef6945715d9bbc7/8db6d3f2057678aecb94c0b2f98dd7564908fab9b722168bbe18d11b27eb748d/resize:100:100

To get the Image API V2 url of images stored on items, you can export the items using task table-export-items.

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES"
            created="2019-04-10T13:40:23.83"
            updated="2019-04-10T13:40:23.83">
            <Identifier key="EAN_13">1234567890123</Identifier>
            <Field key="MAIN_IMAGE"
                width-px="3000"
                height-px="3000"
                size-kb="3254"
                file-hash="3f483b628326fc6019f24b05ee1f25665e9610d97b88aec1867175852dbd9960"
                original-file-name="1234567890123_front.jpg"
                color-space="RGB"
                color-profile="NONE"
                resource="https://asset.product-live.com/documents/61cd873970c866d1606693aa/3f483b628326fc6019f24b05ee1f25665e9610d97b88aec1867175852dbd9960"
                md5="91f11681dfcf7397a9af32345399cd6e">
                https://asset.prod.product-live.com/file-map-resize/61cd873970c866d1606693aa_documents/redirect/3f483b628326fc6019f24b05ee1f25665e9610d97b88aec1867175852dbd9960
            </Field>
        </Item>
    </Items>
</Table>

TIP

If no parameters are provided, the original image is returned unchanged.

WARNING

If at least one parameter is provided, the metadata of the original image are stripped by default.

Image processing operations

Option Resize

resize:%resizing_type:%width:%height:%enlarge:%extend
rs:%resizing_type:%width:%height:%enlarge:%extend

Key points

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.

source: imgproxy documentation

Examples:

• Resize the given image to a width of 500px while keeping the aspect ratio.

/rs:fit:500

• Resize the given image to a dimension of 300px x 500px, while keeping the aspect ratio

/rs:fit:300:500

• Resize the given image to a dimension of 300px x 500px, and ignore the aspect ratio

/rs:force:300:500

Option resizing_type

resizing_type:%resizing_type
rt:%resizing_type

Key points

Defines how the API 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 value: fit

source: imgproxy documentation

Examples

• Resize the given image while keeping aspect ratio to fill a dimension of 300px x 500px and crops projecting parts

/width:300/height:500/resizing_type:fill

Option width

width:%width
w:%width

Key points

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

source: imgproxy documentation

Examples

• Resize the given image to a width of 500px

/width:500

Option height

height:%height
h:%height

Key points

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

source: imgproxy documentation

Examples

• Resize the given image to a height of 100px

/height:100

Option Crop

crop:%width:%height:%gravity
c:%width:%height:%gravity

Key points

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.

source: imgproxy documentation

Examples

• Crop an image:
  • Starting from the top left corner
  • Apply an offset of x = 700 pixels and y = 350 pixels
  • Draw an area of a width of 1150 pixels and a height of 1250 pixels
  • Resized the result to a width of 500px

/crop:400:400:nowe:500:250/rs:fit:500

Option Background

background:%R:%G:%B
bg:%R:%G:%B

background:%hex_color
bg:%hex_color

Key points

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

source: imgproxy documentation

Examples

• Resize the image to a width and height of 500px, allow the image to be extended if the image is smaller to the given size, and finally resize it to a height of 700px and fill the background with a red color

/rs:fit:500:500/extend:true:ce:0:0/height:700/background:255:0:0

Option Format

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

Key points

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

Default: jpg

source: imgproxy documentation

Image formats support

Format	Extension	Source	Result
PNG	png	Yes	Yes
JPEG	jpg	Yes	Yes
WebP	webp	Yes	Yes
AVIF	avif	Yes	Yes
GIF	gif	Yes	Yes
ICO	ico	Yes	Yes
SVG	svg	Yes	SVG results are not supported when the source image is not SVG
HEIC	heic	Yes	No
BMP	bmp	Yes	Yes
TIFF	tiff	Yes	Yes
PDF	pdf	Yes	No

Examples

• Resize the image to a width of 500px and convert it to a PNG

/width:500/format:png

• Resize the image to a width of 500px and convert it to a WEBP

/width:500/format:webp

• Transform a pdf file into a png (if the source file contains multiple pages, only the first page will be converted)

/format:png

Original file: https://asset.prod.product-live.com/documents/5e691db029e7a3fa64c3ca5e/62f2511c94a5547a29128907b96367988b2878db4bfd91b62d5f67ec33bb00a4

Result:

Option Quality

quality:%quality
q:%quality

Key points

Redefines quality of the resulting image, as a percentage.

Default: 0

source: imgproxy documentation

Examples

• Resize the image to a width of 500px and convert it to a JPG with a quality of 90%

/width:500/format:jpg/quality:90

• Resize the image to a width of 500px and convert it to a WEBP with a quality of 10%

/width:500/format:webp/quality:10

Option Rotate

rotate:%angle
rot:%angle

Key points

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

source: imgproxy documentation

Examples

• Resize the image to a width of 500px and rotate it by 90 degrees

/width:500/rotate:90

Strip Metadata

Metadata are stripped by default when at least one option is passed

If no options are passed, metadata are not stripped.

strip_metadata:%strip_metadata
sm:%strip_metadata

Key points

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.

source: imgproxy documentation

Examples

• Resize the image to a width of 500px and strip the metadata

/width:500/strip_metadata:true

Strip Color Profile

strip_color_profile:%strip_color_profile
scp:%strip_color_profile

Key points

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.

source: imgproxy documentation

Examples

• Resize the image to a width of 500px and strip the color profile

/width:500/strip_color_profile:true

Option Filename

filename:%string
fn:%string

Key points

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

Default: empty

source: imgproxy documentation

Attention

If not specified, the image is named with its hash

Examples

• Resize the image to a width of 500px, convert it to a PNG and set the filename to my_image

/width:500/format:png/filename:my_image

Option enlarge

enlarge:%enlarge
el:%enlarge

Key points

When set to 1, t or true, imgproxy will enlarge the image if it is smaller than the given size.

Default: false

source: imgproxy documentation

Examples

• Resize the given image to a width of 10000px and enlarge it if it is smaller than 500px

/width:10000/enlarge:1

Option extend

extend:%extend:%gravity
ex:%extend:%gravity

Key points

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.

source: imgproxy documentation

Default: false:ce:0:0

Option gravity

gravity:%type:%x_offset:%y_offset
g:%type:%x_offset:%y_offset

Key points

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.

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: This feature is available in imgproxy 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 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.

Default: ce:0:0

_source: imgproxy documentation

Option Watermark

Option only available in production

This option is only available in the production environment (asset.product-live.com), and not in the development environment (asset.dev.product-live.com) ant the staging environment (asset.stage.product-live.com).

The watermark option require a watermark image or text to be evaluated

Since we do not provide any default watermark

watermark:%opacity:%position:%x_offset:%y_offset:%scale
wm:%opacity:%position:%x_offset:%y_offset:%scale

Key points

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

_source: imgproxy documentation

Option Watermark text

Option only available in production

This option is only available in the production environment (asset.product-live.com), and not in the development environment (asset.dev.product-live.com) ant the staging environment (asset.stage.product-live.com).

watermark_text:%text
wmt:%text

Key points

When set, the API 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

source: imgproxy documentation

Examples

• Watermark the current image using with a custom text, 50% opacity, in blue using Pango markup, positioned in the bottom right corner

/wmt:PHNwYW4gZm9yZWdyb3VuZD0iYmx1ZSIgc2l6ZT0ieC1sYXJnZSI-SGVsbG8hPC9zcGFuPg/wm:0.5:soea:0:0:0.5

Option Watermark URL

Option only available in production

This option is only available in the production environment (asset.product-live.com), and not in the development environment (asset.dev.product-live.com) ant the staging environment (asset.stage.product-live.com).

watermark_url:%url
wmu:%url

Key points

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

source: imgproxy documentation

Examples

• Watermark the current image using a custom image and place it on the bottom left corner with 50% opacity

/wmu:aHR0cHM6Ly9hc3NldC5wcm9kLnByb2R1Y3QtbGl2ZS5jb20vZmlsZS1tYXAvNWU2OTFkYjAyOWU3YTNmYTY0YzNjYTVlX2RvY3VtZW50cy9yZWRpcmVjdC85OWFkNWE0OGY3MTVlNDQxZjgyNzc5ZjgyMmUwZjRhMTIwNTA0OWY5ODVkMDdkZjVjZTkyMGRiZDg4Yjc2ODYz/wm:0.9:sowe:100:50:0.9

Option Trim

trim:%threshold:%color:%equal_hor:%equal_ver
t:%threshold:%color:%equal_hor:%equal_ver

Key points

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.

source: imgproxy documentation

Examples

Original image

/trim:100

Option Padding

padding:%top:%right:%bottom:%left
pd:%top:%right:%bottom:%left

Key points

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.

source: imgproxy documentation

Examples

Original image

/padding:10:10:10:10/background:255:0:0

Option Pixelate

pixelate:%size
pix:%size

Key points

When set, imgproxy will apply the pixelate filter to the resulting image. The value of size defines individual pixel size.

Default: disabled

source: imgproxy documentation

Examples

Original image

/pixelate:10

Fallback image URL

Key points

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

source: imgproxy documentation

Examples

In this example, the original image is not available, so the fallback image is used.

/width:500/format:png/fallback_image_url:aHR0cHM6Ly9hc3NldC5kZXYucHJvZHVjdC1saXZlLmNvbS9kb2N1bWVudHMvNjA4MTI3MzRjNzU0MDA5ZDk2MjEzZjgxL2RmMWY3M2M5NDliZjdiMTRkN2U1NTEwNTc3YTI1YjI0MTAzZmJlMjFlM2JlN2Q3YTQxNWM5NmFmNjZkNzg2ZGE

Option Page

Option only available in production

This option is only available in the production environment (asset.product-live.com), and not in the development environment (asset.dev.product-live.com) ant the staging environment (asset.stage.product-live.com).

page:%page
pg:%page

Key points

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

source: imgproxy documentation

Examples

• Select the 2nd page and convert it to a png image (original file)

/page:1/format:png

Option Video thumbnail second

Option only available in production

This option is only available in the production environment (asset.product-live.com), and not in the development environment (asset.dev.product-live.com) ant the staging environment (asset.stage.product-live.com).

video_thumbnail_second:%second
vts:%second

Key points

source: imgproxy documentation

Examples

• Extract a thumbnail from the current MP4 video (original file)

/video_thumbnail_second:15

Object detection

TIP

Imgproxy can detect objects on the image and use them for smart cropping, blurring the detections, or drawing the detections.

source: imgproxy documentation

• For now, only a face detection model is available
  • Other models may be made available in the future

Object-oriented crop

Key points

You can crop your images and keep objects of desired classes in frame:

.../crop:256:256/g:obj:face/...

source: imgproxy documentation

Examples

• Crop an image and focus on the face

/crop:256:256/g:obj:face

Original image

Cropped image with face detection

/crop:500:500/g:obj:face

Bluring detections

Key points

You can blur objects of desired classes:

.../blur_detections:7:face/...

source: imgproxy documentation

Examples

• Blur the face of the model

/blur_detections:7:face

Original image

https://asset.prod.product-live.com/documents/5e691db029e7a3fa64c3ca5e/4cc4d1b4c56b82765b1228174a1c0d82005e0af5c29ccd2188d128541b2af49d/w:500

Blured image with face detection

https://asset.prod.product-live.com/documents/5e691db029e7a3fa64c3ca5e/4cc4d1b4c56b82765b1228174a1c0d82005e0af5c29ccd2188d128541b2af49d/w:500/blur_detections:7:face

Draw detections

Key points

You can make imgproxy draw bounding boxes for the detected objects of the desired classes (this is handy for testing your models):

.../draw_detections:1:face/...

source: imgproxy documentation

Examples

• Draw a box array around the face of the model

/draw_detections:1:face

https://asset.prod.product-live.com/documents/5e691db029e7a3fa64c3ca5e/4cc4d1b4c56b82765b1228174a1c0d82005e0af5c29ccd2188d128541b2af49d/w:500/draw_detections:1:face

• Work also with multiple objects

https://asset.prod.product-live.com/documents/5e691db029e7a3fa64c3ca5e/4b7cd1609aca4cb35e2d2404249eade37b676bc699238816472a75b0199a6bf4/w:500/draw_detections:1:face