Files and Images New

LAST EDIT Jan 24 2021

This API endpoint allows you to upload files and to process your images (eg. create image thumbnails).

This functionality defaults to using the Stream CDN. If you would like, you can easily change the logic to upload to your own CDN of choice.



Image and files have separate API endpoints (e.g. images can be resized, whereas files cannot). Once the upload is completed the URL of the file/image is returned and is ready for use.

Upload size is limited to 10MB, any attempt to upload a larger file will return an HTTP 413 error. Please contact support if you need to upload larger files.
Individual uploads will count against your stored files quota. Retrieving a file from the Stream CDN will count against your monthly files bandwidth quota. You can get more info on our pricing page.

The Stream CDN URL returned during the upload contains a signature that validates the access to the file it points to. Links can only be accessed with a signature, which also protects against enumeration attacks.

A single Stream CDN URL expires after 14 days, after which its signature will stop working and the link won't be valid anymore. You can check when a link will expire by comparing the current time with the Unix timestamp in the Expires parameter of the link's query:

If a link is expired, you can refresh it with a single call, which will return a new, fresh link:



Files and images can be deleted using their URL.

The file/image will still be available on the CDN until their cache is expired.

Image Processing


Once an image is uploaded, it is possible to create variants of the same in different sizes. The image to manipulate is selected using its URL. A new URL is then returned by the API.

Resized images will count against your stored files quota.


resizestringthe strategy used to adapt the image the new dimensionsclip
cropstringthe cropping modecenter
wnumberthe final width of the processed image-
hnumberthe final height of the processed image. -



The resize parameter determines how the new image dimensions are applied. The default value for this parameter is "clip".

Allowed values:

  • clip fits the image within the width and height boundaries without cropping or changing the aspect ratio.

  • crop applies the new dimensions and keeps the aspect ratio by cropping the parts of the image outside of the new boundaries. You can use the crop parameter to control how the cropping is done.

  • scale applies the new dimensions to the image. This method does not respect the aspect ratio and can create distorted images.

  • fill same as "clip" but the resulting image will have the exact dimensions requested and filled with a solid background color.



When resizing the image with a crop you can specify the cropping direction. By default, images are cropped started from their center. You combine directions in order to pick corners. Eg. "top,left" will use the top left corner as cropping position.

Allowed values:

  • top, bottom, left, right, center