NAV
http shell

Introduction

Welcome to the Imagizer Media Engine API! You can use this API to access Imagizer API endpoints.

Image API

The Image API allows for real-time image manipulation using parameters in the query string of the imagizer image URLs.

Scale

Width

GET /image.jpg?width=200 HTTP/1.1
curl "http://HOSTNAME/image.jpg?width=200" \
 -o output_image.jpg

Scale the image by width. The height will be calculated by the aspect ratio of the source image.

original
width=200

Height

GET /image.jpg?height=200 HTTP/1.1
curl "http://HOSTNAME/image.jpg?height=200" \
 -o output_image.jpg

Scale the image by height. the width will be calculated by the aspect ratio of the source image.

original
height=200

Crop

Fit

GET /image.jpg?width=200&height=200&crop=fit HTTP/1.1
curl "http://HOSTNAME/image.jpg?width=200&height=200&crop=fit" \
 -o output_image.jpg

Crops any excess image data outside the width and height boundaries after scaling. The output image will match exactly the dimensions given.

original
width=200&height=200&crop=fit

Top/Bottom

GET /image.jpg?width=200&height=200&crop=top HTTP/1.1
curl "http://HOSTNAME/image.jpg?width=200&height=200&crop=top" \
 -o output_image.jpg

Forces to keep either top or bottom part of the image when cropping any excess image data outside the width and height boundaries after scaling. The output image will match exactly the dimensions given.

width=200&height=200&crop=top
width=200&height=200&crop=bottom

Pad

GET /image.jpg?width=200&height=200&crop=pad&pad_color=abc HTTP/1.1
curl "http://HOSTNAME/image.jpg?width=200&height=200&crop=pad&pad_color=abc" \
 -o output_image.jpg

Resizes an image to the given dimensions and fills the extra space with pad_color. The default color is white.

original
width=200&height=200&crop=pad&pad_color=fff

Face

GET /image.jpg?crop=face HTTP/1.1
curl "http://HOSTNAME/image.jpg?crop=face" \
 -o output_image.jpg

Crops out image data around any faces detected in the image.

original
crop=face

Face padding

GET /image.jpg?width=300&height=300&crop=face HTTP/1.1
curl "http://HOSTNAME/image.jpg?width=300&height=300&crop=face" \
 -o output_image.jpg

Specifying width and height will pad or crop the face image to fit within the dimensions given.

crop=face&width=300&height=300

Entropy

GET /image.jpg?crop=entropy HTTP/1.1
curl "http://HOSTNAME/image.jpg?crop=entropy" \
 -o output_image.jpg

Entropy crop will find and return the most interesting features of the source image, cropping out less important areas.

original
crop=entropy

Custom

GET /image.jpg?crop=65,190,150,150 HTTP/1.1
curl "http://HOSTNAME/image.jpg?crop=65,190,150,150" \
 -o output_image.jpg

Custom crop allows for specifying a sub-region of the source image to be returned The value is 4 numbers representing x, y, width, and height separated using commas

original
crop=65,190,150,150
GET /image.jpg?crop=center,center,150,150 HTTP/1.1
curl "http://HOSTNAME/image.jpg?crop=center,center,150,150" \
 -o output_image.jpg
crop=center,center,150,150

Pad

GET /image.jpg?pad=30 HTTP/1.1
curl "http://HOSTNAME/image.jpg?pad=30" \
 -o output_image.jpg

Adds padding around an image with a given pad_color as a hex string. The default color is white.

pad the width of the padding in pixels.
pad_color background color of the padding as a hex string

original
pad=20&pad_color=555

Rotate

GET /image.jpg?angle=90 HTTP/1.1
curl "http://HOSTNAME/image.jpg?angle=90" \
 -o output_image.jpg

The angle parameter tells Imagizer to rotate the image counter clockwise N degrees. The meaningful values are 90, 180, and 270 degrees.

angle=0
angle=90

angle=180
angle=270

Quality

GET /image.jpg?quality=80 HTTP/1.1
curl "http://HOSTNAME/image.jpg?quality=80" \
 -o output_image.jpg

The quality parameter allows for specifying the quality of the image. Decreasing the quality parameter will reduce the file size. Quality value may be set from 1 to 100 and the default value is 90.

quality=80
quality=5

Contrast and Brightness

GET /image.jpg?contrast=0.3&brightness=0.2 HTTP/1.1
curl "http://HOSTNAME/image.jpg?contrast=0.3&brightness=0.2" \
 -o output_image.jpg

Imagizer allows for a quick adjustment of contrast and brightness.
contrast - adjust contrast of an image from -1 to 1
brightness - adjust brightness of an image from -1 to 1

contrast=1
brightness=0.3

Auto Fix

GET /image.jpg?auto_fix=true HTTP/1.1
curl "http://HOSTNAME/image.jpg?auto_fix=true" \
 -o output_image.jpg

Automatically adjust brightness and contrast of an image.

Original Image
auto_fix=true

Sharpening

Use this API to increase image sharpness.

sharp_amount - controls the overall strength of the sharpening effect (1-100)
sharp_radius - controls the size of the edges you wish to enhance (1-100)

GET /image.jpg?dpr=2&width=200&sharp_amount=100 HTTP/1.1
curl "http://HOSTNAME/image.jpg?dpr=2&width=200&sharp_amount=100" \
 -o output_image.jpg
amount=0
amount=100
amount=100, radius=100

DPR (device pixel ratio)

GET /image.jpg?dpr=2&width=300 HTTP/1.1
curl "http://HOSTNAME/image.jpg?dpr=2&width=300" \
 -o output_image.jpg

The device pixel ratio is used to specify the correct device pixel density. This will allow implementing the correct density on a variety of devices, such as Apple Retina displays and Android devices.

original
dpr=2 (Retina)

Filter

GET /image.jpg?filter=2 HTTP/1.1
curl "http://HOSTNAME/image.jpg?filter=2" \
 -o output_image.jpg

Filters apply various effects to images. Imagizer offers 20 different filters.

original
filter=2
filter=3
filter=21

Blur

GET /image.jpg?blur=100 HTTP/1.1
curl "http://HOSTNAME/image.jpg?blur=100" \
 -o output_image.jpg

Blur image (0-100).

original
blur=100

Transparency

GET /image-transparent.png?w=200 HTTP/1.1
curl "http://HOSTNAME/image-transparent.png?w=200" \
 -o output_image.png
GET /image.png?w=200&format=jpeg HTTP/1.1
curl "http://HOSTNAME/image.png?w=200&format=jpeg" \
 -o output_image.jpg

By default Imagizer will preserve transparent background when resizing images. However, if transparency is not required we recommend to convert images to JPEG format. It yields a much better performance as well as reduced image size.

Transparent PNG
JPEG

Flatten

GET /image-transparent.png?w=200 HTTP/1.1
curl "http://HOSTNAME/image-transparent.png?w=200" \
 -o output_image.png
GET /image-transparent.png?w=200&flatten=1 HTTP/1.1
curl "http://HOSTNAME/image-transparent.png?w=200&flatten=1" \
 -o output_image.png

Imagizer provides an easy way to remove the alpha channel from images that support it. Removing the alpha channel reduces the resulting image size and therefore can improve image delivery times.

Transparent PNG
Flattened PNG

Format

GET /image.png?w=200 HTTP/1.1
curl "http://HOSTNAME/image.png?w=200" \
 -o output_image.png
GET /image.png?w=200&format=webp HTTP/1.1
curl "http://HOSTNAME/image.png?w=200&format=webp" \
 -o output_image.webp

Imagizer provides an easy way of switching between image formats. Supported output formats are JPEG, PNG, and WEBP.

PNG
JPEG
WEBP

Auto format

GET /image.png?w=200&format=auto HTTP/1.1
curl -H "Accept: image/webp" "http://HOSTNAME/image.png?w=200&format=auto" \
 -o output_image.webp

Auto format will provide the most optimized format supported by the client. The default format is WEBP. If the client does not support WEBP the output format will fallback to JPEG or PNG if the image has transparency.

Watermarking

GET /image.jpg?mark=<URL> HTTP/1.1
curl "http://HOSTNAME/image.jpg?mark=<URL>" \
 -o output_image.jpg
GET /image.jpg?mark=<URL>&mark_scale=60&mark_pos=bottom,right&mark_offset=2 HTTP/1.1
curl "http://HOSTNAME/image.jpg?mark=<URL>&mark_scale=60&mark_pos=bottom,right&mark_offset=2" \
 -o output_image.jpg

Imagizer supports watermarking.

mark - the watermark URL
mark_alpha - adjusts the watermark alpha (0-100 where 0 means fully transparent and 100 is fully opaque)
mark_scale - scales the watermark to a percentage of the smallest dimension
mark_pos - positions the watermark with the source image. Valid values are top, right, bottom, left; the default position is center
mark_offset - offsets the watermark position by a given percentage

Watermark
Bottom-right, 60% scale, 2% offset

Watermark alpha 50

Watermarking can be made required by using the ImageParamsAllowed config

Red-eye correction

GET /image.jpg?redeye=true HTTP/1.1
curl "http://HOSTNAME/image.jpg?redeye=true" \
 -o output_image.jpg

When the redeye parameter is set to true, red-eye correction is applied to detected faces.

Before
After

Color trim

GET /image.png?trim=color&trim_color=white HTTP/1.1
curl "http://HOSTNAME/image.png?trim=color&trim_color=white" \
-o output_image.png

If trim=color is set, Imagizer will attempt to look for trim_color and crop it out. By default the trim_color value is set to white. It will also accept a hex string (e.g. fff, ffffff). Some of the predefined values are: white, black, red, green, blue, yellow, magenta, cyan.

trim - when set to color Imagizer will detect and trim given color from the image
trim_color - string representing the color to trim

Before
After

Hostname

GET /image.png?hostname=http://example.com HTTP/1.1
curl "http://HOSTNAME/image.png?hostname=http://example.com" \
-o output_image.png

By default Imagizer will use the provided backend end-point from the Imagizer config. Imagizer also provides a dynamic method of providing multiple backend end-points by passing a hostname parameter

The hostname parameter can be restricted by setting the hostnameAllowed config

Image Recognition

GET /image.png?recognition=labels HTTP/1.1
curl "http://HOSTNAME/image.png?recognition=labels" \
-o labels.json
{  
   "labels":[  
      {  
         "Name":"Animal",
         "Confidence":98.966850280762
      },
      {  
         "Name":"Horse",
         "Confidence":98.966850280762
      },
      {  
         "Name":"People",
         "Confidence":98.813423156738
      },
      {  
         "Name":"Human",
         "Confidence":98.749732971191
      },
      {  
         "Name":"Cafe",
         "Confidence":87.56616973877
      },
      {  
         "Name":"Vehicle",
         "Confidence":83.645690917969
      },
      {  
         "Name":"Bazaar",
         "Confidence":71.16487121582
      },
      {  
         "Name":"Market",
         "Confidence":71.16487121582
      },
      {  
         "Name":"Carriage",
         "Confidence":67.355987548828
      },
      {  
         "Name":"Horse Cart",
         "Confidence":67.355987548828
      },
      {  
         "Name":"Kiosk",
         "Confidence":66.328186035156
      },
      {  
         "Name":"Deli",
         "Confidence":52.841217041016
      },
      {  
         "Name":"Shop",
         "Confidence":52.841217041016
      },
      {  
         "Name":"Automobile",
         "Confidence":50.674034118652
      },
      {  
         "Name":"Pub",
         "Confidence":50.671188354492
      }
   ]
}

Image recognition is able to identify thousands of objects such as vehicles, pets, or furniture, and provides a confidence score. Image recognition also detects scenes within an image, such as a sunset or beach.

Use the recognition=labels parameter to request image recognition. A list of labels will be returned in json format.

Example

/image-labels.jpg?recognition=labels

Example labels photo

Admin API

The admin API is available from port 17006 on your aws instance. You must open port 17006 from the Aws console. Make sure to properly setup security as the admin API allows access to your imagizer configuration

Stats

Get Imagizer stats

GET :17006/stats

GET /stats HTTP/1.1
Content-Type: application/json
curl -H "Content-Type:application/json" \
 "http://HOSTNAME:17006/stats"

The above command returns JSON structured like this:

{  
    "version": "2.5-21.1",
    "requestsPerSecond": 405,
    "cachedObjects": 24706,
    "cachedMemoryUsedMB": 1619,
    "cachedMemoryAvailableMB": 13741,
    "cacheHit": 490,
    "cacheHitPass": 0,
    "cacheMiss": 14864,
    "cacheHitRate": 0.0319,
    "cacheMissRate": 0.9681,
    "cacheMinAverageHitRate": 0.0317,
    "cacheMinAverageMissRate": 0.9683,
    "cacheLruMoved": 490,
    "cacheLruNuked": 10728,
    "systemMemoryUsedMB": 3994,
    "systemMemoryFreeMB": 28108,
    "cpuIdlePercent": 78.4,
    "cpuUserPercent": 8.4,
    "cpuSystemPercent": 4.7,
    "cpuNicePercent": 0,
    "cpuIoWaitPercent": 0,
    "cpuStealPercent": 8,
    "networkSendBytesSec": 465169,
    "networkReceiveBytesSec": 828111,
    "disks": [
        {
            "mountPoint": "/data",
            "diskFreeMb": 11764,
            "diskUsedMb": 75,
            "diskPercent": 0.6
        },
        {
            "mountPoint": "/tmp",
            "diskFreeMb": 864,
            "diskUsedMb": 160,
            "diskPercent": 15.6
        },
        {
            "mountPoint": "/",
            "diskFreeMb": 4444,
            "diskUsedMb": 3086,
            "diskPercent": 41
        }
    ]
}

This endpoint retrieves various stats of your Imagizer instance

Attribute Description
version The current version of the Imagizer Engine
requestsPerSecond Current Requests per seconds
cachedObjects Total images stored in cache
cachedMemoryUsedMB Current memory used in cache in megabytes
cachedMemoryAvailableMB Current memory available for cache
cacheHit Amount of requests served from cache
cacheMiss Amount of requests not found in cache
cacheHitPass Amount of requests not able to be cached
cacheHitRate Accumulated cache hit rate
cacheMissRate Accumulated cache miss rate
cacheMinAverageHitRate Last minute averaged cache hit rate
cacheMinAverageMissRate Last minute averaged cache miss rate
cacheLruMoved Amount of move operations done on the LRU cache list
cacheLruNuked Amount of images that have been forcefully evicted from cache to make room for a new image
systemMemoryUsedMB Current system memory used in megabytes
systemMemoryFreeMB Current system memory free in megabytes
cpuIdlePercent Percentage of cpu time spent doing nothing
cpuUserPercent Percentage of cpu time spent by normal processes executing in user mode
cpuSystemPercent Percentage of cpu time spent by processes executing in kernel mode
cpuNicePercent Percentage of cpu time spent by niced processes executing in user mode
cpuIoWaitPercent Percentage of cpu time spent waiting for I/O to complete
cpuStealPercent Percentage of cpu time spent by other operating systems when running in a virtualized environment
networkSendBytesSec Bandwidth in bytes transmitted per second
networkReceiveBytesSec Bandwidth in bytes received per second
disks An array of disk stats for each mounted device. Listed tmp device is a ram disk.

Disk Stats

Attribute Description
mountPoint The mount point of the device
diskFreeMb Amount of free space available in megabytes
diskUsedMb Amount of used space available in megabytes
diskPercent The percentage of space used in megabytes

Config

Get current config

GET :17006/config

GET /config HTTP/1.1
Content-Type: application/json
curl -H "Content-Type:application/json" \
 "http://HOSTNAME:17006/config"

The above command returns JSON structured like this:

{  
   "backend":"http:\/\/my.aws.bucket.s3.amazonaws.com",
   "backendTimeout":30,
   "backendConnectTimeout":3,
   "awsAuthorization":{  
      "bucket":"my.aws.bucket",
      "key":"AWS_ACCESS_KEY_ID",
      "secret":"XXXXXXXXXXXXXXXXXXXXX"
   },
   "cache":"memory",
   "cacheControl":{  
      "override":false,
      "browserCacheTtl":1800,
      "serverCacheTtl":2678400
   },
   "logging": {
       "enable": false,
       "appLogLevel": "info",
       "facility": "local7",
       "syslogServer": "",
       "syslogPort": 514
   },
   "sendLogsToDeveloper":false,
   "debugLog":false,
   "hostsAllowed":[],
   "imageParamsAllowed":[],
   "secureWebProxy":null,
   "webProxy":null,
   "upscaleAllowed":false
}

This endpoint retrieves the current Imagizer config

Attribute Description
backend The backend upstream server url
backendTimeout The backend fetch timeout (default: 30 sec)
backendConnectTimeout The backend fetch connect timeout (default: 3 sec)
awsAuthorization AWS Authorization (bucket, key, and secret)
cache The cache type to use (memory, disk, or none) (default: memory)
cacheControl Cache control configuration (override, browserCacheTtl, and serverCacheTtl). Default and override cache control headers
sendLogsToDeveloper Enable or disable share diagnostics and usage information with Nventify
logging Logging configuration. See below for more details
hostsAllowed Restricted hosts to use with hostname parameter. Leave blank to not restrict
imageParamsAllowed Restricted image parameters to preset combinations. Leave blank to not restrict
passThroughHeaders Array of request headers to be passed through to origin image servers
sizeCheck Restrict image resolution request size to within an allowed tolerance
webProxy Web proxy to use on backend image fetches
secureWebProxy Secure web proxy to use on https backend image fetches
upscaleAllowed Allows for upscaling using the image API width and height parameters. (default: false)

Create new config

POST :17006/config

Use POST to create a complete new config. This will overwrite any existing configuration

POST /config HTTP/1.1
Content-Type: application/json

{  
   "backend":"http://my.aws.bucket.s3.amazonaws.com",
   "backendTimeout":20,
   "backendConnectTimeout":3
}
curl -X POST -H "Content-Type:application/json" \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com",
        "backendTimeout":20,
        "backendConnectTimeout":3
     }' \
 "http://HOSTNAME:17006/config"

Update config

PATCH :17006/config

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "backend":"http://my.aws.bucket.s3.amazonaws.com"
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com"
     }' \
 "http://HOSTNAME:17006/config"

Use PATCH to make partial changes to the configuration

EC2 User Data

You may update your instance config via the EC2 user data

Add the json formatted config data directly into your EC2 user data. When the instance is started, it will automatically configure itself using the user data.

{  
   "backend":"http://my.aws.bucket.s3.amazonaws.com"
}

AWS Authentication

To enable support for AWS HMAC Authentication, send an awsAuthorization object complete with bucket, key, and secret.

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "awsAuthorization":{  
      "bucket":"my.aws.bucket",
      "key":"AWS_ACCESS_KEY_ID",
      "secret":"AWS_SECRET_KEY"
   }
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "awsAuthorization":{  
           "bucket":"my.aws.bucket",
           "key":"AWS_ACCESS_KEY_ID",
           "secret":"AWS_SECRET_KEY"
        }
     }' \ 
 "http://HOSTNAME:17006/config"
Parameter Description
bucket The AWS S3 bucket
key The AWS auth key which has access to the bucket
secret The AWS secret which matches the key

Logging

Imagizer supports logging to a remote syslog server. The web server access log and error log along with the application log will be sent. The application log supports four levels (debug, info, warn, error) of logging. By default info, warning, and error logs will be sent. Log severity will be set accordingly. Facility will default to “local7”

Enable syslog logging to remote server

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "facility": "local7",
      "syslogServer": "192.168.1.155",
      "syslogPort": 514
   }
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "logging":{  
           "enable": true,
           "appLogLevel": "info",
           "facility": "local7",
           "syslogServer": "192.168.1.155",
           "syslogPort": 514
        }
     }' \ 
 http://HOSTNAME:17006/config
Attribute Description
enable Enables web server and application logging to syslog (default: disabled)
appLogLevel Defines the application level logging (debug, info, warn, error) (default: info)
facility Sets facility of syslog messages, as defined in RFC 3164 (Default: local7)
syslogServer Defines the address of a syslog server. The address can be specified as a IP address
syslogPort Defines the port of a syslog server (default: 514)

Cache

Enable disk cache

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "cache":"disk"
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "cache":"disk"
     }' \ 
 "http://HOSTNAME:17006/config"

Disable caching completely

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "cache":"none"
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "cache":"none"
     }' \ 
 "http://HOSTNAME:17006/config"

There are two types of cache storage: memory-based (default) and disk-based. There is also an option to disable caching.

To enable disk cache attach one or more volumes to your instance and set the cache option to “disk”. All attached volumes to the instance will be automatically mounted and formatted for use. Formatting may take some time.

To disable caching completely, set cache option to “none”

Parameter Description
cache The type of cache storage to use. (memory, disk, none)

Cache Control

Imagizer caching is controlled by the Cache-Control header on origin images. The Browser Cache TTL and Server Cache TTL will only be applied when there is no Cache-Control header present on origin images or the override value is set to true.

Set default browser cache to 10 minutes and the Imagizer server cache to 30 days

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "cacheControl":{
      "override": false,
      "browserCacheTtl": 1800,
      "serverCacheTtl": 2678400
   }
}
curl -X PATCH -H "Content-Type:application/json" \
-d '{  
      "cacheControl":
      {
         "override": false,
         "browserCacheTtl": 1800,
         "serverCacheTtl": 2678400
      }
}' \
 "http://HOSTNAME:17006/config"

Disable caching completely

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "cacheControl":{
      "override": true,
      "browserCacheTtl": 0,
      "serverCacheTtl": 0
   }
}
curl -X PATCH -H "Content-Type:application/json" \
-d '{  
      "cacheControl":
      {
         "override": true,
         "browserCacheTtl": 0,
         "serverCacheTtl": 0
      }
}' \ 
 "http://HOSTNAME:17006/config"
Parameter Description
override Sets whether or not to override the origin Cache-Control header (default: false)
browserCacheTtl Specifies the maximum time in seconds that the image is cached on the client side. This is the max-age directive. (Specified in seconds, default: 10 minutes)
serverCacheTtl Specifies the maximum time in seconds that the image is cached on the server side in Imagizer. This is the s-maxage directive. (Specified in seconds, default: 30 days)

Hosts Allowed

Limit the use of the hostname parameter to three different backends

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "hostsAllowed": [
        "bucket.s3.amazonaws.com",
        "bucket2.s3.amazonaws.com",
        "bucket3.s3.amazonaws.com"
    ]
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "hostsAllowed": [
             "bucket.s3.amazonaws.com",
             "bucket2.s3.amazonaws.com",
             "bucket3.s3.amazonaws.com"
         ]
     }' \ 
 "http://HOSTNAME:17006/config"

By default the Imagizer Image API allows any hostname to be passed through the hostname parameter. This can be restricted to a preset list of approved backend origins using the hostsAllowed attribute.

Parameter Description
hostsAllowed List of hostnames allowed

Image Params Allowed

Limit the use of the image API to thumbnails of 120px wide and large images of 1000px wide with a watermarked logo image

POST /config HTTP/1.1
Content-Type: application/json

{  
   "backend":"http://my.aws.bucket.s3.amazonaws.com",
   "imageParamsAllowed": [
        {
            "width": 120
        },
        {
            "width": 500,
            "height": 500,
            "mark": "http://example.com/watermark.png",
            "mark_pos": "bottom,right",
            "mark_offset": 2
        }   
    ]
}
curl -X POST -H "Content-Type:application/json" \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com",
        "imageParamsAllowed": [
             {
                 "width": 120
             },
             {
                 "width": 1000,
                 "mark": "http://example.com/logo.png",
                 "mark_pos": "bottom,right",
                 "mark_offset": 2
             }   
         ]
     }' \ 
 "http://HOSTNAME:17006/config"

By default the Imagizer Image API allows any combination of request parameters. Restrict the requests parameters to a preset list of combinations using the imageParamsAllowed attribute.

Parameter Description
imageParamsAllowed List of image parameter combinations allowed

Web Proxy

All https traffic will pass through my-proxy-example.com on port 8282 while non https traffic will pass through port 8181

POST /config HTTP/1.1
Content-Type: application/json

{  
   "backend":"http://my.aws.bucket.s3.amazonaws.com",
   "webProxy":{  
      "host":"my-proxy-example.com",
      "port":"8181"
   },
   "secureWebProxy":{  
      "host":"my-proxy-example.com",
      "port":"8282"
   }
}
curl -X POST -H "Content-Type:application/json" \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com",
        "webProxy":{
            "host":"my-proxy-example.com",
            "port":"8181"
        },
        "secureWebProxy":{
            "host":"my-proxy-example.com",
            "port":"8282"
        }
     }' \ 
 "http://HOSTNAME:17006/config"

Imagizer supports web proxy usage. Using a web proxy will send all origin image requests to a specified proxy. Imagizer supports both http and https requests through proxy. Use the webProxy attribute for all http requests and the secureWebProxy attribute for https requests.

Parameter Description
webProxy Host and port for web proxy to be used for all incoming image traffic
secureWebProxy Host and port for web proxy to be used for all incoming https image traffic

Pass Through Headers

Imagizer will pass through request headers to the origin image only when specified in the config. Use the passThroughHeaders parameter to specify an array of headers to be use on each origin image request. Wildcards (*) are supported to match multiple headers.

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "passThroughHeaders":[  
      "Host",
      "Origin",
      "X-My-Custom-Header"
   ]
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "passThroughHeaders":[  
           "Host",
           "Origin",
           "X-My-Custom-Header"
        ]
     }' \
 "http://HOSTNAME:17006/config"

Pass all request headers

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "passThroughHeaders":[  
      "*"
   ]
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "passThroughHeaders":[  
           "*"
        ]
     }' \
 "http://HOSTNAME:17006/config"

Size Check

Restrict image resolution request size to within an allowed tolerance.

When enabled a comparison between the requested image dimensions and the original image dimensions is preformed. If the requested dimensions exceed the tolerated percent of the width or height, a fallback image is served in it’s place.

It’s possible to configure one fallback image for each image format. Image formats without a configured fallback image will default to jpg.

PATCH /config HTTP/1.1
Content-Type: application/json

{  
   "sizeCheck":{
       "tolerancePercent": 10,
       "fallbackImages": {
           "jpg": "/error/images/image.jpg",
           "png": "/error/images/image.jpg"
       }
   }
}
curl -X PATCH -H "Content-Type:application/json" \
 -d '{  
        "sizeCheck":{
            "tolerancePercent": 10,
            "fallbackImages": {
                "jpg": "/error/images/image.jpg",
                "png": "/error/images/image.jpg"
            }
        }
     }' \
 "http://HOSTNAME:17006/config"

Example

The following image has dimensions of 200x150. If we request an image with a width more then 10% larger than we’ll receive the fallback image.

Original Image
width=250

Parameter Description
tolerancePercent The tolerance in percent allowed above the original dimensions. (required) (default: 10)
fallbackImages Array of paths to fallback images. (required)

Network

Get current network

This endpoint retrieves the current network configuration

GET /network HTTP/1.1
Content-Type: application/json
curl -H "Content-Type:application/json" \
 "http://HOSTNAME:17006/network"

The above command returns JSON structured like this:

{  
   "static":false,
   "ip":"192.168.1.100",
   "netmask":"255.255.255.0",
   "gateway":"192.168.1.1",
   "dnsServers":[  
      "192.168.1.1"
   ]
}
Attribute Description
static whether of not the instance is using a static ip
ip The current ip of the instance
netmask The current netmask of the instance
gateway The current gateway address of the instance
dnsServers A list of dns servers the instance is using

Change network configuration

Use POST to create a complete new network. This will overwrite any existing configuration.

Create a static network

POST /network HTTP/1.1
Content-Type: application/json

{  
   "static":true,
   "ip":"192.168.1.100",
   "netmask":"255.255.255.0",
   "gateway":"192.168.1.1",
   "dnsServers":[  
      "192.168.1.1"
   ]
}
curl -X POST -H "Content-Type:application/json" \
 -d '{  
        "static":true,
        "ip":"192.168.1.100",
        "netmask":"255.255.255.0",
        "gateway":"192.168.1.1",
        "dnsServers":[  
           "192.168.1.1"
        ]
     }' \
 "http://HOSTNAME:17006/network"

Create DHCP network

POST /network HTTP/1.1
Content-Type: application/json

{  
   "static":false
}
curl -X POST -H "Content-Type:application/json" \
 -d '{  
        "static":false
     }' \
 "http://HOSTNAME:17006/network"

Cache

Imagizer will cache both origin images and processed images. By default images are cached in memory, but Imagizer can also be configured to use disk space

Cache-Control headers

The backend can instruct Imagizer how to cache images with the HTTP response header Cache-Control. Images will be cached up to the ​max-age or s-maxage specified. Use of ​s-maxage takes precedence over max-age

When there are no Cache-Control headers are present, imagizer will cache images for a default amount of time. Imagizer may also be configured to override Cache-Control headers.

Examples

Cache images up to 24 hours:

Cache-Control: public, max-age=86400

Disable caching completely:

Cache-Control: no-store

Purge All

DELETE /cache HTTP/1.1
curl -X DELETE \
 "http://HOSTNAME:17006/cache"

Use DELETE on /cache to purge all cache.

Purge Specific Object

DELETE /cache/image.jpg HTTP/1.1
curl -X DELETE \
 "http://HOSTNAME:17006/cache/image.jpg"

To purge specific objects append the object URI to the request.

Update

Major Imagizer updates require a complete new image. However, minor patch updates can be applied directly to the Imagizer instance using the update API. Patch update files are provided by Nventify’s support. Contact us if you find an issue that needs patching.

Apply Patch

Updating an Imagizer instance takes a few minutes and requires a reboot afterwards. Take the provided patch file and upload to the /update endpoint.

POST /update HTTP/1.1

file=@patch.20170119.1552.tar
curl -F "file=@patch.20170119.1552.tar" \
http://HOSTNAME:17006/update

Status

Update status can be monitored by preforming a GET requests on the /update endpoint.

GET /update HTTP/1.1
curl http://HOSTNAME:17006/update

The above command returns JSON structured like this:

[
    {
       "filename": "patch2017011915521484949961",
       "status": "Update has been applied"
    }
]

Write-through Cache

POST http://HOSTNAME:17007/image.jpg HTTP/1.1
Content-Type: multipart/form-data;

file=@image.jpg
curl -F file=@image.jpg http://HOSTNAME:17007/image.jpg

The above command will write image.jpg into cache. All requests to /image.jpg will return the uploaded image.

Images can be written directly into Imagizer’s cache. This allows for a pre-warming of the cache, preventing Imagizer from fetching original images later in real time. Write-through cache is available through port 17007.

Perform a multipart/form-data file upload to the intended url of the image. Once the upload is complete, the image will become available for processing.

Example: /image.jpg?width=200

SDK Libraries

We offer several official libraries for working with the Imagizer Media Engine in your favorite languages and frameworks.

Visit us on Github.

Official

Third Party

Examples

Release Notes

The AWS release version is prepended to the version numbers

4.2-30.2

4.1-28.3

4.0-27.0

3.4-26.0

3.3-25.0

3.2-24.1

3.1-23.3

3.0-22.5

2.5-21.1

2.4-19.1

2.3-18.1

2.2-17.2

2.1-15.1

1.10-14.2

1.9-13.3

1.8-12.3

1.7-10.4

1.6

1.5

1.4

1.3