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.

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:

Parameters

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

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/

Examples

Sets Content-Disposition header for the given file.

Examples

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.

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

{"height":1280,"width":1280}

• Use the original image CDN URL and add the desired resize values (height and width), or use the custom fits mentioned above.

Original Image

• Resize the image by manually inserting the width and height values to the image’s URL as follows:

https://cdn.filestackcontent.com/resize=width:100,height:200/HANDLE

• It is also possible to use a custom fit to resize your image; the example below uses the scale fit.

https://cdn.filestackcontent.com/resize=width:350,height:500,fit:scale/HANDLE

• Use the cropping values to select the part of the image that you wish to highlight.

Original Image

• Crop the image by inputting the 4 required values. The example below shows the CDN used to crop the image.

https://cdn.filestackcontent.com/crop=dim:[0,200,1000,500]/HANDLE

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

• Choose the number of degrees to rotate your image.

Original Image

• Rotate the image by the required number of degrees; the following example rotates it by 180 degrees.

https://cdn.filestackcontent.com/rotate=deg:180/HANDLE

Original Image

• Flip the image vertically by simply adding the flip feature to your CDN URL,  as shown below:

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

Original Image

• Add the flop feature to your CDN URL to change the image’s position horizontally, as shown below:

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

Original Image

• Find the second image URL handle and add it as a watermark to the original image. You can also choose the size and position as shown below.

https://cdn.filestackcontent.com/watermark:f:<img_handle>,size:80,position:[bottom,%20left]/HANDLE

• Ensure you select a .JPG or .PNG and add the compress keyword to your cdn code.

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

Original Image

• Add pjpg to your CDN URL and choose the desired value. See the example below:

https://cdn.filestackcontent.com/pjpg=quality:25/HANDLE

Original Image

• Add quality to your CDN URL and choose the desired value. See the example below:

https://cdn.filestackcontent.com/quality=value:60/HANDLE

• Remove all metadata by adding the no_metadata keyword to your CDN URL.

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

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

Original Image

• Use the sharpen task to enhance your image by boosting its clarity.

/sharpen=amount:8/

• Blur the entire image by selecting the amount of blur you want. The example below adds a level of 12 for blur.

/blur=amount:12/

/monochrome/

• The example below uses the black-and-white task with a threshold of 38 to cast the image’s effect.

/blackwhite=threshold:38/

/sepia=tone:80/

• Pixelate the entire image by selecting the desired amount. The example below sets the pixelation level to 15.

/pixelate=amount:15/

• The example below returns an image with the oil paint effect, with a level of 6.

/oil_paint=amount:6/

/negative/

• The example below plays with the saturation, hue, and brightness parameters to achieve the modulate effect.

/modulate=saturation:150,hue:15,brightness:100/

/modulate=hue:155/

• In the example below, the coordinates were selected to partially pixelate some faces at a pixelation level of 50.

/partial_pixelate=objects:[[420,600,200,200],[420,600,200,200]],amount:50/

• For the example below, the coordinates were chosen as well as a blur amount of 10 and an oval type.

/partial_blur=objects:[[420,600,200,200],[420,600,200,200]],amount:10,type:oval/

• When using the detect_faces task, the image instantly numbers the detected faces based on proximity.

/detect_faces/

• Setting export:true exports all face objects to a JSON object. In the image above, the export task exports all face objects from the image to a JSON file.

[
    {
        "id": 1,
        "x": 226,
        "y": 215,
        "width": 50,
        "height": 68,       
    },
    {
        "id": 2,
        "x": 103,
        "y": 364,
        "width": 36,
        "height": 40,
    },
    {
        "id": 3,
        "x": 359,
        "y": 377,
        "width": 35,
        "height": 38,
    }
]

/detect_faces=export:true/

Original Image

• The following image displays a group of friends. The example below uses fill mode to select which faces to crop in the edited image.

/crop_faces=faces:[2,4],mode:fill/

• The example below uses the faces parameter and an array of values to select which faces to pixelate.

/pixelate_faces=type:rect,faces:[2,3,4,5],amount:30/

• The blur example below uses the faces parameter and an array of values to select which faces to blur. Additionally, it specifies the blur type to be oval.

/blur_faces=type:oval,faces:[2,3,4,5],blur:18/

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.