Processing API

Overview

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

Security

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.

Legend

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

Control Tasks

Cache

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.

Store

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"
    }
  }
}

Fallback

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

• Request without a fallback. DOC to DOC conversion will fail:

  https://cdn.filestackcontent.com/<apikey>/output=f:doc/http://www.snee.com/xml/xslt/sample.doc

• Fallback with handle:

  https://cdn.filestackcontent.com/<apikey>/output=f:doc/fallback=file:grKLLdxJQgm3VU3dRWW6/http://www.snee.com/xml/xslt/sample.doc

• Fallback with handle and 10-second cache:

  https://cdn.filestackcontent.com/<apikey>/output=f:doc/fallback=file:grKLLdxJQgm3VU3dRWW6,cache:10/http://www.snee.com/xml/xslt/sample.doc

• Fallback with handle (if fallback handle belongs to the same application)

  https://cdn.filestackcontent.com/<apikey>/security=policy:<policy>,signature:<signature>/output=f:doc/fallbacke=file:grKLLdxJQgm3VU3dRWW6/http://www.snee.com/xml/xslt/sample.doc

• Fallback to secured handle (only if it’s from another application than the source of the transformation):

  https://cdn.filestackcontent.com/<apikey>/output=f:doc/fallback=file:"grKLLdxJQgm3VU3dRWW6?policy=<policy>&signature=<signature>"/http://www.snee.com/xml/xslt/sample.doc

• Fallback to external URL:

  https://cdn.filestackcontent.com/<apikey>/output=f:doc/fallback=file:"https://www.file.com/fallback"/http://www.snee.com/xml/xslt/sample.doc

Content Disposition

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>

Image Restrictions

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.

Image Transformations

Image Size

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

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:

• clip - preserving the aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified
• crop - preserving the aspect ratio, ensure the image covers both provided dimensions by clipping/cropping to fit
• max - do not enlarge if the dimensions of the provided image are already less than the specified width or height
• scale - ignore the aspect ratio of the provided image and stretch to both provided dimensions

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:

• catrom - Catmull-Rom spline
• lanczos2 - Lanczos kernel with a=2
• lanczos3 - Lanczos kernel with a=3 (default)
• mitchell - Mitchell-Netravali spline
• nearest - Nearest-neighbour interpolation

Crop

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.

Smart Crop

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

• Basic smart crop (width and height are required parameters):

  https://cdn.filestackcontent.com/smart_crop=width:400,height:400/HANDLE

• Smart crop in the face mode:

  https://cdn.filestackcontent.com/smart_crop=width:400,height:400,mode:face/HANDLE

• Smart crop in the object mode:

  https://cdn.filestackcontent.com/smart_crop=width:400,height:400,mode:object,object:<your_object>/HANDLE

• Change the color of the bars that appears when the file is cropped:

  https://cdn.filestackcontent.com/smart_crop=width:400,height:400,mode:object,object:<your_object>,fill_color:<your_color>/HANDLE

• Smart crop with coords set to true:

  https://cdn.filestackcontent.com/smart_crop=width:400,height:400,coords:true/HANDLE

Response:

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

Rotate

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.

Flip

flip

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

Flop

flop

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

Watermark

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.

Compress

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.

Progressive JPEG

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.

Quality

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.

Strip Metadata

no_metadata

Remove any embedded metadata from an image file.

Image Enhancements

These powerful image enhancements are available for Pro plans and higher. See our pricing page for more info.

Upscale

upscale

Upscale is only available on Pro plans or higher.

Enhance

enhance

Enhance is only available on Pro plans or higher.

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

• Automatic image enhancement

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

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:

Before

After

Examples

• Image enhancement with fix_dark preset:

  https://cdn.filestackcontent.com/enhance=preset:fix_dark/HANDLE

• Chain enhance with other tasks:

  https://cdn.filestackcontent.com/resize=w:500/enhance=preset:beautify/HANDLE

Red Eye Removal

redeye

Red eye removal is only available on Pro plans or higher.

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

Image Borders and Effects

Rounded Corners

rounded_corners=blur:0.3

Vignette

vignette=amount:20

Polaroid

polaroid

Torn Edges

torn_edges=spread:[1,10]

Shadow

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

Circle

circle

Border

border=width:2

Image Filters

Sharpen

sharpen=amount:2

Blur

blur=amount:2

Monochrome

monochrome

Black and White

blackwhite=threshold:50

Sepia

sepia=tone:80

Pixelate

pixelate=amount:2

Oil Paint

oil_paint=amount:2

Negative

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

modulate=hue:155

Partial Pixelate

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

Partial Blur

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

Facial Detection

Detect Faces

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 200x200 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) [‘100x100’, ‘200x200’, ‘300x300’], 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 140x140 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
    }
]

Crop Faces

crop_faces

• mode:thumb - adds a buffer around the face object by default. Part of the image inside the buffer is always resized to the desired dimensions (w & h parameters).
• mode:crop - ignores the buffer around the face object.
• mode:fill - works in a similar manner to thumb mode, except that while thumb mode will always crop an image to fit in the whole face object while still trying to respect width and height transformations, fill mode will prioritze width and height parameters over displaying the whole face object.

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.

Pixelate Faces

pixelate_faces

Blur Faces

blur_faces

File Conversions

File Type

output

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

Parameters

Examples

• Convert file to PDF with landscape orientation using the handle:

  https://cdn.filestackcontent.com/output=format:pdf,pageorientation:landscape/HANDLE

• Convert file to JPG with quality=70 using the external URL:

  https://cdn.filestackcontent.com/APIKEY/output=format:jpg,quality:70/EXTERNAL_URL

• Convert file to PDF using our Advanced Conversion Engine:

  https://cdn.filestackcontent.com/output=f:pdf,engine:auto/HANDLE

Auto Image Conversion

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:

https://cdn.filestackcontent.com/resize=w:300/compress/wSPGjTiQtuImifba6aAQ JPEG 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.

https://cdn.filestackcontent.com/resize=w:300/auto_image/compress/wSPGjTiQtuImifba6aAQ WebP 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:

• https://caniuse.com/#feat=webp
• https://caniuse.com/#feat=jpegxr

Examples

• Automatic image encoding:

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

• Chaining with other tasks:

  https://cdn.filestackcontent.com/auto_image/resize=width:400,fit:max/compress/HANDLE

Animate (Images to GIF)

animate

Animate task converts set of images to a GIF file.

Examples

• Animate images every second in a loop and produce 200x300 GIF file:

  https://cdn.filestackcontent.com/animate=fit:scale,width:200,height:300/[HANDLE1,HANDLE2,HANDLE3,HANDLE4,HANDLE5]

Limitations

Collage

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.

ASCII

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.

URL Screenshot

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.

QR Code

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.

Parameters

Below you can see the example of the result:

https://cdn.filestackcontent.com/qr/xBfYjbEJT0Wpkh2s0MK0

Examples

• Create QR code using the handle:

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

• Create QR code using the external URL:

  https://cdn.filestackcontent.com/qr/EXTERNAL_URL

• Create QR code using additional parameters of this task:

  https://cdn.filestackcontent.com/qr=version:4,error_correction:L,format:svg/HANDLE

ZIP

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

• Create a zip archive using the array of handles:

  https://cdn.filestackcontent.com/APIKEY/zip/[HANDLE1,HANDLE2]

• Create a zip archive using the array of URLs:

  https://cdn.filestackcontent.com/APIKEY/zip/[URL1,URL2]

• Create a zip archive combining the array of handles and URLs:

  https://cdn.filestackcontent.com/APIKEY/zip/[HANDLE1,URL1]

• Create a zip archive with the custom filename using the Content Disposition task:

  https://cdn.filestackcontent.com/APIKEY/zip/content=filename:"filename.zip"/[URL1,URL2]

Document Transformations

PDF Info

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

• Get color information:

  https://cdn.filestackcontent.com/output=f:pdf/pdfinfo=colorinfo:true/HANDLE

PDF Create

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]

PDF Conversions

Converting PDF to specific orientation, pageformat and specific pages.

pdfconvert

Examples

• Convert to specific orientation and format:

  https://cdn.filestackcontent.com/output=f:pdf/pdfconvert=pageorientation:landscape,pageformat:a3/HANDLE

• With specific page range.

  https://cdn.filestackcontent.com/output=f:pdf/pdfconvert=pageorientation:landscape,pageformat:a3,pages:[2,3,4]/HANDLE

PDF Monochrome

Convert PDF to black and white version.

monochrome

Examples

• Convert some of the PDF pages to specific orientation and format in black and white:

  https://cdn.filestackcontent.com/output=f:pdf/pdfconvert=pageorientation:landscape,pageformat:a3,pages:[2,3,4]/monochrome/HANDLE

Document to Images

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

• Convert specific page range with high density

  http://cdn.filestackcontent.com/doc_to_images=pages:[1-3,5],density:300/handle

• Ignore hidden slides from the pptx file

  http://cdn.filestackcontent.com/doc_to_images=pages:[1-3,5],density:300,hidden_slides:false/handle

• Change output format from jpg to png

  http://cdn.filestackcontent.com/doc_to_images=pages:[1-3,5],format:png/handle

• Use external URL

  http://cdn.filestackcontent.com/APIKEY/doc_to_images=pages:[1-3,5]/http://www.snee.com/xml/xslt/sample.doc

Audio and Video

Video and audio transcoding overview

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.

Color Options

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.

Automate Transformations

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.