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

Adjustments

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, brightness, gamma, warmth, saturation and fill flash.
contrast - adjust contrast of an image from -1 to 1
brightness - adjust brightness of an image from -1 to 1
gamma - adjust gamma of an image from -1 to 1
warmth - adjust warmth of an image from -1 to 1
saturation - adjust saturation of an image from -1 to 1
fill_flash - adjust fill flash of an image from 0 to 1
highlight - adjust image highlights from -1 to 1
shadow - adjust image shadows from 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

Auto White Balance

GET /image.jpg?auto_level=true HTTP/1.1

curl "http://HOSTNAME/image.jpg?auto_level=true" \
 -o output_image.jpg

Automatically adjust white balance level of an image.

Original Image
auto_level=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

Origin

GET /image.png?origin=http://example.com HTTP/1.1

curl "http://HOSTNAME/image.png?origin=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 an origin parameter

The origin parameter can be restricted by setting the hostnameAllowed config

Host Header

The host_header parameter will override the Host header on the origin request.

GET /img.jpg?host_header=images.example.com&origin=example.com HTTP/1.1

curl "http://HOSTNAME/image.png?host_header=img.example.com&origin=example.com" \
-o image.jpg

Hostname

The hostname parameter has been deprecated. Use origin instead.

Meta Data

Image meta data including exif data can be returned in JSON format using the meta=true parameter.

The ImagizerEngine IP and hostname are returned in the server property.

GET /image.png?meta=true HTTP/1.1

curl "http://HOSTNAME/image.png?meta=true"

{  
   "fileSize":4428575,
   "width":4032,
   "height":3024,
   "fileType":"jpeg",
   "mimeType":"image/jpeg",
   "hasAlpha":false,
   "colorSpace":"srgb",
   "exif":{  
      "ApertureValue":"2159/1273",
      "BrightnessValue":"3497/314",
      "ComponentsConfiguration":"1, 2, 3, 0",
      "DateTime":"2017:04:02 16:08:21",
      "DateTimeDigitized":"2017:04:02 16:08:21",
      "DateTimeOriginal":"2017:04:02 16:08:21",
      "ExifImageLength":3024,
      "ExifImageWidth":4032,
      "ExifOffset":180,
      "ExifVersion":"48, 50, 50, 49",
      "ExposureBiasValue":"0/1",
      "ExposureMode":0,
      "ExposureProgram":2,
      "ExposureTime":"1/3690",
      "Flash":24,
      "FlashPixVersion":"48, 49, 48, 48",
      "FNumber":"9/5",
      "FocalLength":"399/100",
      "FocalLengthIn35mmFilm":28,
      "ISOSpeedRatings":20,
      "Make":"Apple",
      "MeteringMode":5,
      "Model":"iPhone 7",
      "Orientation":1,
      "ResolutionUnit":2,
      "SensingMethod":2,
      "ShutterSpeedValue":"29588/2497",
      "Software":10.3,
      "SubjectArea":"2015, 1511, 2217, 1330",
      "SubSecTimeDigitized":245,
      "SubSecTimeOriginal":245,
      "WhiteBalance":0,
      "XResolution":"72/1",
      "YResolution":"72/1"
   },
   "faces":[],
   "server":{  
      "host":"ip-10-0-1-96",
      "ip":"10.0.1.96"
   }
}

/image-meta.jpg?meta=true

Example Photo

Facial Data

GET /image.png?meta=true&face=true HTTP/1.1

curl "http://HOSTNAME/image.png?meta=true&face=true"

{  
   "fileSize":215707,
   "width":1710,
   "height":1140,
   "fileType":"jpeg",
   "mimeType":"image/jpeg",
   "hasAlpha":false,
   "colorSpace":"srgb",
   "exif":{  
      "ColorSpace":65535,
      "ExifOffset":90,
      "ExifVersion":"48, 50, 50, 49",
      "Orientation":1,
      "Software":"Adobe Photoshop CS6 (Macintosh)"
   },
   "faces":[  
      {  
         "xPos":926,
         "yPos":524,
         "width":137,
         "height":137
      },
      {  
         "xPos":1012,
         "yPos":311,
         "width":140,
         "height":140
      },
      {  
         "xPos":516,
         "yPos":228,
         "width":200,
         "height":200
      },
      {  
         "xPos":1163,
         "yPos":148,
         "width":157,
         "height":157
      },
      {  
         "xPos":125,
         "yPos":362,
         "width":285,
         "height":285
      }
   ],
   "server":{  
      "host":"ip-10-0-1-81",
      "ip":"10.0.1.81"
   },
   "jpeg":{  
      "colorspace":2,
      "sampling-factor":"2x2,1x1,1x1"
   }
}

Adding face=true along with meta=true will return facial coordinates.

/image-meta.jpg?meta=true&face=true

Example Photo

Image Recognition

Nudity Detection

Image recognition can determine if an image contains any nudity. A True or False value and a confidence score will be returned.

GET /image.png?recognition=nsfw HTTP/1.1

curl "http://HOSTNAME/image.png?recognition=nsfw" \
-o nsfw.json

{
"nsfw": {
      "nudity": {
      "confidence": 98.48,
      "value": false
    }
  }
}

Example

Non-nude image

/image-notnsfw.jpg?recognition=nsfw

Example non-nsfw photo

Object Detection

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

Post to Process

Scaled image to 400px wide

POST http://HOSTNAME/ HTTP/1.1
Content-Type: multipart/form-data;

file=@image.jpg
width=400

curl -F file=@image.jpg -F width=400 \
 "http://HOSTNAME/" -o processed-image.jpg

Lookup image meta data 

POST http://HOSTNAME/ HTTP/1.1
Content-Type: multipart/form-data;

file=@image.jpg
meta=true

curl -F "file=@image.jpg" \
-F meta=true "http://HOSTNAME/"

Images may be posted directly to ImagizerEngine for processing. This can be done using a multipart POST request containing the image data and a list of image parameters to be applied. The processed image will be immediately returned.

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 http://HOST:17006/stats

The above command returns JSON structured like this:

{  
   "version":"4.3-33.3",
   "requestsPerSecond":45,
   "cachedObjects":3923,
   "cachedMemoryUsed":320912470,
   "cachedMemoryAvailable":15785214890,
   "cacheHit":162383,
   "cacheHitPass":0,
   "cacheMiss":123417,
   "cacheHitRate":0.5681700489853044,
   "cacheMissRate":0.43182995101469557,
   "cacheMinAverageHitRate":0.3152332361516035,
   "cacheMinAverageMissRate":0.6847667638483965,
   "cacheLruMoved":50123,
   "cacheLruNuked":0,
   "cpuCount":8,
   "cpuIdlePercent":62,
   "cpuUserPercent":22,
   "cpuSystemPercent":13,
   "cpuNicePercent":0,
   "cpuIoWaitPercent":0,
   "cpuStealPercent":1,
   "loadAvgFifteen":3.75,
   "loadAvgFive":1.05,
   "loadAvgOne":0.44,
   "networkSendBytesSec":2734900.3519119998,
   "networkReceiveBytesSec":5153407.748600915,
   "networkSendPacketsSec":2759.4351877102104,
   "networkReceivePacketsSec":4968.094014012295,
   "systemMemoryUsed":3707723776,
   "systemMemoryFree":28817772544,
   "systemMemoryTotal":33666740224,
   "systemMemoryShared":290275328,
   "systemMemoryCached":1106018304,
   "systemMemoryBuffers":35225600,
   "systemSwapMemoryFree":1073737728,
   "systemSwapMemoryUsed":0,
   "systemSwapMemoryTotal":1073737728,
   "totalDiskFree":26730463232,
   "totalDiskUsed":4170719232,
   "totalDiskTotal":30901182464,
   "disks":[  
      {  
         "diskUsed":254066688,
         "diskFree":819675136,
         "diskPercent":23.7,
         "mountPoint":"/tmp"
      },
      {  
         "diskUsed":3814895616,
         "diskFree":4081442816,
         "diskUsedMb":3638,
         "mountPoint":"/"
      },
      {  
         "diskUsed":101756928,
         "diskFree":21829345280,
         "diskPercent":0.5,
         "mountPoint":"/data"
      }
   ]
}

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
cachedMemoryUsed Current memory used in cache in bytes
cachedMemoryAvailable Current memory available for cache in bytes
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
cpuCount The number of CPU cores
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
loadAvgFifteen Average system load over the last 15 minutes
loadAvgFive Average system load over the last 5 minutes
loadAvgOne Average system load over the last 1 minute
networkSendBytesSec Bandwidth in bytes transmitted per second
networkReceiveBytesSec Bandwidth in bytes received per second
networkSendPacketsSec Packets sent per second
networkReceivePacketsSec Packets received per second
systemMemoryUsed Current system memory used in bytes
systemMemoryFree Current system memory free in bytes
systemMemoryTotal Current system memory total in bytes
systemMemoryShared Current system shared memory in bytes
systemMemoryCached Current system cached memory in bytes
systemMemoryBuffers Current system buffers total in bytes
systemSwapMemoryFree Current system swap free in bytes
systemSwapMemoryUsed Current system swap used in bytes
systemSwapMemoryTotal Current system swap total in bytes
totalDiskFree Total amount of free disk space available in bytes
totalDiskUsed Total amount of used disk space in bytes
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
diskFree Amount of free disk space available in bytes
diskUsed Amount of used disk space available in bytes
diskPercent The percentage of disk space used

Config

Get current config

GET :17006/config

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

curl http://HOST: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,
       "cloudWatch": {
          "enable": false,
          "region": "us-east-1",
          "key": "",
          "secret": ""
       }
   },
   "stats": {
       "ganglia": {
           "host":"",
           "port":"8649",
           "enable":false
       }
   },
   "sendLogsToDeveloper":false,
   "debugLog":false,
   "hostsAllowed":[],
   "imageParamsAllowed":[],
   "passThroughHeaders":[],
   "upscaleAllowed":false,
   "urlRewrites":[],
   "defaultImages":{
        "missing": "",
        "error": "",
        "shouldProcess": false,
        "return200Response": true
   },
   "sizeCheck":null,
   "secureWebProxy":null,
   "webProxy":null
}

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
stats Stats 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
urlRewrites An array of Url Rewrites to be performed on all requests.
defaultImages Default images to be used instead of http error codes.
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 Allow for upscaling using the image API width and height parameters. (default: false)
enablePostToProcess Enable Post to Process feature. (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 \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com",
        "backendTimeout":20,
        "backendConnectTimeout":3
     }' \
http://HOST: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 \
 -d '{  
        "backend":"http://my.aws.bucket.s3.amazonaws.com"
     }' \
http://HOST: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 \
 -d '{  
        "awsAuthorization":{  
           "bucket":"my.aws.bucket",
           "key":"AWS_ACCESS_KEY_ID",
           "secret":"AWS_SECRET_KEY"
        }
     }' \
http://HOST: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 and AWS Cloud Watch. 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 \
 -d '{  
        "logging":{  
           "enable": true,
           "appLogLevel": "info",
           "facility": "local7",
           "syslogServer": "192.168.1.155",
           "syslogPort": 514
        }
     }' \
http://HOST: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)
CloudWatch Defines AWS Cloud Watch configuration

Cloud Watch

Cloud Watch Logging may be enable and authorized using either an IAM role attached to your Imagizer instance or AWS user credentials.

Attribute Description
enable Enables web server and application logging to Cloud Watch (default: disabled)
region The AWS Cloud Watch region to send logs to
key The AWS auth key which has access to the Cloud Watch (optional)
secret The AWS secret which matches the key (optional)
Using IAM Role

Enable CloudWatch using IAM Role

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

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true
      }
   }
}

curl -X PATCH \
 -d '{  
        "logging":{  
            "enable": true,
            "appLogLevel": "info",
            "cloudWatch": {
               "enable":true
            }
        }
     }' \
http://HOST:17006/config

When using an IAM Role you must first create an IAM role with the correct permissions. Then attach the role to Imagizer.

Using AWS Credentials

Your AWS user must have the correct permission to access Cloud Watch. See AWS Cloud Watch Access for details.

Enable CloudWatch using AWS credentials

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

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "secret": "XXXXXXXXXXXXXXXXX"
      }
   }
}

curl -X PATCH \
 -d '{  
        "logging":{  
            "enable": true,
            "appLogLevel": "info",
            "cloudWatch": {
               "enable":true,
               "key": "XXXXXXXXXXXXXXXXX",
               "secret": "XXXXXXXXXXXXXXXXX"
            }
        }
     }' \
http://HOST:17006/config

Stats

Imagizer collections and stores system stats. These stats are available through the Stats API at any time.

Ganglia

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

{  
   "stats":[  
      {  
         "ganglia":{  
            "host":"ganglia.example.com",
            "port":8594,
            "prototal":"udp"
         }
      }
   ]
}

curl -X PATCH \
 -d '{  
        "stats":[  
           {  
              "ganglia":{  
                 "host":"ganglia.example.com",
                 "port":8649,
                 "prototal":"udp"
              }
           }
        ]
     }' \
http://HOST:17006/config

Send all stats to Ganglia. Stats are sent once a minute.

Attribute Description
enable If true send all stats to ganglia.
host The ganglia host.
port The ganglia port (default: 8649).
protocol The protocol to use when sending stats to ganglia. (udp or multicast) (default: upd)

Cache

Enable disk cache

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

{  
   "cache":"disk"
}

curl -X PATCH \
 -d '{  
        "cache":"disk"
     }' \
http://HOST:17006/config

Disable caching completely

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

{  
   "cache":"none"
}

curl -X PATCH \
 -d '{  
        "cache":"none"
     }' \
http://HOST: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 \
-d '{  
      "cacheControl":
      {
         "override": false,
         "browserCacheTtl": 1800,
         "serverCacheTtl": 2678400
      }
}' \
http://HOST:17006/config

Disable caching completely

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

{  
   "cacheControl":{
      "override": true,
      "browserCacheTtl": 0,
      "serverCacheTtl": 0
   }
}

curl -X PATCH \
-d '{  
      "cacheControl":
      {
         "override": true,
         "browserCacheTtl": 0,
         "serverCacheTtl": 0
      }
}' \
http://HOST: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 \
 -d '{  
        "hostsAllowed": [
             "bucket.s3.amazonaws.com",
             "bucket2.s3.amazonaws.com",
             "bucket3.s3.amazonaws.com"
         ]
     }' \
http://HOST: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

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

{  
   "imageParamsAllowed": [
        {
            "width": 120
        },
        {
            "width": 500,
            "height": 500,
            "mark": "http://example.com/watermark.png",
            "mark_pos": "bottom,right",
            "mark_offset": 2
        }   
    ]
}

curl -X PATCH \
 -d '{  
        "imageParamsAllowed": [
             {
                 "width": 120
             },
             {
                 "width": 1000,
                 "mark": "http://example.com/logo.png",
                 "mark_pos": "bottom,right",
                 "mark_offset": 2
             }   
         ]
     }' \
http://HOST: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

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

{  
   "webProxy":{  
      "host":"my-proxy-example.com",
      "port":"8181"
   },
   "secureWebProxy":{  
      "host":"my-proxy-example.com",
      "port":"8282"
   }
}

curl -X PATCH \
 -d '{  
        "webProxy":{
            "host":"my-proxy-example.com",
            "port":"8181"
        },
        "secureWebProxy":{
            "host":"my-proxy-example.com",
            "port":"8282"
        }
     }' \
http://HOST: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 \
 -d '{  
        "passThroughHeaders":[  
           "Host",
           "Origin",
           "X-My-Custom-Header"
        ]
     }' \
http://HOST:17006/config

Pass all request headers

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

{  
   "passThroughHeaders":[  
      "*"
   ]
}

curl -X PATCH \
 -d '{  
        "passThroughHeaders":[  
           "*"
        ]
     }' \
http://HOST: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"
       },
       "hostsAllowed": [],
       "return404Response": false
   }
}

curl -X PATCH \
 -d '{  
        "sizeCheck":{
            "tolerancePercent": 10,
            "fallbackImages": {
                "jpg": "/error/images/image.jpg",
                "png": "/error/images/image.jpg",
            },
            "hostsAllowed": [],
            "return404Response": false
        }
     }' \
http://HOST: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)

Url Rewrites

Modify the image path of all requests. Replace “is/image” with “product/published”.

/is/image/myimage1.jpg?width=400 => /product/published/myimage1.jpg?width=400

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

{  
   "urlRewrites":[  
      {  
         "search":"is/image",
         "replace":"product/published"
      }
   ]
}

curl -X PATCH \
 -d '{  
        "urlRewrites":[  
           {  
              "search":"is/image",
              "replace":"product/published"
           }
        ]
     }' \
http://HOST:17006/config

Migrate previously used image optimizer urls to Imagizer formatted API

/images/myimage1.jpg?resize=300x400 => /images/myimage1.jpg?width=300&height=400

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

{  
   "urlRewrites":[  
      {  
         "search":"/resize=([0-9]+)x([0-9]+)/",
         "replace":"width=$1&height=$2",
         "includeQueryString":true,
         "isRegex":true
      }
   ]
}

curl -X PATCH \
-d '{  
      "urlRewrites":[  
         {  
            "search":"/resize=([0-9]+)x([0-9]+)/",
            "replace":"width=$1&height=$2",
            "includeQueryString":true,
            "isRegex":true
         }
       ]
    }' \
http://HOST:17006/config

Url rewrites will perform search and replace on the request url before preceding to image processing. This will allow for changes to both the path and the query parameters on all requests passed to Imagizer.

Url Rewrites allow for both string and regex(PCRE) search and replace. Multiple rewrites are allowed.

Parameter Description
search The value being searched for, otherwise known as the needle.
replace The replacement value that replaces found search values.
includeQueryString If true include the query string in the search and replace. (default: false)
isRegex If true treat the search string as a regex. (default: false)

Default Images

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

{  
   "defaultImages": {
      "missing": "http://example.com/404image.jpg",
      "error": "http://example.com/errorimage.jpg",
      "shouldProcess": false,
      "return200Response": true
   }
}

curl -X PATCH \
-d '{
       "defaultImages": {
          "missing": "http://example.com/404image.jpg",
          "error": "http://example.com/errorimage.jpg",
          "shouldProcess": false,
          "return200Response": true
       }
    }' \
http://HOST:17006/config

Use default image in place of missing images and/or errors.

Parameter Description
missing Image to be used instead of 404 error code
error Image to be used instead of all other errors.
shouldProcess If true process the default image using the given image parameters. (default: false)
return200Response If true return a 200 response code with the default images. If false return the error code with the default image. (default: true)

Enable Post To Process

Enable Post To Process on port 80.

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

{  
   "enablePostToProcess": true
}

curl -X PATCH \
-d '{"enablePostToProcess": true}' \
http://HOST:17006/config

Network

Get current network

This endpoint retrieves the current network configuration

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

curl http://HOST: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 \
 -d '{  
        "static":true,
        "ip":"192.168.1.100",
        "netmask":"255.255.255.0",
        "gateway":"192.168.1.1",
        "dnsServers":[  
           "192.168.1.1"
        ]
     }' \
http://HOST:17006/network

Create DHCP network

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

{  
   "static":false
}

curl -X POST \
 -d '{  
        "static":false
     }' \
http://HOST: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://HOST:17006/cache

Use DELETE on /cache to purge all cache.

Purge Specific Object

DELETE /cache/image.jpg HTTP/1.1

curl -X DELETE http://HOST: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://HOST:17006/update

Status

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

GET /update HTTP/1.1

curl http://HOST:17006/update

The above command returns JSON structured like this:

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

Write-through Cache

Write image.jpg into 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"

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

Post to Process

Write the image into cache then return a processed image 

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

file=@image-file.jpg
width=400
quality=65

curl -F file=@image.jpg \
 -F width=400 "http://HOSTNAME/" \
 -o processed-image.jpg

Write the image into cache then return image meta data with facial coordinates (JSON) 

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

file=@image-file.jpg
meta=true
face=true

curl -F file=@image.jpg \
 -F meta=true -F face=true \
 "http://HOSTNAME:17007/"

Write-through cache supports Post to Process which allows for the retrieval of a processed image or meta data immediately after upload.

Pass any Imagizer parameters along with your POST and Imagizer will return the processed image.

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.4-35.1

4.3-33.3

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

http shell