Version: latest

Getting an image info pro

imgproxy can fetch and return a source image info without downloading the whole image: just send an HTTP GET request to the imgproxy's /info endpoint and imgproxy will respond with a JSON containing the image info.

The request URL path should consist of the /info prefix, a signature, info options, and a source URL, like this:

http://imgproxy.example.com/info/%signature/%info_options/plain/%source_url
http://imgproxy.example.com/info/%signature/%info_options/%encoded_source_url
http://imgproxy.example.com/info/%signature/%info_options/enc/%encrypted_source_url

Signature

warning

The signature part should always be present in a URL. If the signature check is disabled (no key/salt pairs are provided), the signature part may contain anything (for example, unsafe or _).

A signature protects your URL from being modified by an attacker. It is highly recommended to sign imgproxy URLs in a production environment.

Once you set up your URL signature, check out the Signing the URL guide to learn about how to sign your URLs. Otherwise, since the signature is required, feel free to use any string here.

Info options

Info options should be specified as URL parts divided by slashes (/). An info option has the following format:

%option_name:%argument1:%argument2:...:%argumentN

tip

You can redefine the arguments separator with the the IMGPROXY_ARGUMENTS_SEPARATOR config. For example, if you set IMGPROXY_ARGUMENTS_SEPARATOR=",", info options will have the following format:

%option_name,%argument1,%argument2,...,%argumentN

Size

size:%size
s:%size

When set to 1, t, or true, imgproxy will return the size of the image file. If the source URL is an HTTP(s) URL, imgproxy will determine the file size based on the Content-Length HTTP header.

Default: true.

Response example:

{
  "size": 123456
}

Format

format:%format
f:%format

When set to 1, t, or true, imgproxy will return the image format.

info

For video files, imgproxy returns a list of predicted formats divided by comma.

Default: true.

Response example:

{
  "format": "jpeg"
}

Dimensions

dimensions:%dimensions
d:%dimensions

When set to 1, t, or true, imgproxy will return the image dimensions.

Default: true.

Response example:

{
  "width": 7360,
  "height": 4912
}

EXIF

exif:%exif

When set to 1, t, or true, imgproxy will return the image's EXIF metadata.

Default: true.

Response example:

{
  "exif": {
    "Aperture": "8.00 EV (f/16.0)",
    "Contrast": "Normal",
    "Date and Time": "2016:09:11 22:15:03",
    "Model": "NIKON D810",
    "Software": "Adobe Photoshop Lightroom 6.1 (Windows)"
  }
}

IPTC

iptc:%iptc

When set to 1, t, or true, imgproxy will return the image's IPTC (IPTC-IIM) metadata and Photoshop metadata (currently, only the resolution data).

Default: true.

Response example:

{
  "iptc": {
    "Name": "Spider-Man",
    "Caption": "Spider-Man swings on the web",
    "Copyright Notice": "Daily Bugle",
    "Keywords": ["spider-man", "menance", "offender"]
  },
  "photoshop": {
    "resolution": {
      "XResolution": 240,
      "XResolutionUnit": "inches",
      "WidthUnit": "inches",
      "YResolution": 240,
      "YResolutionUnit": "inches",
      "HeightUnit": "inches"
    }
  }
}

XMP

xmp:%xmp

When set to 1, t, or true, imgproxy will return the image's XMP metadata.

Default: true.

Response example:

{
  "xmp": {
    "aux": {
      "ApproximateFocusDistance": "4294967295/1",
      "ImageNumber": "16604",
      "Lens": "16.0-35.0 mm f/4.0",
      "LensID": "163",
      "LensInfo": "160/10 350/10 40/10 40/10",
      "SerialNumber": "12345678"
    },
    "dc": {
      "creator": ["Peter B. Parker"],
      "publisher": ["Daily Bugle"],
      "subject": ["spider-man", "menance", "offender"],
      "format": "image/jpeg"
    },
    "photoshop": {
      "DateCreated": "2016-09-11T18:44:50.003"
    }
  }
}

Video meta

video_meta:%video_meta
vm:%video_meta

When set to 1, t, or true, imgproxy will return the video metadata and video streams info.

Default: true.

Response example:

{
  "video_meta": {
    "com.android.version": "9",
    "compatible_brands": "isommp42",
    "creation_time": "2022-01-12T15:04:10.000000Z",
    "location": "+46.4845+030.6848/",
    "location-eng": "+46.4845+030.6848/",
    "major_brand": "mp42",
    "minor_version": "0"
  },
  "video_streams": [
    {
      "type": "video",
      "codec": "h264",
      "duration": 12.345,
      "bps": 16910024,
      "fps": 24,
      "language": "eng"
    },
    {
      "type": "audio",
      "codec": "eac3",
      "duration": 12.345,
      "bps": 768000,
      "frequency": 48000,
      "layout": "5.1(side)",
      "language": "eng"
    },
    {
      "type": "subtitle",
      "codec": "subrip",
      "language": "eng"
    }
  ]
}

Detect objects

Slow

This option requires the image to be fully downloaded and processed.

detect_objects:%detect_objects
do:%detect_objects

When set to 1, t, or true, imgproxy will return the info about the objects found in the image. Read the object detection manual to learn how to configure object detection.

info

imgproxy returns the relative coordinates of the found objects.

Default: false.

Response example:

{
  "objects": [
    {
      "class_id": 0,
      "class_name": "face",
      "confidence": 0.985792,
      "left": 0.6602726057171822,
      "top": 0.23434072732925415,
      "width": 0.11385439336299896,
      "height": 0.18671900033950806
    },
    {
      "class_id": 0,
      "class_name": "face",
      "confidence": 0.9810329,
      "left": 0.4354642778635025,
      "top": 0.3503067269921303,
      "width": 0.10691609978675842,
      "height": 0.18357203900814056
    }
  ]
}

Colorspace

Slow

This option requires the image to be fully downloaded.

colorspace:%colorspace
cs:%colorspace

When set to 1, t, or true, imgproxy will return the image's colorspace (srgb, cmyk, etc).

Default: false.

Response example:

{
  "colorspace": "srgb"
}

Bands

Slow

This option requires the image to be fully downloaded.

bands:%bands
b:%bands

When set to 1, t, or true, imgproxy will return the number image's bands.

Default: false.

Response example:

{
  "bands": 3
}

Sample format

Slow

This option requires the image to be fully downloaded.

sample_format:%sample_format
sf:%sample_format

When set to 1, t, or true, imgproxy will return the image's sample format (uchar, ushort, float, etc).

Default: false.

Response example:

{
  "sample_format": "uchar"
}

Pages number

Slow

This option requires the image to be fully downloaded.

pages_number:%pages_number
pn:%pages_number

When set to 1, t, or true, imgproxy will return the number of pages the image contains. For animated images, it'll return the number of animation frames.

Default: false.

Response example:

{
  "pages_number": 10
}

Alpha

Slow

This option requires the image to be fully downloaded and processed.

alpha:%alpha:%check_transparency
a:%alpha:%check_transparency

alpha – when set to 1, t, or true, imgproxy will check if the image has an alpha channel.
check_transparency – (optional) when set to 1, t, or true, imgproxy will additionally check if the image has actual transparency (pixels that have non-max alpha value).

Default: false:false.

Response example:

{
  "sample_format": "uchar"
}

Crop coordinates

Slow

This option requires the image to be fully downloaded and processed.

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

When width and height are greater than zero, imgproxy will return the relative crop coordinates for the defined crop parameters.

This option takes the same arguments as the crop processiong option.

Default: 0:0:ce.

Response example:

{
  "crop": {
    "left": 0.383203125,
    "top": 0.2603861907548274,
    "width": 0.1953125,
    "height": 0.3510825043885313
  }
}

Objcts position

objects_position:%type:%x_offset:%y_offset
obj_pos:%type:%x_offset:%y_offset
op:%type:%x_offset:%y_offset

When the crop info option is used with the obj/objw gravity type, the objects_position option allows you to adjust the position of the detected objects on the crop area.

This option takes the same arguments as the objects_position processiong option.

Default: ce:0:0

tip

If you need to get info about the objects position in the original image, you should use the detect_objects info option.

Palette

Slow

This option requires the image to be fully downloaded and processed.

palette:%colors
p:%colors

When colors is greater than zero, imgproxy will build and return the image's RGBA palette containing maximum colors colors.

info

When colors is greater than zero, its value should be between 2 and 256.

Default: 0.

Response example:

{
  "palette": [
    { "R": 189, "G": 178, "B": 169, "A": 255 },
    { "R": 83, "G": 79, "B": 67, "A": 255 }
  ]
}

Average color

Slow

This option requires the image to be fully downloaded and processed.

average:%average:%ignore_transparent
avg:%average:%ignore_transparent

average – when set to 1, t, or true, imgproxy will calculate and return the image's average color. Default: false
ignore_transparent – (optional) when set to 1, t, or true, imgproxy will ignore fully transparent pixels. Default: true

Default: false:true

Response example:

{
  "average": { "R": 139, "G": 132, "B": 121, "A": 255 }
}

Dominant colors

Slow

This option requires the image to be fully downloaded and processed.

dominant_colors:%dominant_colors:%build_missed
dc:%dominant_colors:%build_missed

dominant_colors – when set to 1, t, or true, imgproxy will calculate and return the image's dominant colors (vibrant, light vibrant, dark vibrant, muted, light muted, and dark muted). Default: false
build_missed – (optional) when set to 1, t, or true, imgproxy will build colors that were not found in the image based on the found ones. Default: false

Default: false:false

Response example:

{
  "dominant_colors": {
    "dark_muted": { "R": 75, "G": 70, "B": 57 },
    "dark_vibrant": { "R": 90, "G": 78, "B": 43 },
    "light_muted": { "R": 167, "G": 156, "B": 130 },
    "light_vibrant": { "R": 212, "G": 198, "B": 165 },
    "muted": { "R": 155, "G": 146, "B": 120 },
    "vibrant": { "R": 172, "G": 146, "B": 83 }
  }
}

BlurHash

Slow

This option requires the image to be fully downloaded and processed.

blurhash:%x_components:%y_components
bh:%x_components:%y_components

When x_components and y_components are greater than zero, imgproxy will calculate and return the image's BlurHash. x_components and y_components is the numbers of horizontal and vertical components of BlurHash. The larger the numbers the more "detailed" will be the BlurHash.

The maximum value for x_components and y_components is 9.

Default: 0:0

Response example:

{
  "blurhash": "LLH-}fox0fRQ%Do}9as9_3%2M{S2"
}

Calc hashsums

Slow

This option requires the image to be fully downloaded.

calc_hashsums:%hashsum_type1:%hashsum_type2:...:%hashsum_typeN
chs:%hashsum_type1:%hashsum_type2:...:%hashsum_typeN

When hashsum types list is not empty, imgproxy will calculate and return the hashsums of the source image. Available hashsum types are: md5, sha1, sha256, and sha512.

Default: empty

Response example:

{
  "hashsums": {
    "md5": "cc507f81206a4c7d0a995a07c3d9f43a",
    "sha256": "621f6c6d68de754c6cdf3d286b7837634ce9f273f30f377b3e0df0568a23cee0"
  }
}

warning

Calculation of video file hashsums is not supported as it would require downloading the whole video file. imgproxy won't throw an error if you try to calculate the hashsum of a video file but it will skip the hashsums field

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. Page numeration starts from zero.

Default: 0

Video thumbnail second

video_thumbnail_second:%second
vts:%second

Allows redefining IMGPROXY_VIDEO_THUMBNAIL_SECOND config.

Video thumbnail keyframes

video_thumbnail_keyframes:%keyframes
vtk:%keyframes

Allows redefining IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES config.

Cache buster

cachebuster:%string
cb:%string

Cache buster doesn't affect image processing but its 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

expires:%timestamp
exp:%timestamp

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

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

Hashsum

Slow

This option requires the image to be fully downloaded.

hashsum:%hashsum_type:%hashsum
hs:%hashsum_type:%hashsum

When hashtype is not none, 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.

hashsum_type: specifies the hashsum type. Available values:
- none: don't check the hashsum
- md5: use MD5 hashsum
- sha1: use SHA1 hashsum
- sha256: use SHA256 hashsum
- sha512: use SHA512 hashsum
hashsum: the expected hex-encoded hashsum of the source image. If hashsum_type is none, this argument is ignored and can be omitted

Default: none

warning

Checking video file hashsums is not supported as it would require downloading the whole video file. imgproxy won't throw an error if you try to check the hashsum of a video file but it will skip the hashsum check

Max src resolution

max_src_resolution:%resolution
msr:%resolution

Allows redefining IMGPROXY_MAX_SRC_RESOLUTION config.

warning

Since this option allows redefining a security restriction, its usage is not allowed unless the IMGPROXY_ALLOW_SECURITY_OPTIONS config is set to true.

Max src file size

max_src_file_size:%size
msfs:%size

Allows redefining IMGPROXY_MAX_SRC_FILE_SIZE config.

warning

Since this option allows redefining a security restriction, its usage is not allowed unless the IMGPROXY_ALLOW_SECURITY_OPTIONS config is set to true.

Source URL

Plain

The source URL can be provided as is, prepended by /plain/ part:

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

info

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

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

Encrypted with AES-CBC

The source URL can be encrypted with the AES-CBC algorithm, prepended by the /enc/ segment. The encrypted URL can be split with / as desired:

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

Signature​

Info options​

Size​

Format​

Dimensions​

EXIF​

IPTC​

XMP​

Video meta​

Detect objects​

Colorspace​

Bands​

Sample format​

Pages number​

Alpha​

Crop coordinates​

Objcts position​

Palette​

Average color​

Dominant colors​

BlurHash​

Calc hashsums​

Page​

Video thumbnail second​

Video thumbnail keyframes​

Cache buster​

Expires​

Preset​

Hashsum​

Max src resolution​

Max src file size​

Source URL​

Plain​

Base64 encoded​

Encrypted with AES-CBC​

Signature

Info options

Size

Format

Dimensions

EXIF

IPTC

XMP

Video meta

Detect objects

Colorspace

Bands

Sample format

Pages number

Alpha

Crop coordinates

Objcts position

Palette

Average color

Dominant colors

BlurHash

Calc hashsums

Page

Video thumbnail second

Video thumbnail keyframes

Cache buster

Expires

Preset

Hashsum

Max src resolution

Max src file size

Source URL

Plain

Base64 encoded

Encrypted with AES-CBC