imgproxy

https://docs.imgproxy.net/
Admin
imgproxy is a fast, secure, and simple standalone server for resizing, processing, and converting...
Tokens:19,891
Snippets:342
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run imgproxy with Docker

Source: https://docs.imgproxy.net/getting_started

Commands to pull the latest imgproxy image and start the container on port 8080.

```bash
docker pull ghcr.io/imgproxy/imgproxy:latest  

docker run -p 8080:8080 -it ghcr.io/imgproxy/imgproxy:latest  
```

--------------------------------

### Install and build imgproxy on macOS

Source: https://docs.imgproxy.net/installation

Install dependencies via Homebrew and compile the binary with required environment variables.

```bash
brew install vips go  

PKG_CONFIG_PATH="$(brew --prefix libffi)/lib/pkgconfig" \

  CGO_LDFLAGS_ALLOW="-s|-w" \

  CGO_CFLAGS_ALLOW="-Xpreprocessor" \

  go build -o /usr/local/bin/imgproxy ./cli  


```

--------------------------------

### Install via Homebrew

Source: https://docs.imgproxy.net/installation

Install imgproxy on macOS using the Homebrew package manager.

```bash
brew install imgproxy
```

--------------------------------

### Install libvips on Ubuntu

Source: https://docs.imgproxy.net/installation

Update package lists and install the libvips development headers.

```bash
sudo apt-get update  

sudo apt-get install libvips-dev  


```

--------------------------------

### Define info presets in a file

Source: https://docs.imgproxy.net/configuration/options

Example content for a file referenced by IMGPROXY_INFO_PRESETS_PATH, supporting comments and one definition per line.

```text
default=xmp:0/blurhash:4:3  

  

# Detect objects on the image  

with_objects=detect_objects:1  


```

--------------------------------

### Define processing presets in a file

Source: https://docs.imgproxy.net/configuration/options

Example content for a file referenced by IMGPROXY_PRESETS_PATH, supporting comments and one definition per line.

```text
default=resizing_type:fill/enlarge:1  

  

# Sharpen the image to make it look better  

sharp=sharpen:0.7  

  

# Blur the image to hide details  

blurry=blur:2  


```

--------------------------------

### Constructing a signed imgproxy URL

Source: https://docs.imgproxy.net/usage/processing

Example of a signed URL using a preset, resizing, smart gravity, and PNG conversion.

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

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

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

--------------------------------

### Install RPM package

Source: https://docs.imgproxy.net/installation

Install an RPM package on RHEL, Fedora, or CentOS systems.

```bash
sudo rpm -i imgproxy-4.0.0.arm64.rpm
```

--------------------------------

### Deploy imgproxy with Helm

Source: https://docs.imgproxy.net/installation

Add the official Helm repository and install imgproxy on a Kubernetes cluster.

```bash
helm repo add imgproxy https://helm.imgproxy.net/  

  

# With Helm 3  

helm upgrade -i imgproxy imgproxy/imgproxy  

  

# With Helm 2  

helm upgrade -i --name imgproxy imgproxy/imgproxy  
```

--------------------------------

### Example URL in presets-only mode

Source: https://docs.imgproxy.net/configuration/options

A sample URL structure when IMGPROXY_ONLY_PRESETS is enabled, restricting processing options to defined presets.

```text
http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png
```

--------------------------------

### Install DEB package

Source: https://docs.imgproxy.net/installation

Install a DEB package on Debian or Ubuntu systems and resolve missing dependencies.

```bash
sudo dpkg -i imgproxy-4.0.0.arm64.deb
```

```bash
sudo apt-get install -f
```

--------------------------------

### Configure URL replacements

Source: https://docs.imgproxy.net/configuration/options

Examples of pattern-based URL replacement rules using IMGPROXY_URL_REPLACEMENTS.

```text
mys3://=s3://my_bucket/images/
```

```text
mys3://*/=s3://my_bucket/${1}/images
```

--------------------------------

### SEO-friendly URL structure

Source: https://docs.imgproxy.net/configuration/options

Example of an imgproxy URL with an appended filename when IMGPROXY_BASE64_URL_INCLUDES_FILENAME is enabled.

```text
https://my-imgproxy.dev/.../aHR0cDovL2V4YW1wbGUuY29tL3B1cHB5LmpwZw/puppy.jpg
```

--------------------------------

### Enable jemalloc via LD_PRELOAD

Source: https://docs.imgproxy.net/memory_usage_tweaks

Installs and enables jemalloc to improve memory fragmentation and concurrency support on Debian-based systems.

```bash
sudo apt-get install libjemalloc2

LD_PRELOAD='/usr/lib/x86_64-linux-gnu/libjemalloc.so.2' imgproxy
```

--------------------------------

### Enable TCMalloc via LD_PRELOAD

Source: https://docs.imgproxy.net/memory_usage_tweaks

Installs and enables Google's TCMalloc for faster multi-threaded memory allocation on Debian-based systems.

```bash
sudo apt-get install libtcmalloc-minimal4

LD_PRELOAD='/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4' imgproxy
```

--------------------------------

### GET /health

Source: https://docs.imgproxy.net/healthcheck

Returns the health status of the imgproxy server.

```APIDOC
## GET /health

### Description
Returns an HTTP Status of 200 OK if the server has been successfully started. This endpoint is intended for use with container orchestration systems like Kubernetes for readiness and liveness probes.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **Status** (integer) - Returns 200 OK if the server is healthy.
```

--------------------------------

### GET Image Processing

Source: https://docs.imgproxy.net/usage/processing

The primary method for processing images is to send a GET request to the imgproxy server with a URL path containing the signature, processing options, and the source image URL.

```APIDOC
## GET /%signature/%processing_options/%source_url

### Description
Processes an image based on the provided signature, processing options, and source URL. The request returns the processed image file.

### Method
GET

### Endpoint
/%signature/%processing_options/%source_url

### Parameters
#### Path Parameters
- **signature** (string) - Required - A security signature to protect the URL from unauthorized alteration.
- **processing_options** (string) - Required - A slash-separated list of image processing operations (e.g., resize, width, height).
- **source_url** (string) - Required - The URL of the source image to be processed. Can be plain, encoded, or encrypted.
```

--------------------------------

### Specify page for pagination or animation

Source: https://docs.imgproxy.net/usage/processing

Selects a specific page from a multi-page source like PDF, TIFF, or animated formats. Page numbering starts at zero.

```text
page:%page  

pg:%page  
```

--------------------------------

### Build imgproxy on Ubuntu

Source: https://docs.imgproxy.net/installation

Compile the imgproxy binary from source using the Go toolchain.

```bash
CGO_LDFLAGS_ALLOW="-s|-w" \

  go build -o /usr/local/bin/imgproxy ./cli  


```

--------------------------------

### Build and run a custom Docker image

Source: https://docs.imgproxy.net/installation

Build a local image using the provided Dockerfile and run it.

```bash
docker build -f docker/Dockerfile -t imgproxy .  

docker run -p 8080:8080 -it imgproxy  
```

--------------------------------

### Clone imgproxy source code

Source: https://docs.imgproxy.net/installation

Use git to clone the repository and enter the directory.

```bash
git clone https://github.com/imgproxy/imgproxy.git  

cd imgproxy  


```

--------------------------------

### Deploy imgproxy to Heroku manually

Source: https://docs.imgproxy.net/installation

Clone the repository and deploy the application to Heroku using the container stack.

```bash
git clone https://github.com/imgproxy/imgproxy.git && cd imgproxy  

heroku create your-application  

heroku stack:set container  

git push heroku master  
```

--------------------------------

### Provide a plain source URL

Source: https://docs.imgproxy.net/usage/processing

Use the /plain/ prefix for standard URLs. Ensure special characters are percent-encoded or replaced as specified.

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

--------------------------------

### Deploy specific imgproxy version to Heroku

Source: https://docs.imgproxy.net/installation

Use the Heroku Container Registry to push a specific version of the imgproxy image.

```bash
heroku create your-application  

heroku stack:set container -a your-application  

heroku container:login  

# Replace "v4" with the imgproxy version you want to deploy  

docker pull ghcr.io/imgproxy/imgproxy:v4-amd64  

docker tag ghcr.io/imgproxy/imgproxy:v4-amd64 registry.heroku.com/your-application/web  

docker push registry.heroku.com/your-application/web  

heroku container:release web -a your-application  
```

--------------------------------

### Build Linux packages from Docker

Source: https://docs.imgproxy.net/installation

Use the imgproxy-build-package script to export DEB, RPM, or TAR packages from a Docker image.

```bash
docker run -u0 --rm -it -v $(pwd):/dist ghcr.io/imgproxy/imgproxy:latest-amd64 imgproxy-build-package deb /dist
```

--------------------------------

### Quality processing option

Source: https://docs.imgproxy.net/usage/processing

Sets the output image quality as a percentage.

```text
quality:%quality  

q:%quality  
```

--------------------------------

### Download imgproxy source tarball

Source: https://docs.imgproxy.net/installation

Download and extract the source code tarball for the master branch or a specific version.

```bash
mkdir imgproxy  

cd imgproxy  

curl -Ls https://github.com/imgproxy/imgproxy/archive/master.tar.gz \

  | tar -xz --strip-components 1 -C .  


```

```bash
mkdir imgproxy  

cd imgproxy  

curl -Ls https://github.com/imgproxy/imgproxy/archive/v4.0.0.tar.gz \

  | tar -xz --strip-components 1 -C .  


```

--------------------------------

### Return Attachment Option

Source: https://docs.imgproxy.net/usage/processing

Forces the browser to open a 'Save as' dialog by setting the Content-Disposition header.

```text
return_attachment:%return_attachment  

att:%return_attachment  
```

--------------------------------

### Preset

Source: https://docs.imgproxy.net/usage/processing

Defines a list of presets to be used by imgproxy.

```APIDOC
## Preset

### Description
Defines a list of presets to be used by imgproxy. Multiple presets can be used in a single URL.

### Syntax
preset:%preset_name1:%preset_name2:...:%preset_nameN
pr:%preset_name1:%preset_name2:...:%preset_nameN
```

--------------------------------

### Plain Source URL

Source: https://docs.imgproxy.net/usage/processing

Provides a direct source URL to imgproxy by prepending the /plain/ segment. The URL should be percent-encoded.

```APIDOC
## GET /plain/[source_url]

### Description
Processes an image from a plain source URL. The source URL must be percent-encoded.

### Endpoint
/plain/[source_url]

### Parameters
#### Path Parameters
- **source_url** (string) - Required - The URL of the source image, percent-encoded.
```

--------------------------------

### Specify resulting image format

Source: https://docs.imgproxy.net/usage/processing

Sets the output image format, acting as an alias for the extension part of the URL.

```text
format:%extension  

f:%extension  

ext:%extension  
```

--------------------------------

### Provide an AES-CBC encrypted source URL

Source: https://docs.imgproxy.net/usage/processing

Use the /enc/ prefix for AES-CBC encrypted URLs, which can be split with forward slashes.

```text
/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog
```

--------------------------------

### Specify extension for plain source URL

Source: https://docs.imgproxy.net/usage/processing

Append the desired extension after an @ symbol when using a plain source URL.

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

--------------------------------

### Width option

Source: https://docs.imgproxy.net/usage/processing

Sets the width of the resulting image.

```text
width:%width  

w:%width  
```

--------------------------------

### Height option

Source: https://docs.imgproxy.net/usage/processing

Sets the height of the resulting image.

```text
height:%height  

h:%height  
```

--------------------------------

### Max Source File Size

Source: https://docs.imgproxy.net/usage/processing

Redefines the maximum source file size limit; requires IMGPROXY_ALLOW_SECURITY_OPTIONS to be enabled.

```text
max_src_file_size:%size  

msfs:%size  
```

--------------------------------

### Adjust Meta-Option

Source: https://docs.imgproxy.net/usage/processing

Defines brightness, contrast, and saturation in a single meta-option.

```text
adjust:%brightness:%contrast:%saturation  

a:%brightness:%contrast:%saturation  
```

--------------------------------

### Redefine video thumbnail second

Source: https://docs.imgproxy.net/usage/processing

Overrides the IMGPROXY_VIDEO_THUMBNAIL_SECOND configuration for video processing.

```text
video_thumbnail_second:%second  

vts:%second  
```

--------------------------------

### Provide a Base64 encoded source URL

Source: https://docs.imgproxy.net/usage/processing

Use URL-safe Base64 encoding for the source URL, which can be split with forward slashes.

```text
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn
```

--------------------------------

### Background

Source: https://docs.imgproxy.net/usage/processing

Fills the resulting image background with the specified color.

```APIDOC
## Background

### Syntax
`background:%R:%G:%B` or `bg:%R:%G:%B` or `background:%hex_color` or `bg:%hex_color`

### Parameters
- **R, G, B** (number) - Optional - Red, Green, Blue channel values (0-255)
- **hex_color** (string) - Optional - Hex-coded color value
```

--------------------------------

### Define WebP saving options

Source: https://docs.imgproxy.net/usage/processing

Redefines WebP saving options with optional compression, subsampling, and preset parameters.

```text
webp_options:%compression:%smart_subsample:%preset  

webpo:%compression:%smart_subsample:%preset  
```

--------------------------------

### Return Attachment

Source: https://docs.imgproxy.net/usage/processing

Forces the browser to open a 'Save as' dialog by setting the Content-Disposition header.

```APIDOC
## Return Attachment

### Description
When set to 1, t or true, imgproxy will return attachment in the Content-Disposition header, and the browser will open a 'Save as' dialog.

### Syntax
return_attachment:%return_attachment
att:%return_attachment
```

--------------------------------

### Filename

Source: https://docs.imgproxy.net/usage/processing

Defines the filename for the Content-Disposition header, optionally using Base64 encoding.

```text
filename:%filename:%encoded  

fn:%filename:%encoded  
```

--------------------------------

### Generate random key/salt pair

Source: https://docs.imgproxy.net/configuration/options

Use this command to quickly generate a random hex-encoded key or salt for URL signature configuration.

```bash
echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
```

--------------------------------

### Resizing algorithm option

Source: https://docs.imgproxy.net/usage/processing

Specifies the algorithm used for image resizing.

```text
resizing_algorithm:%algorithm  

ra:%algorithm  
```

--------------------------------

### Hashsum Pro

Source: https://docs.imgproxy.net/usage/processing

Calculates and validates the hashsum of the source image.

```APIDOC
## Hashsum Pro

### Description
imgproxy will calculate the hashsum of the source image and compare it with the provided hashsum. If they don't match, imgproxy will respond with 422.

### Syntax
hashsum:%hashsum_type:%hashsum
hs:%hashsum_type:%hashsum

### Parameters
- **hashsum_type**: none, md5, sha1, sha256, sha512
- **hashsum**: the expected hex-encoded hashsum
```

--------------------------------

### WebP Options

Source: https://docs.imgproxy.net/usage/processing

Redefines WebP saving options.

```APIDOC
## WebP Options

### Description
Allows redefining WebP saving options. All arguments are optional.

### Parameters
- **compression** (string) - Optional
- **smart_subsample** (boolean) - Optional
- **preset** (string) - Optional
```

--------------------------------

### Max Source Resolution

Source: https://docs.imgproxy.net/usage/processing

Redefines the maximum source resolution limit; requires IMGPROXY_ALLOW_SECURITY_OPTIONS to be enabled.

```text
max_src_resolution:%resolution  

msr:%resolution  
```

--------------------------------

### Minimum width option

Source: https://docs.imgproxy.net/usage/processing

Defines the minimum width for the resulting image.

```text
min-width:%width  

mw:%width  
```

--------------------------------

### Apply Duotone

Source: https://docs.imgproxy.net/usage/processing

Converts the image to duotone using intensity and two base colors for dark and light areas.

```text
duotone:%intensity:%color1:%color2  

dt:%intensity:%color1:%color2  
```

--------------------------------

### Expires

Source: https://docs.imgproxy.net/usage/processing

Sets a Unix timestamp after which the request will return a 404 error.

```text
expires:%timestamp  

exp:%timestamp  
```

--------------------------------

### Define PNG saving options

Source: https://docs.imgproxy.net/usage/processing

Redefines PNG saving options with optional interlacing and quantization parameters.

```text
png_options:%interlaced:%quantize:%quantization_colors  

pngo:%interlaced:%quantize:%quantization_colors  
```

--------------------------------

### Apply Monochrome

Source: https://docs.imgproxy.net/usage/processing

Converts the image to monochrome based on intensity and an optional base color.

```text
monochrome:%intensity:%color  

mc:%intensity:%color  
```

--------------------------------

### Processing Options

Source: https://docs.imgproxy.net/usage/processing

A collection of processing options that can be passed to imgproxy to modify image output.

```APIDOC
## Processing Options

### Strip metadata
- **strip_metadata** (boolean) - Optional - Strip EXIF, IPTC, etc. metadata.
- **sm** (boolean) - Alias for strip_metadata.

### Keep copyright
- **keep_copyright** (boolean) - Optional - Keep copyright info when stripping metadata.
- **kcr** (boolean) - Alias for keep_copyright.

### DPI
- **dpi** (integer) - Optional - Replace image DPI metadata.

### Strip color profile
- **strip_color_profile** (boolean) - Optional - Transform ICC profile to sRGB and remove it.
- **scp** (boolean) - Alias for strip_color_profile.

### Preserve HDR
- **preserve_hdr** (boolean) - Optional - Keep high bit depth or downscale to 8 bit.
- **ph** (boolean) - Alias for preserve_hdr.

### Color profile
- **color_profile** (string) - Optional - Convert colorspace using 'srgb', 'cmyk', or a custom profile filename.
- **cp** (string) - Alias for color_profile.
- **icc** (string) - Alias for color_profile.

### Enforce thumbnail
- **enforce_thumbnail** (boolean) - Optional - Use embedded thumbnail if available (HEIC/AVIF).
- **eth** (boolean) - Alias for enforce_thumbnail.

### Quality
- **quality** (integer) - Optional - Redefine image quality percentage.
- **q** (integer) - Alias for quality.

### Format quality
- **format_quality** (string) - Optional - Set quality per format (e.g., format1:quality1:format2:quality2).
- **fq** (string) - Alias for format_quality.

### Autoquality
- **autoquality** (string) - Optional - Configure autoquality settings (method:target:min_quality:max_quality:allowed_error).
- **aq** (string) - Alias for autoquality.

### Max bytes
- **max_bytes** (integer) - Optional - Degrade quality until image size is under specified bytes.
- **mb** (integer) - Alias for max_bytes.

### JPEG options
- **jpeg_options** (string) - Optional - Redefine JPEG saving options (progressive:no_subsample:trellis_quant:overshoot_deringing:optimize_scans:quant_table).
- **jpgo** (string) - Alias for jpeg_options.
```

--------------------------------

### Padding

Source: https://docs.imgproxy.net/usage/processing

Defines padding size using CSS-style syntax. Padded space is filled according to the background option.

```APIDOC
## Padding

### Syntax
`padding:%top:%right:%bottom:%left` or `pd:%top:%right:%bottom:%left`

### Parameters
- **top** (number) - Optional - Top padding (and for all other sides if they haven't been explicitly set)
- **right** (number) - Optional - Right padding (and left if it hasn't been explicitly set)
- **bottom** (number) - Optional - Bottom padding
- **left** (number) - Optional - Left padding
```

--------------------------------

### Video Thumbnail Tile

Source: https://docs.imgproxy.net/usage/processing

Generates a tiled sprite using source video frames.

```APIDOC
## Video Thumbnail Tile

### Description
Generates a tiled sprite using the source video frames when step is not 0.

### Parameters
- **step** (float) - Required
- **columns** (integer) - Required
- **rows** (integer) - Required
- **tile_width** (integer) - Required
- **tile_height** (integer) - Required
- **extend_tile** (boolean) - Optional
- **trim** (boolean) - Optional
- **fill** (boolean) - Optional
- **focus_x** (float) - Optional
- **focus_y** (float) - Optional
```

--------------------------------

### Redefine video thumbnail keyframes

Source: https://docs.imgproxy.net/usage/processing

Overrides the IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES configuration for video processing.

```text
video_thumbnail_keyframes:%keyframes  

vtk:%keyframes  
```

--------------------------------

### Minimum height option

Source: https://docs.imgproxy.net/usage/processing

Defines the minimum height for the resulting image.

```text
min-height:%height  

mh:%height  
```

--------------------------------

### Security Restrictions

Source: https://docs.imgproxy.net/usage/processing

Options to redefine security configurations, requiring IMGPROXY_ALLOW_SECURITY_OPTIONS to be true.

```APIDOC
## Security Restrictions

### Description
These options allow redefining global security configurations. Usage is only allowed if IMGPROXY_ALLOW_SECURITY_OPTIONS is set to true.

### Options
- **Max src resolution**: max_src_resolution:%resolution (msr:%resolution)
- **Max src file size**: max_src_file_size:%size (msfs:%size)
- **Max animation frames**: max_animation_frames:%size (maf:%size)
- **Max animation frame resolution**: max_animation_frame_resolution:%size (mafr:%size)
- **Max result dimension**: max_result_dimension:%size (mrd:%size)
```

--------------------------------

### Generate video thumbnail sprite

Source: https://docs.imgproxy.net/usage/processing

Creates a tiled sprite from video frames based on the provided step, dimensions, and layout parameters.

```text
video_thumbnail_tile:%step:%columns:%rows:%tile_width:%tile_height:%extend_tile:%trim:%fill:%focus_x:%focus_y  

vtt:%step:%columns:%rows:%tile_width:%tile_height:%extend_tile:%trim:%fill:%focus_x:%focus_y  
```

--------------------------------

### Resize processing option

Source: https://docs.imgproxy.net/usage/processing

Meta-option for defining resizing type, dimensions, and scaling behavior.

```text
resize:%resizing_type:%width:%height:%enlarge:%extend  

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

--------------------------------

### Constructing imgproxy request URLs

Source: https://docs.imgproxy.net/usage/processing

The base structure for imgproxy request URLs using plain, encoded, or encrypted source URLs.

```text
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  
```

--------------------------------

### Configure Unsharp Masking

Source: https://docs.imgproxy.net/usage/processing

Redefines unsharp masking options using mode, weight, and divider parameters.

```text
unsharp_masking:%mode:%weight:%divider

ush:%mode:%weight:%divider
```

--------------------------------

### Page and Pages

Source: https://docs.imgproxy.net/usage/processing

Controls pagination for multi-page or animated source images.

```APIDOC
## Page

### Description
Specifies the page to use for multi-page or animated sources. Starts from zero.

### Parameters
- **page** (integer) - Required

## Pages

### Description
Specifies the number of pages to use, stacked vertically.

### Parameters
- **pages** (integer) - Required
```

--------------------------------

### Trim

Source: https://docs.imgproxy.net/usage/processing

Removes surrounding background from the image.

```APIDOC
## trim:%threshold:%color:%equal_hor:%equal_ver

### Description
Removes surrounding background based on color similarity.

### Parameters
- **threshold** (number) - Required - Color similarity tolerance.
- **color** (string) - Optional - Hex-coded value of the color to cut off.
- **equal_hor** (boolean) - Optional - If true, cuts equal parts from left and right sides.
- **equal_ver** (boolean) - Optional - If true, cuts equal parts from top and bottom sides.
```

--------------------------------

### Style

Source: https://docs.imgproxy.net/usage/processing

Prepends a style node to an SVG image.

```APIDOC
## Style

### Description
Prepends a <style> node with the provided content to the <svg> node of a source SVG image.

### Syntax
style:%style
st:%style

### Parameters
- **style** (string) - Required - URL-safe Base64-encoded CSS-styles.
```

--------------------------------

### Specify number of pages

Source: https://docs.imgproxy.net/usage/processing

Defines the number of pages to use from a multi-page source, which are then stacked vertically.

```text
pages:%pages  

pgs:%pages  
```

--------------------------------

### Apply Color Overlay

Source: https://docs.imgproxy.net/usage/processing

Places a color overlay on the image with configurable opacity and alpha channel preservation.

```text
colorize:%opacity:%color:%keep_alpha

col:%opacity:%color:%keep_alpha
```

--------------------------------

### AVIF Options

Source: https://docs.imgproxy.net/usage/processing

Redefines AVIF saving options.

```APIDOC
## AVIF Options

### Description
Allows redefining AVIF saving options.

### Parameters
- **subsample** (string) - Optional
```

--------------------------------

### Draw Object Detections

Source: https://docs.imgproxy.net/usage/processing

Draws bounding boxes, class labels, and confidence scores for detected objects.

```text
draw_detections:%draw:%class_name1:%class_name2:...:%class_nameN

dd:%draw:%class_name1:%class_name2:...:%class_nameN
```

--------------------------------

### Calculate Base64 fallback image data

Source: https://docs.imgproxy.net/configuration/options

Command to generate the base64 string required for the IMGPROXY_FALLBACK_IMAGE_DATA environment variable.

```bash
base64 tmp/fallback.png | tr -d '\n'
```

--------------------------------

### Size processing option

Source: https://docs.imgproxy.net/usage/processing

Meta-option for defining dimensions and scaling behavior.

```text
size:%width:%height:%enlarge:%extend  

s:%width:%height:%enlarge:%extend  
```

--------------------------------

### DPI processing option

Source: https://docs.imgproxy.net/usage/processing

Sets or overrides the DPI metadata of the output image.

```text
dpi:%dpi  
```

--------------------------------

### Configure Docker Compose health check

Source: https://docs.imgproxy.net/healthcheck

Use the imgproxy health command within a Docker Compose healthcheck configuration to monitor server status.

```yaml
healthcheck:  

  test: [ "CMD", "imgproxy", "health" ]  

  timeout: "10s"  

  interval: "10s"  

  retries: 3  
```

--------------------------------

### Color profile processing option

Source: https://docs.imgproxy.net/usage/processing

Converts the image colorspace to a specified profile and embeds it.

```text
color_profile:%profile  

cp:%profile  

icc:%profile  
```

--------------------------------

### Specify extension for Base64 encoded source URL

Source: https://docs.imgproxy.net/usage/processing

Append the extension after a dot when using a Base64 encoded source URL.

```text
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
```

--------------------------------

### Format

Source: https://docs.imgproxy.net/usage/processing

Specifies the resulting image format.

```APIDOC
## Format

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

### Parameters
- **extension** (string) - Required
```

--------------------------------

### Apply Padding

Source: https://docs.imgproxy.net/usage/processing

Defines padding size using CSS-style syntax. Padding is applied after transformations and enlarges the image.

```text
padding:%top:%right:%bottom:%left  

pd:%top:%right:%bottom:%left  
```

--------------------------------

### PNG Options

Source: https://docs.imgproxy.net/usage/processing

Redefines PNG saving options including interlacing and quantization.

```APIDOC
## PNG Options

### Description
Allows redefining PNG saving options. All arguments are optional.

### Parameters
- **interlaced** (boolean) - Optional
- **quantize** (boolean) - Optional
- **quantization_colors** (integer) - Optional
```

--------------------------------

### Specify extension for encrypted source URL

Source: https://docs.imgproxy.net/usage/processing

Append the extension after a dot when using an encrypted source URL.

```text
/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog.png
```

--------------------------------

### Filename

Source: https://docs.imgproxy.net/usage/processing

Defines the filename for the Content-Disposition header.

```APIDOC
## filename (fn)

### Description
Sets the filename for the Content-Disposition header.

### Parameters
- **filename** (string) - Required - Escaped or URL-safe Base64-encoded filename.
- **encoded** (boolean) - Optional - Identifies if the filename is Base64-encoded.
```

--------------------------------

### Defining processing options

Source: https://docs.imgproxy.net/usage/processing

Standard format for processing options and the alternative format when using a custom separator.

```text
%option_name:%argument1:%argument2:...:%argumentN  
```

```text
%option_name,%argument1,%argument2,...,%argumentN  
```

--------------------------------

### Preset Option

Source: https://docs.imgproxy.net/usage/processing

Defines a list of presets to be applied to the image processing request.

```text
preset:%preset_name1:%preset_name2:...:%preset_nameN  

pr:%preset_name1:%preset_name2:...:%preset_nameN  
```

--------------------------------

### Format quality processing option

Source: https://docs.imgproxy.net/usage/processing

Defines quality settings for specific output formats.

```text
format_quality:%format1:%quality1:%format2:%quality2:...:%formatN:%qualityN  

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

--------------------------------

### Apply Gradient

Source: https://docs.imgproxy.net/usage/processing

Places a gradient on the processed image transitioning from transparency to a specified color.

```text
gradient:%opacity:%color:%direction:%start:%stop  

gr:%opacity:%color:%direction:%start:%stop  
```

--------------------------------

### Raw

Source: https://docs.imgproxy.net/usage/processing

Streams the source image directly without processing, checking, or memory buffering.

```APIDOC
## raw

### Description
Responds with a raw, unprocessed, and unchecked source image. Bypasses type, resolution, and file size checks.
```

--------------------------------

### Autoquality processing option

Source: https://docs.imgproxy.net/usage/processing

Configures automatic quality adjustment settings.

```text
autoquality:%method:%target:%min_quality:%max_quality:%allowed_error  

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

--------------------------------

### Set device pixel ratio

Source: https://docs.imgproxy.net/usage/processing

Multiplies image dimensions for HiDPI devices. Affects offsets and padding.

```text
dpr:%dpr  
```

--------------------------------

### Resizing type option

Source: https://docs.imgproxy.net/usage/processing

Defines the strategy for resizing the source image.

```text
resizing_type:%resizing_type  

rt:%resizing_type  
```

--------------------------------

### Hashsum Verification

Source: https://docs.imgproxy.net/usage/processing

Verifies the source image against a provided hashsum to ensure integrity.

```text
hashsum:%hashsum_type:%hashsum  

hs:%hashsum_type:%hashsum  
```

--------------------------------

### Extract TAR package

Source: https://docs.imgproxy.net/installation

Extract a TAR package to a specific directory on the system.

```bash
tar -xzf imgproxy-4.0.0.arm64.tar.gz -C /opt
```

--------------------------------

### Adjust Contrast

Source: https://docs.imgproxy.net/usage/processing

Adjusts image contrast using a positive floating point number.

```text
contrast:%contrast  

co:%contrast  
```

--------------------------------

### Configure Objects Position

Source: https://docs.imgproxy.net/usage/processing

Adjusts the position of detected objects when using obj/objw gravity. Use the focus point (fp) or proportional (prop) variants for advanced positioning.

```text
objects_position:%type:%x_offset:%y_offset

obj_pos:%type:%x_offset:%y_offset

op:%type:%x_offset:%y_offset
```

--------------------------------

### Video thumbnail animation

Source: https://docs.imgproxy.net/usage/processing

Generates an animated image from video frames based on the provided step, delay, and frame dimensions.

```APIDOC
## video_thumbnail_animation (vta)

### Description
Generates an animated image using source video frames when step is not 0.

### Parameters
- **step** (number) - Required - The step of timestamp (in seconds) between video frames.
- **delay** (number) - Required - The delay between animation frames in milliseconds.
- **frames** (number) - Required - The number of animation frames.
- **frame_width** (number) - Required - The width of animation frames.
- **frame_height** (number) - Required - The height of animation frames.
- **extend_frame** (boolean) - Optional - Extend each animation frame to the requested size using a black background.
- **trim** (boolean) - Optional - Trim unused frames from the animation.
- **fill** (boolean) - Optional - Use the fill resizing type for animation frames.
- **focus_x** (number) - Optional - X coordinate of the center of the animation frame (0 to 1).
- **focus_y** (number) - Optional - Y coordinate of the center of the animation frame (0 to 1).
```

--------------------------------

### Set Watermark URL

Source: https://docs.imgproxy.net/usage/processing

Uses an image from a URL-safe Base64-encoded URL as a watermark.

```text
watermark_url:%url  

wmu:%url  
```

--------------------------------

### Configure image gravity

Source: https://docs.imgproxy.net/usage/processing

Defines the anchor point for cropping or positioning, supporting standard, smart, and object-oriented gravity types.

```text
gravity:%type:%x_offset:%y_offset  

g:%type:%x_offset:%y_offset  
```

--------------------------------

### Video thumbnail animation

Source: https://docs.imgproxy.net/usage/processing

Generates an animated image from video frames. Requires specifying step, delay, frame count, and dimensions.

```text
video_thumbnail_animation:%step:%delay:%frames:%frame_width:%frame_height:%extend_frame:%trim:%fill:%focus_x:%focus_y  

vta:%step:%delay:%frames:%frame_width:%frame_height:%extend_frame:%trim:%fill:%focus_x:%focus_y  
```

--------------------------------

### Extend image aspect ratio

Source: https://docs.imgproxy.net/usage/processing

Extends the image to match the requested aspect ratio.

```text
extend_aspect_ratio:%extend:%gravity  

extend_ar:%extend:%gravity  

exar:%extend:%gravity  
```

--------------------------------

### Set Background Color

Source: https://docs.imgproxy.net/usage/processing

Fills the image background with a specified RGB or hex color, useful for alpha-channel conversion.

```text
background:%R:%G:%B  

bg:%R:%G:%B  

  

background:%hex_color  

bg:%hex_color  
```

--------------------------------

### Define AVIF saving options

Source: https://docs.imgproxy.net/usage/processing

Redefines AVIF saving options with an optional subsampling parameter.

```text
avif_options:%subsample  

avifo:%subsample  
```

--------------------------------

### Apply Watermark

Source: https://docs.imgproxy.net/usage/processing

Places a watermark on the processed image with configurable opacity, position, and scaling.

```text
watermark:%opacity:%position:%x_offset:%y_offset:%scale  

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

--------------------------------

### Max bytes processing option

Source: https://docs.imgproxy.net/usage/processing

Automatically degrades image quality to ensure the file size remains under the specified limit.

```text
max_bytes:%bytes  

mb:%bytes  
```

--------------------------------

### Adjust Saturation

Source: https://docs.imgproxy.net/usage/processing

Adjusts image saturation using a positive floating point number.

```text
saturation:%saturation  

sa:%saturation  
```

--------------------------------

### Set Watermark Size

Source: https://docs.imgproxy.net/usage/processing

Defines the width and height of the watermark, effective when the watermark scale is set to zero.

```text
watermark_size:%width:%height  

wms:%width:%height  
```

--------------------------------

### Enable image enlargement

Source: https://docs.imgproxy.net/usage/processing

Enlarges the image if it is smaller than the target size when set to 1, t, or true.

```text
enlarge:%enlarge  

el:%enlarge  
```

--------------------------------

### Calculate Base64 Watermark Data

Source: https://docs.imgproxy.net/configuration/options

Command to generate the base64-encoded string required for the IMGPROXY_WATERMARK_DATA environment variable.

```bash
base64 tmp/watermark.png | tr -d '\n'
```

--------------------------------

### Skip processing

Source: https://docs.imgproxy.net/usage/processing

Skips processing for specific file extensions when the requested format matches the source format.

```text
skip_processing:%extension1:%extension2:...:%extensionN  

skp:%extension1:%extension2:...:%extensionN  
```

--------------------------------

### Extend image boundaries

Source: https://docs.imgproxy.net/usage/processing

Extends the image if it is smaller than the given size using specified gravity.

```text
extend:%extend:%gravity  

ex:%extend:%gravity  
```

--------------------------------

### JPEG options processing option

Source: https://docs.imgproxy.net/usage/processing

Allows customization of advanced JPEG compression parameters.

```text
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  
```

--------------------------------

### Auto Rotate

Source: https://docs.imgproxy.net/usage/processing

Automatically rotates images based on EXIF orientation metadata.

```text
auto_rotate:%auto_rotate  

ar:%auto_rotate  
```

--------------------------------

### Apply SVG Style

Source: https://docs.imgproxy.net/usage/processing

Prepends a style node with URL-safe Base64-encoded CSS to a source SVG image.

```text
style:%style  

st:%style  
```

--------------------------------

### Dpr

Source: https://docs.imgproxy.net/usage/processing

Multiplies the image dimensions for HiDPI (Retina) devices.

```APIDOC
## Dpr

### Description
Multiplies the image dimensions for HiDPI (Retina) devices. Affects gravity offsets, watermark offsets, and paddings.

### Parameters
- **dpr** (float) - Required - The device pixel ratio factor (must be > 0).
```

--------------------------------

### Max Animation Frame Resolution

Source: https://docs.imgproxy.net/usage/processing

Redefines the maximum resolution for animation frames; requires IMGPROXY_ALLOW_SECURITY_OPTIONS to be enabled.

```text
max_animation_frame_resolution:%size  

mafr:%size  
```

--------------------------------

### Raw processing

Source: https://docs.imgproxy.net/usage/processing

Streams the source image directly without processing, validation, or memory-intensive downloads.

```text
raw:%raw  
```

--------------------------------

### Skip processing

Source: https://docs.imgproxy.net/usage/processing

Skips processing for specific file extensions if the requested format matches the source format.

```APIDOC
## skip_processing (skp)

### Description
Skips processing of listed formats when the requested format is the same as the source format.

### Parameters
- **extensions** (string) - Required - List of extensions to skip, separated by colons.
```

--------------------------------

### Gradient

Source: https://docs.imgproxy.net/usage/processing

Places a gradient on the processed image that transitions from transparency to a specified color.

```APIDOC
## Gradient

### Description
Places a gradient on the processed image. The gradient transitions from transparency to the specified color.

### Syntax
gradient:%opacity:%color:%direction:%start:%stop
gr:%opacity:%color:%direction:%start:%stop

### Parameters
- **opacity** (float) - Required - Specifies gradient opacity. Set to 0 to disable.
- **color** (string) - Optional - Hex-coded value of the gradient color. Default: 000.
- **direction** (string/int) - Optional - Angle in degrees or string (down, up, right, left). Default: down.
- **start** (float) - Optional - Relative position where the gradient starts. Default: 0.0.
- **stop** (float) - Optional - Relative position where the gradient ends. Default: 1.0.
```

--------------------------------

### Watermark Size

Source: https://docs.imgproxy.net/usage/processing

Defines the width and height of the watermark.

```APIDOC
## Watermark Size

### Description
Defines the desired width and height of the watermark.

### Syntax
watermark_size:%width:%height
wms:%width:%height

### Parameters
- **width** (int) - Required - Width of the watermark.
- **height** (int) - Required - Height of the watermark.
```

--------------------------------

### Set image zoom factors

Source: https://docs.imgproxy.net/usage/processing

Multiplies image dimensions by the specified factors. Values must be greater than 0.

```text
zoom:%zoom_x_y  

z:%zoom_x_y  

  

zoom:%zoom_x:%zoom_y  

z:%zoom_x:%zoom_y  
```

--------------------------------

### Crop to Detected Objects

Source: https://docs.imgproxy.net/usage/processing

Automatically crops the image to fit around detected objects with an optional scale factor for padding.

```text
crop_objects:%scale_factor:%class_name1:%class_name2:...:%class_nameN

c_obj:%scale_factor:%class_name1:%class_name2:...:%class_nameN
```

--------------------------------

### Fallback image URL

Source: https://docs.imgproxy.net/usage/processing

Specifies a URL-safe Base64-encoded URL for a fallback image to be used if processing fails.

```text
fallback_image_url:%url  

fiu:%url  
```

--------------------------------

### Strip metadata processing option

Source: https://docs.imgproxy.net/usage/processing

Controls whether image metadata like EXIF or IPTC is removed from the output.

```text
strip_metadata:%strip_metadata  

sm:%strip_metadata  
```

--------------------------------

### Cache buster

Source: https://docs.imgproxy.net/usage/processing

Allows bypassing CDN, proxy, and browser caches by changing the URL string.

```APIDOC
## cachebuster (cb)

### Description
Used to bypass caches when settings change that are not reflected in the URL.

### Parameters
- **string** (string) - Required - Arbitrary string to bust the cache.
```

--------------------------------

### Flip

Source: https://docs.imgproxy.net/usage/processing

Flips the image along the specified axes.

```APIDOC
## Flip

### Syntax
`flip:%horizontal:%vertical` or `fl:%horizontal:%vertical`

### Parameters
- **horizontal** (boolean/string) - Optional - Flip horizontally (1, t, true)
- **vertical** (boolean/string) - Optional - Flip vertically (1, t, true)
```

--------------------------------

### Enlarge

Source: https://docs.imgproxy.net/usage/processing

Enlarges the image if it is smaller than the given size.

```APIDOC
## Enlarge

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

### Parameters
- **enlarge** (boolean) - Required - Whether to enable enlargement.
```

--------------------------------

### Set Watermark Text

Source: https://docs.imgproxy.net/usage/processing

Generates a watermark image from URL-safe Base64-encoded text.

```text
watermark_text:%text  

wmt:%text  
```

--------------------------------

### Cache buster

Source: https://docs.imgproxy.net/usage/processing

Bypasses CDN and browser caches by appending a string that does not affect image processing.

```text
cachebuster:%string  

cb:%string  
```
Tokens:
Raw