Files and Images

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

Upload

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.

The returned URL is served via CDN and can be requested by anyone. In order to avoid resource enumeration attacks, a unique signature is added. Manipulating the returned URL will likely result in HTTP errors. Every time that you retrieve the activity/reaction/collection where the file/image was uploaded, the URL will be refreshed.

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: https://us-east.stream-io-cdn.com/0000/images/foo.png?…&Expires=1602666347&…

// uploading an image from the browser (input is a <input type="file"> form field)
client.images.upload(input.files[0]);

// uploading an image from React Native (imageURI is the URI of the file)
client.images.upload(imageURI);

// uploading a file from the browser (input is a <input type="file"> form field)
client.files.upload(input.files[0]);

// uploading a file from React Native (fileURI is the URI of the file)
client.files.upload(fileURI);

// uploading an image from the filesystem
await client.images.upload(AttachmentFile(path: imageURI));
 
// uploading a file from the filesystem
await client.files.upload(AttachmentFile(path: fileURI));

Delete

Files and images can be deleted using their URL.

// deleting an image using the url returned by the APIs
client.images.delete(imageURL);

// deleting a file using the url returned by the APIs
client.files.delete(fileURL);

// deleting an image using the url returned by the APIs
await client.images.delete(imageUrl!);
 
// deleting a file using the url returned by the APIs
await client.files.delete(fileUrl!);

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.

Parameters

Resize

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.

Crop

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

// create a 50x50 thumbnail and crop from center
client.images.process(imageURL, { h:50, w:50, resize:'crop' });

// create a 50x50 thumbnail using clipping (keeps aspect ratio)
client.images.process(imageURL, { h:50, w:50, resize:'clip' });

// crop an image from center (by default) with size 50x50 
await client.images.getCropped(
 imageUrl!,
 const Crop(50, 50),
);

// resize an image with size 50x50 using clipping by default (keeps aspect ratio)
await client.images.getResized(
 imageUrl,
 const Resize(50, 50),
);