Processing API

Below, you can find a list of all supported Processing Engine conversions. Please refer to Processing Engine Overiew for more information about this system.

If your account has security enabled, a valid policy and signature will be required for any and all processing requests. The processing engine accepts security parameters as a URL task:

https://cdn.filestackcontent.com /security=p:POLICY,s:SIGNATURE/ HANDLE

Please see our security documentation for more information regarding the generation of policies and signatures.

All task parameters listed here follow this pattern. Array types are presented as ordered lists of their respective types. Required fields are marked by an asterisk *.

cache=expiry:3600

Specify the amount of time for how long the file should be cached in our CDN. For example, cache=expiry:31536000 will set the cache duration for 1 year. You can also use cache=expiry:max and the same value will be set for the cache headers: “Cache-Control:public, max-age=31536000”. The cache can be set to false to ensure that you always receive a newly converted file. This setting is only recommended for testing purposes because every time a URL using cache=false loads, it will count against your conversion quota.

Parameters

store

Store the result of this transformation into your storage. By default, transformations are stored in temporary storage and cached for 30 days. Storing files can ensure that you don’t incur extra transformations when the cache expires every 30 days. It also allows you to create new handles from transformed URLs.

A request to a URL that contains this task will return a JSON response. Example:

https://cdn.filestackcontent.com/<apikey>/store/<url>

Returns:

{
  "container": "my-bucket",
  "filename": "272262.png",
  "key": "brPb11lRQR67XKxC9aUQ-272262.png",
  "size": 4585441,
  "type": "image/png",
  "url": "https://cdn.filestackcontent.com/feAWPKHgR6SnJMRzsKVP"
}

Store task is capable of triggering workflow jobs. In order to execute a job on a stored file, you’ll need to pass an ID of a workflow you wish to trigger using the workflows parameter. Store task will respond with unique IDs of executed jobs. Example:

https://cdn.filestackcontent.com/<apikey>/store=workflows:["46c8344b-d737-4411-8cbc-edbf66ce6731","448d6764-6ba5-11eb-9439-0242ac130002"]/<url>

Returns:

{
  "container": "my-bucket",
  "filename": "272262.png",
  "key": "brPb11lRQR67XKxC9aUQ-272262.png",
  "size": 4585441,
  "type": "image/png",
  "url": "https://cdn.filestackcontent.com/feAWPKHgR6SnJMRzsKVP"
  "workflows": {
    "46c8344b-d737-4411-8cbc-edbf66ce6731": {
      "jobid": "bd8a6508-7186-4ddf-985e-d91fa5aa5bf7"
    },
    "448d6764-6ba5-11eb-9439-0242ac130002": {
      "jobid": "da385844-6ba7-11eb-9439-0242ac130002"
    }
  }
}

Parameters

fallback=file:<file>,cache:<cache>

Returns default file if the source of the transformation does not work or the transformation fails.

If you are using a fallback handle that belongs to a different application than the one which runs transformation and it is secured with security policy, appropriate signature and policy with read call should be used:

/fallback=file:"<source>?policy=<policy>&signature=<signature>",cache:10/

You can read more about security policies here.

Examples

content=type:<type>,filename:<filename>

Sets Content-Disposition header for the given file.

Examples

https://cdn.filestackcontent.com/<apikey>/content=t:attachment,f:"sample.jpg"/<handle>

The maximum accepted image resolution is 100,000,000 pixels. For example, it can either be 10,000px x 10,000px or 5,000px x 20,000px.

Filestack will also not convert an image that is larger than 256 MB. Please contact us if you require the ability to process larger files.

imagesize

You can use the imagesize task to get information about the width and height of the given image, for example:

https://cdn.filestackcontent.com/imagesize/HANDLE

Imagesize GET request will return data as JSON, for example:

{"height":1253,"width":1080}

resize=height:200

The resizing feature comprises two main functions: manipulating the width and height of an image and changing the fit and alignment of the image. Either width or height is required. When both width and height are provided, the possible methods by which the image should fit these are:

If a single dimension is provided, only clip (default) or max fit can be applied.

Resize also allows specifying a resampling filter. Available filters are:

Parameters

crop=dim:[x,y,width,height]

Crop images by entering coordinates and crop dimensions. The X and Y coordinates start from [0,0] and correspond to the top left-hand corner of the image. The width and height parameters dictate the size in pixels of the cropping rectangle. If the crop area extends outside the frame of the image, you will only receive back the part of the image that is within the crop area.

Parameters

smart_crop

Smart Crop allows you to programmatically manipulate your images in a way that provides a version of the image that is exactly the shape you want, while keeping it’s aspect ratio and cutting out least interesting fragments of the input picture.

Examples

Response:

{"coords": {"x": 0, "y": 317, "width": 634, "height": 634}}

rotate=deg:180

You can rotate your image in a range clockwise from 0 degrees (no rotation) to 359 (nearly all the way around). Specifying “exif” for the degree parameter will auto-detect EXIF orientation and apply the rotation.

Parameters

flip

This task flips the image in the vertical direction. Flip requires no additional parameters.

flop

This task flops the image in the horizontal direction. Flop requires no additional parameters.

watermark=position:[middle, center]

You can add watermarks by overlaying one image on top of another. The size of the overlayed image is a percentage of its original size.

Parameters

compress

Filestack offers a standalone task specifically for compression. It utilizes mozjpeg to offer improved compression for JPG files over the algorithm used for output=compress:true. It will not attempt to re-compress a previously compressed image. Compress will only work with PNG and JPG files. If any other format is passed in, it will return an unchanged image. For the best results, compress should be the last task in your transformation chain.

Parameters

pjpg

Convert an image to progressive JPEG. This is ideal for large images that will be displayed while downloading over a slow connection, allowing a reasonable preview after receiving only a portion of the data. However, support for progressive JPEGs is not universal. When progressive JPEGs are received by programs that do not support them (such as versions of Internet Explorer before Windows 7) the software displays the image only after it has been completely downloaded.

Parameters

quality

Set the quality of your JPG or WEBP images without the danger of possibly generating a larger file. This is great for reducing the file size of your image before running it through the compress task. Quality is a standalone task which is separate from the quality parameter available in the output task, and it will never increase the size of a file.

Parameters

no_metadata

Remove any embedded metadata from an image file.

These powerful image enhancements are available as plugins in our marketplace and in our Transformations UI.

upscale

Upscale is available in our marketplace and in our Transformations UI.

Parameters

enhance

Enhance is available in our marketplace and in our Transformations UI.

This task smartly analyzes a photo and performs color correction and other enhancements to improve the overall quality of the image.

In standard version enhance requires no additional parameters. If you have presets enabled in your plan you will have access to additional preset parameter.

enhance=preset:<preset>

Available presets are listed in the table below:

Below you can see example usage of the enhance=preset:fix_noise preset:

You can find more examples in our [tutorial](https://www.filestack.com/docs/tutorials/enhance_images/).

Examples

redeye

Red eye removal is available in our marketplace and in our Transformations UI.

This task removes the red-eye effect from photos. The redeye task requires no additional parameters.

rounded_corners=blur:0.3

Parameters

vignette=amount:20

Parameters

polaroid

Parameters

torn_edges=spread:[1,10]

Parameters

shadow=opacity:60,vector:[4,4]

Parameters

circle

Parameters

border=width:2

Parameters

sharpen=amount:2

Parameters

blur=amount:2

Parameters

monochrome

blackwhite=threshold:50

Parameters

sepia=tone:80

Parameters

pixelate=amount:2

Parameters

oil_paint=amount:2

Parameters

negative

The image returned by this transformation creates a negative image by portraying the lightest area as the darkest and the darkest areas as the lightest. The negative task requires no additional parameters.

modulate=hue:155

Parameters

partial_pixelate=objects:[[x,y,width,height],[x,y,width,height]]

Parameters

partial_blur=objects:[[x,y,width,height],[x,y,width,height]]

Parameters

detect_faces

The minsize and maxsize parameters are used to weed out objects that most likely are not faces. This can be an integer or a float in a range from 0.01 to 10000. The default value is 0.35. If the value is larger than 1, it is used as the expected minimum/maximum size of face objects in pixels. So for example if the value is set to 200, then the smallest/largest face object it will detect is 200×200 pixels. If the value that is set is less than 1, e.g. 0.3, then it filters out all face objects it detects that are smaller/larger than the middle/average object size by 30%.

For example, this means that if a set of 3 objects are detected that are (size in pixels) [‘100×100’, ‘200×200’, ‘300×300’], then setting minsize to 0.3 will result in a calculation where the middle object size 200 is used: 200-0.30*200=140 and all objects smaller than 140×140 would be eliminated.

Setting export:true will export all face objects to a JSON object:

[
    {
        "x": 642,
        "y": 298,
        "width": 137,
        "height": 137,
        "id": 1
    },
    {
        "x": 446,
        "y": 731,
        "width": 138,
        "height": 138,
        "id": 2
    }
]

Parameters

crop_faces

The faces parameter can be a single face object, an array of face objects, or you can use faces:all to choose all the detected face objects. This parameter governs the faces you want included in your crop.

Parameters

pixelate_faces

Parameters

blur_faces

Parameters

output

This task converts an input file into the specified output format.

auto_image

This task automatically changes the encoding of the image based on the user agent and therefore provides better compression and quality characteristics compared to their older JPEG and PNG counterparts.

Currently, Filestack supports automatic conversion to WebP and JPEG XR.

WebP is natively supported in Google Chrome, Firefox, Edge, Opera, and by many other tools and software libraries.

For example this 1.42 MB JPEG image, after applying resize and compress tasks would have 48.45 KB:

If you are using auto_image task and one of the supported browsers you should see that it’s delivered in a WebP format and it’s size is 44.84 KB.

You can read more about benefits of using WebP at https://developers.google.com/speed/webp/.

To see the current browser support for each supported next-gen format, check out the entries below:

animate

Animate task converts set of images to a GIF file.

collage=files:[0ZgN5BtJTfmI1O3Rxhce]

The collage task accepts an array of Filestack file handles, storage aliases, or external urls. These files are appended in order to the base file of the transformation URL. Altogther the base image and the passed files are the images that will comprise the collage. The order in which they appear in the array dictates how the images will be arranged.

Both width and height are required. The images passed to this task will be resized using fit:clip (resize) so that the output image is close to the specified dimension parameters. The width parameter takes precedence over the height parameter.

Parameters

display: inline-block; line-height: 16px;

ascii

Take any image file and turn it into an HTML file of ASCII Art.

reverse reverses the character set used to generate the ASCII output. Works well with dark backgrounds. Requires color:true.

size specifies the size of the returned file as a percentage of the original.

Parameters

urlscreenshot

Note: This only works with external URLs, following the format:

https://cdn.filestackcontent.com/APIKEY/urlscreenshot/FULL_URL

The URL screenshot task will not work for content that is located in areas that require you to login. If the content is not publicly visible, then it will not be captured.

Parameters

qr

This task generates a QR code that encodes URL to the specified resource. You can pass in a solitary Filestack handle or a single publicly available external URL. It does not perform any operations on the underlying file data. This task checks if the resource is available and then encodes the URL.

Below you can see the example of the result:

zip

This task takes the file or files that are passed into it and compresses them into a zip file. You can pass in a solitary Filestack handle, a single external url, a Filestack storage alias, or an array of handles and urls to be zipped. The zip task has no additional parameters.

Examples

Get information about PDF document. This task returns following information:

pdfinfo

Response

{
  "colorinfo": [
    {
      "c": 0.1442,
      "k": 0.61787,
      "m": 0.18234,
      "y": 0.19159
    },
    {
      "c": 0.18357,
      "k": 0.44799,
      "m": 0.30939,
      "y": 0.27883
    }
  ],
  "created": "2017-07-13T11:59:59-05",
  "encrypted": false,
  "hasform": false,
  "hasjavascript": false,
  "isgrayscale": false,
  "isoptimized": true,
  "istagged": true,
  "pages": 2,
  "pagesize": {
    "height": 792,
    "paper": "Letter",
    "width": 612
  },
  "pdfversion": "1.7",
  "protected": false,
  "updated": "2017-07-13T12:00:01-05"
}

Examples

Merge files to create a separate PDF file using an array of Filestack handles.

pdfcreate

Note: This only works with Filestack handles.

Example

http://cdn.filestackcontent.com/pdfcreate/[handle1,handle2]

Converting PDF to specific orientation, pageformat and specific pages.

pdfconvert

Examples

Convert PDF to black and white version.

monochrome

Examples

Convert all (or selected range) document pages to images in one API call.

doc_to_images

Response

Lets assume that your document has 6 pages. When you run /doc_to_images/ task like this:

http://cdn.filestackcontent.com/doc_to_images/handle

You will receive application/json response with the ordered list of image URLs.

[
  "http://cdn.filestackcontent.com/doc_to_images@1/handle",
  "http://cdn.filestackcontent.com/doc_to_images@2/handle",
  "http://cdn.filestackcontent.com/doc_to_images@3/handle",
  "http://cdn.filestackcontent.com/doc_to_images@4/handle",
  "http://cdn.filestackcontent.com/doc_to_images@5/handle",
  "http://cdn.filestackcontent.com/doc_to_images@6/handle"
 ]

Please notice the syntax:

doc_to_images@N

where N is the number of the image. Those numbers do not match page numbers (if you use page ranges) and are used only as unique identifiers for the images in the list.

Examples

Currently, depending on the device in use, video and audio files can be saved in different formats. Our video and audio transcoding features help with converting the files to the type and format you would like to use in your application.

Video and Audio Transcoding are included on the Grow and higher plans.

Please learn more about our Video and Audio Transformations here.

Many of the Filestack conversion options allow you to set a color for the background, border or other parameter. The following is a list of defined color options. You can set any color you want using the hexadecimal (or shortened hexadecimal) code, but there is a set list of defined color words Filestack accepts.

With Filestack’s Workflows, you can automate tasks such as image enhancement, file conversions, facial detection, etc., and chain them into a workflow, boosting efficiency. To learn more, check out our Workflow API Processing documentation page.