Convert Images - resize, crop, and change the format of image files

In addition to uploading files and raw data, the Javascript API can also perform basic conversions on images. This method generates a new filestack link and counts as both an upload and a conversion.

Syntax

<script src="https://api.filestackapi.com/filestack.js"></script>
<script type="text/javascript">
  filepicker.setKey("your_API_KEY");
  filepicker.convert(Blob, conversion_options, storage_options, onSuccess(Blob){}, onError(FPError){}, onProgress(percent){});
</script>

Convert Code Example - Resize image to 200x200

Resize contents of blob to 200x200 and then confirm new image is different
var blob = { url: 'https://www.filestackapi.com/api/file/9BWnyKPBQI23ukbT7sZA', filename: 'robot.png', mimetype: 'image/png', isWriteable: false, size: 28683 }; filepicker.stat( blob, { width: true, height: true }, function(metadata) { console.log("Original image Dimensions:"); console.log(JSON.stringify(metadata)); } ); 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; console.log("Convert successful"); console.log("Converted image URL"); console.log(new_Blob.url); filepicker.stat( new_Blob, { width: true, height: true }, function(metadata) { console.log("Converted image Dimensions:"); console.log(JSON.stringify(metadata)); } ); } );

Parameters

blob
the file to convert
blob
Blob
{blob}

A Blob pointing to the file you would like to convert.

conversion_options
a dictionary of key-value pairs that define the conversion
width
Integer
{width: 200}

Resize the source image to the specified width in pixels. Ignored if the file is not an image.

height
Integer
{height: 200}

Resize the source image to the specified height in pixels. Ignored if the file is not an image.

fit
String
{fit: 'clip'}

Specifies how to resize the image. The default value is clip if fit is not declared. 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
align
String
{align: 'faces'}

Determines how the image is aligned when resizing and using the "fit" parameter. Defaults to cropping to the center of the image. 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 the image so that the faces are aligned in the center of the resized image.
crop
Array
{crop: [20, 20, 100, 100]}

Crops the image to the specified rectangle in pixels, given by [x, y, width, height], where x is the distance in pixels from the left edge of the image and y is the distance in pixels from the top edge of the image. For example, [0,0,100,100] would crop a 100x100 image starting from the top left corner of the image.

crop_first
Boolean
{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
Boolean
{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
String
{filter: 'blur'}

Specifies which filter to apply to the image. Available filters are:

blur Blurs the image. You can additionally specify a "blurAmount" parameter. As you increase "blurAmount", the image becomes blurrier. 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
Boolean
{compress: true}

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

quality
Integer
{quality: 75}

For jpeg conversion, specifies the quality of the resultant image. Quality should be an integer between 1 and 100. For more information about image quality and compression see the image compression page.

rotate
Integer or String
{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
String
{watermark: 'https://d3urzlae3olibs.cloudfront.net
/watermark.png'}

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

watermark size
Integer
{watermark_size: 30}

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

watermark position
String
{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

security
String
{policy: POLICY, signature: SIGNATURE}

If you have security enabled, you'll need to have a valid Filestack 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

onSuccess
The function to call if a file is picked successfully.

We'll return a Blob as a JSON object with the following properties.

url The main 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.

Sample response

{
    "url":"https://cdn.filestackcontent.com/Knu33RNOQ6qi0S5ND1mY",
    "filename":"calvinhobbes2.jpg",
    "mimetype":"image/jpeg",
    "size":71644,
    "cropped":{
      "originalImageSize":[720,540],
      "cropArea":{"position":[0,0],"size":[720,540]}
    },
    "converted":true,
    "id":1,
    "client":"computer",
    "isWriteable":true
}
onProgress
The function that is called on uploading progress events. The function will show the percent completed as a number out of 100. Multiple mode provides separate callbacks for all selected files.

We'll retrun a JSON object with the following properties:

progress Current progress as a float number.
filename The filename of the file being uploaded.
mimetype The mimetype of the file being uploaded.
size The size of the file being uploaded in bytes if available.

Sample response

{
    "progress":57.63,
    "filename":"file.jpg",
    "mimetype":"image/jpeg",
    "size":3300503
}
onError
The function to call if there is an error when picking a 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 General error when converting the file.
400 Bad parameters were passed to the server. This often will be the case when you turned on security but haven't passed up a policy or signature.
403 Invalid request - The policy and/or signature don't allow you to make this request. For more information see Security Documentation.

For more info about FPErrors, see Error Handling.

Sample response

{"code":101}