Getting Started

Filestack Architecture

File Upload

File Export (Save To)

Responsive Images

Image Transformations

Document Transformations

Video Transcoding

Audio Transcoding





Filestack Viewer


Supported Cloud Drives

Filestack Recipes

Filestack Integrations

Filestack SDKs

Register for an API key

Convert a file with the Javascript API

In addition to storing files and raw data, you can store the contents of URLs directly as well.

Sample Code
var blob = { url: '', filename: 'robot.png', mimetype: 'image/png', isWriteable: false, size: 28683 }; console.log("Converting..."); /*an <img> element where we can display the resulting image*/ var result = document.getElementById("convert-result"); filepicker.convert( blob, { width: 200, height: 200 }, function(new_Blob){ var img = document.createElement('img'); img.src = new_Blob.url; result.removeChild(result.firstChild); result.appendChild(img); console.log("Convert successful"); console.log(new_Blob.url); } );

Run code above


filepicker.convert(Blob, conversion_options, storage_options, onSuccess(Blob){}, onError(FPError){}, onProgress(percent){})
Blob The Filestack Blob to use as the base for the conversion. If you need to apply a conversion to a raw image, you should first use the call to get a Blob.

A dictionary of key-value pairs that configure the conversion.


{width: 200}

Resize the inputted image to be the specified width, in pixels. Ignored if the file is not an image.


{height: 200}

Resize the inputted image to be the specified height, in pixels. Ignored if the file is not an image.


{fit: 'clip'}

Specifies how to resize the image. Possible values are:

clip Resizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio
crop Resizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries
scale Resizes the image to fit the specified parameters exactly by scaling the image to the desired size
max Resizes the image to fit within the parameters, but as opposed to 'clip' will not scale the image if the image is smaller than the output size

Defaults to "clip".


{align: 'faces'}

Determines how the image is aligned when resizing and using the "fit" parameter. Possible values are:

top Crop aligned with the top of the image
bottom Crop aligned with the bottom of the image
left Crop aligned with the left edge of the image
right Crop aligned with the right edge of the image
faces Search for faces, and if found, crop such that the faces are aligned in the center of the resized image.

Defaults to cropping to the center of the image.


{crop: [20, 20, 100, 100]}

Crops the image to the specified rectangle, given by [x, y, width, height], where x is the distance in pixels from the left edge and y is the distance in pixels from the top edge.


{crop_first: true}

Makes sure the image is cropped before any other conversion parameters are executed.The only value for this parameter is true.


{format: 'jpg'}

Specifies what format the image should be converted to, if any. Possible values are "jpg" and "png". For "jpg" conversions, you can additionally specify a quality parameter.


{filter: 'blur'}

Specifies which filter to use. Available filters are:

blur Blurs the image. You can additionally specify a "blurAmount" parameter. As you increase "blurAmount", the image becomes more blurry. Default value is 2.
sharpen Sharpens the image. You can additionally specify a "sharpenAmount" parameter. As you increase the "sharpenAmount", sharpening becomes more obvious. Default value is 2.


{compress: true}

For jpeg or png files, specifies whether image should be compressed. Possible values: true or false.


{quality: 75}

For jpeg conversion, specifies the quality of the resultant image. Quality should be an integer between 1 and 100


{rotate: "exif"} or {rotate: 180}

Rotate the image. Default is no rotation. {rotate:"exif"} will rotate the image automatically based on the exif data in the image. Other valid values are integers between 0 and 359, for degrees of rotation.


{watermark: '

Adds the specified absolute url as a watermark on the image.

Watermark Size

{watermark_size: 30}

Scale the watermark to the given size, which is a percentage of the base image (not the original watermark).

Watermark Position

{watermark_position: 'top,right'}

Align the watermark to the given edge(s) of the original image. Possible values for vertical position are "top","middle","bottom" and "left","center","right" for horizontal position. The two can be combined by separating vertical and horizontal with a comma. The default behavior is bottom,right


{policy: POLICY, signature: SIGNATURE}

If you have security enabled, you'll need to have a valid policy and signature in order to perform the requested call. This allows you to select who can and cannot perform certain actions on your site. Read more about security and how to generate policies and signatures


An optional dictionary of key-value pairs that specify how to store the converted file.


{location: 'S3'}

Where to store the file. The default is S3. Other options are 'azure', 'dropbox', 'rackspace' and 'gcs'. You must have configured your storage in the developer portal to enable this feature.

S3, Rackspace, Azure, Dropbox and Google Cloud are only available on paid plans. Choose Plan


{path: '/myfiles/1234.png'}

The path to store the file at within the specified file store. For S3, this is the key where the file will be stored at. By default, Filestack stores the file at the root at a unique id, followed by an underscore, followed by the filename, for example "3AB239102DB_myphoto.png".

If the provided path ends in a '/', it will be treated as a folder, so if the provided path is "myfiles/" and the uploaded file is named "myphoto.png", the file will be stored at "myfiles/909DFAC9CB12_myphoto.png", for example.


{container: 'user-photos'}

The bucket or container in the specified file store where the file should end up. This is especially useful if you have different containers for testing and production and you want to use them both on the same Filestack app. If this parameter is omitted, the file is stored in the default container specified in your developer portal.

Note that this parameter does not apply to the Dropbox file store.


{storeRegion: 'us-east-1'}

The region where your storage container is located. This setting currently applies only to S3 buckets. If you are using a different bucket and region than the one you set up in your developer portal you can pass the storeRegion as part of your store options. If this parameter is not set we will do our best to determine the region your S3 bucket is located so that we can properly authenticate our connection request. You can find a list of the S3 regions here: in the "region" column.

Public Access

{access: 'public'}

Indicates that the file should be stored in a way that allows public access going directly to the underlying file store. For instance, if the file is stored on S3, this will allow the S3 url to be used directly. This has no impact on the ability of users to read from the Filestack file URL. Defaults to 'private'.


The function to call if a file is converted successfully.

We'll return a Blob of the newly converted file as a JSON object with the following properties.

url The core Filestack file url on which all other operations are based.
filename The filename of the uploaded file.
mimetype The mimetype of the uploaded file.
size The size of the uploaded file in bytes, if available.
isWriteable Whether the file can be written to using filepicker.write.

The function to call if there is an error when converting the file.

Possible error codes on the FPError:

141 The inputted file cannot be found.
142 The user's file cannot be converted with the requested parameters.
143 Unknown error when converting the file.

For more info about FPErrors, see Error Handling.


The function that is called on progress events, if available. The function is called with the percent completed as a number out of 100.

Note that on older browsers, particularly IE 8 and IE 9, the browser does not provide progress events and therefore onProgress will not be called except at 100%.