Skip to content

API Documentation

Jump to bottom Edit New page
Paul Filitchkin edited this page Jun 9, 2016 · 33 revisions

##General operation

Input

{
  "input_url": <input file>,
  ...
  "operations": [
    {
      "type": <operation1 type>,
      "params": { ... }
    },
    {
      "type": <operation2 type>,
      "params": { ... }
    }
  ]
}

Response

{
  "result" : <result>,
  ...
  "info": [
    {
      "result": true/false,
      "type": <operation1 type>,
      ...
    },
    {
      "result": true/false,
      "type": <operation2 type>,
      ...
    }
  ]
}

##Example command

This example generates a single thumbnail with a 230px width. Output sharpening is applied with a radius of 0.5 and a strength of 80%. The final image is saved as a jpeg with 85% quality without any original metadata.

NOTE: In this example the height parameter is provided as the absolute maximum height (e.g. if the thumbnail height more than 2000px the thumbnail width is proportionally scaled to a 2000px height).

Input

{
  "input_url": "file://input.jpg",
  "correct_rotation":true,
  "operations": [
    {
      "type": "resize",
      "params": {
        "type": "width",
        "width": 230,
        "height": 2000,
        "preserve_meta": false,
        "sharpen_amount": 80,
        "sharpen_radius": 0.5,
        "quality": 85,
        "watermark":false,
        "output_url": "file://output.jpg"
      }
    }
  ]
}

Response

{
  "result" : true,
  "time" : 0.18,
  "height" : 864,
  "width" : 1296,
  "md5" : "636ee0572d42df5e3764372cb08d6ade",
  "info" : [
    {
      "type" : "resize",
      "result" : true,
      "output_url" : "file://output.jpg",
      "output_height" : 153,
      "output_width" : 230,
      "time" : 0.02
    }
  ]
}

Input parameters

The input_url is a required field and there needs to be at least one operation specified. All other fields are optional.

Type Name Description
string input_url The location of the input file (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
boolean correct_rotation Reads jpeg EXIF meta data to determine the proper orientation for the image. If true image rotation is corrected before producing thumbnail(s). Otherwise no rotation is performed. It is recommended to set this to true
object write_meta An object of fields to write into image metadata
list operations A list of operations to be performed on the image

Write_meta object

Type Name Description
string caption Store caption information
list keywords Store list of keywords
string copyright Store copyright information
string province_state Store province/state to save
string city Store city to save
string country_name Store country name
string instructions Store special instructions about the image (IPTC-specific, more details [here](http://www.photometadata.org/meta-resources-field-guide-to-metadata#Special Instructions))

Operations list

Type Name Description
string type Operation type
resize create one or more resized images from the source (i.e. thumbnails)
read_meta read header metadata
copy efficiently copy the image without any pixel manipulation
and write metadata provided by write_meta parameter (if any)
fingerprint get a unique identifier of pixel data (fingerprint)
object params Operation parameters

Operation parameters

resize operation

Type Name Description
string type The type of resize
width - the thumbnail will be constrained by the width parameter
height - the thumbnail will be constrained by the height parameter
square - the thumbnail will be a square crop from the center of the image
integer width When type is width or square this will be the target width. When type is height this will determine the maximum width of the image
integer height When type is height this will be the target height. When type is width this will determine the maximum height of the image. When type is square this parameter is ignored
integer quality The output JPEG quality of the image
string output_url The location to write the resize image (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
boolean preserve_meta When set to true all metadata (EXIF/IPTC/XMP) of the original image is saved and when false no EXIF data is saved
string watermark_url The location of the watermark file (currently only supports local files). The file must be a png with an alpha layer. As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
string watermark_type

Watermark type (standard when not specified)

standard Apply an opacity based watermark
adaptive Apply an adaptive watermark that compensates for source image pixel brightness
float watermark_amount The amount to blend the watermark (0.0 - 1.0)

Only used when watermark_type is standard
float watermark_min The minimum amount to blend the watermark (0.0 - 1.0)

Only used when watermark_type is adaptive
float watermark_max The maximum amount to blend the watermark (0.0 - 1.0).

Only used when watermark_type is adaptive
integer sharpen_amount The amount of sharpening to apply to the thumbnail (must also include radius parameter)
float sharpen_radius The radius of the gaussian filter used to unsharpen the image. If excluded or set to 0.0 no sharpening is applied (must also include the amount parameter)
boolean pre_filter When set to true gaussian blurring is applied on the input image to help reduce aliasing during the resize operation. This is slow, but produces good results on images with high-frequency data. Disabled by default.

See example usage.

read_meta operation

The read_meta operation reads EXIF/IPTC/XMP headers and returns key fields.

Type Name Description
boolean info

If set to true read the following from metadata

caption keywords
copyright city
province/state country name
country code instructions
See example usage.

copy operation

The copy operation simply copies an image byte for byte and then applies any meta data overrides provided in the write_meta parameter.

Type Name Description
string output_url The location to write the image copy (currently only supports local files). As of v0.2.0 the file:// prefix is entirely optional (when no prefix is provided the file is assumed to be local)
See example usage.

fingerprint operation

The fingerprint returns a unique image identifier based on the source image pixel data. This is useful for image duplicate detection or identification.

Type Name Description
string type

Fingerprint type

md5 Computes an md5 hash of the image pixel data
See example usage.

Output parameters

Type Name Description
boolean result Operation result. true if all operations were successful, false otherwise
float time Total execution time in seconds
integer height The height of the input image
integer width The width of the input image
string md5 The md5 hash of the pixel data (not to be confused with the md5 of the actual file)
list info The return information for each operation. The order corresponds to the order each input operation was provided.
Add a custom footer
Add a custom sidebar
Clone this wiki locally