Processing API

Overview

All stored files in your application are available over the Filestack CDN, and each file’s URL can be modified with processing “tasks” that modify the requested resource. Each task has its own set of parameters that are documented on this page. Our API Clients provide programmatic access to construct these transformation URLs.

Processing tasks can be chained together in the same URL by separating them with forward slashes. All tasks follow the structure of TASK=option:value, where option:value pairs are comma separated.

https://cdn.filestackcontent.com /resize=height:200/ v8x4EUOKRS6OowxpkY8i

You may make processing requests with either a Filestack handle, a Filestack storage alias, or a public URL. If using a URL or storage alias, your API key must be prepended to the task chain, like this:

https://cdn.filestackcontent.com /YOUR APIKEY /TASKS /URL

You may chain together as many tasks as you like, presuming their types logically follow. Tasks are executed in the order they appear in the URL, and are separated by forward slashes.

This resizes the height of the image to 200 pixels (while preserving aspect ratio), and then modifies the hue of the image.

https://cdn.filestackcontent.com /resize=height:200 /modulate=hue:155 /v8x4EUOKRS6OowxpkY8i

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 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 which contains this task will return a JSON response. Example:

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

Debug

debug

You can use the debug task to get information about a specific transform request, including success and error messages, metadata, and so forth. Debug can be prepended to any transformation URL, for example:

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

A debug GET request will return data as JSON. You can use this to make inferences, debug, and store data about your transformations:

{
  "apikey": "APIKEY",
  "status": {
    "message": "OK",
    "http_code": 200
  },
  "start_time": "2019-03-20T17:54:03.764798629Z",
  "processing_time": "29.819537ms",
  "source": [
    {
      "url": "https://www.filestackapi.com/api/file/HANDLE",
      "mimetype": "image/jpeg",
      "size": 0
    }
  ],
  "task_uri": "resize=width:100,height:100",
  "debug": true,
  "chain": [
    {
      "provider": "conv20",
      "tasks": [
        {
          "name": "resize",
          "params": {
            "align": "center",
            "fit": "clip",
            "height": 100,
            "width": 100
          }
        }
      ],
      "status": {
        "message": "OK",
        "http_code": 200
      },
      "start_time": "2019-03-20T17:54:03.78255033Z",
      "processing_time": "12.066335ms",
      "size": 4125,
      "mimetype": "image/jpeg"
    }
  ]
}

Fallback

fallback=handle:<handle>,cache:<cache>

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

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

/fallback=handle:"<handle>?policy=<policy>&signature=<signature>",cache:10/.

You can read more about security policies here.

Examples

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

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

• Fallback:

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

• Fallback with 10 second cache:

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

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

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

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

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

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

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.

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. Enhance requires no additional parameters.

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=format:FILE_TYPE

See our File Conversion Matrix for info on all supported conversions.

density will adjust the resolution when converting documents like PowerPoint, PDF, AI and EPS files to image formats like JPG or PNG. Higher density values mean higher resolutions, which will improve the image quality.

docinfo can be used to get information about a document, such as the number of pages and the dimensions of the file. This information is delivered as a JSON object, for example:

{"numpages":41,"dimensions":{"width":538,"height":718}}

strip can be used to remove embedded file metadata.

secure applies to conversions of HTML and SVG sources. When the secure parameter is set to true, the HTML or SVG file will be stripped of any insecure tags (HTML sanitization).

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.

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.

Document Transformations

PDF Info

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

pdfinfo=colorinfo:<colorinfo>

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 Conversions

Converting PDF to specific orientation, pageformat and specific pages.

pdfconvert=pageorientation:<pageorientation>,pageformat:<pageformat>,pages:<pages>

Examples

• Convert to specific orientation, format:

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

• With specific pages.

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

Audio and Video

video_convert

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

Most tasks return content directly, but A/V tasks return job metadata because they run asynchronously. When requesting an audio or video conversion:

https://cdn.filestackcontent.com/video_convert=height:260,width:350/HANDLE

You will receieve an initial JSON response:

{
    "data":{},
    "metadata": {
        "result":{},
        "source":{}
    },
    "status":"started",
    "timestamp":"1522783969",
    "uuid":"5c0f33cc9c464e16592b7a01f6f8f5c1"
}

Polling the URL will eventually yield a response with populated results. If you would like to receive this asynchronously upon completion (no polling), please refer to our webhooks documentation.

Completed A/V response:

{
    "data":{
        "thumb":"https://cdn.filestackcontent.com/HANDLE",
        "thumb100x100":"https://process.filestackapi.com/APIKEY/resize=w:100,h:100,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/HANDLE",
        "thumb200x200":"https://process.filestackapi.com/APIKEY/resize=w:200,h:200,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/HANDLE",
        "thumb300x300":"https://process.filestackapi.com/APIKEY/resize=w:300,h:300,f:crop/output=f:jpg,q:66/https://cdn.filestackcontent.com/HANDLE",
        "url":"https://cdn.filestackcontent.com/HANDLE"
    },
    "metadata": {
        "result": {
            "audio_bitrate":128,
            "audio_channels":1,
            "audio_codec":"aac",
            "audio_sample_rate":44100,
            "created_at":"2018/04/03 20:15:50 +0000",
            "duration":5615,
            "encoding_progress":100,
            "encoding_time":2,
            "extname":".mp4",
            "file_size":150791,
            "fps":30,
            "height":260,
            "mime_type":"video/mp4",
            "started_encoding_at":"2018/04/03 20:15:51 +0000",
            "updated_at":"2018/04/03 20:15:55 +0000",
            "video_bitrate":81,
            "video_codec":"h264",
            "width":350
        },
        "source": {
            "audio_bitrate":83,
            "audio_channels":1,
            "audio_codec":"aac",
            "audio_sample_rate":48000,
            "created_at":"2018/04/03 20:15:50 +0000",
            "duration":5568,
            "extname":".mp4",
            "file_size":383631,
            "fps":30,
            "height":320,
            "mime_type":"video/mp4",
            "updated_at":"2018/04/03 20:15:55 +0000",
            "video_bitrate":465,
            "video_codec":"h264",
            "width":560
        }
    },
    "status":"completed",
    "timestamp":"1522786635",
    "uuid":"UUID"
}

Supported Formats

• h264
• h264.hi
• webm
• webm.hi
• ogg
• ogg.hi
• hls.variant
• mp3
• oga
• m4a
• aac
• hls.variant.audio

Note: When using the HLS preset, many files will be generated in your storage container and we will return you a special processing engine link to the playlist file:

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

The video_playlist task generates the playlist dynamically so that all the segments in the playlist can have the same security policy and signature applied in the request if security is enabled for your API key.

Note: Each second of audio or video transcoding counts as 2 transformations. Please take your plan’s conversion limits into account before processing any audio, as you can quickly exceed your plan’s limits and incur overages.

You can restart a failed or pending transcoding by specifying force:true.

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.