Rest API

Obtaining an access token

First Step: To use the Scaler APIs successfully, obtain an access token.
POST /auth/api-key-token HTTP/1.1
Host: api.scaler.pics
Authorization: Bearer YOUR_API_KEY
Response: A JSON object containing the access token. The token is valid for 30 minutes and can be used for multiple image transformations.
{
	"accessToken": "YOUR_ACCESS_TOKEN"
}

Signing transform URL

To execute an image transformation, you need to create a signed URL. This step enhances security and helps balance the load among different workers. Below is an example of how to create a signed URL for image transformation. Refer to Transform Options for a full specification of the body parameters.
POST /sign HTTP/1.1
Host: sign.scaler.pics
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
	"input": "body",
	"output": [
		{
			"type": "jpeg",
			"fit": {
				"width": 512,
				"height": 512
			},
			"quality": 0.8
		}
	]
}
Response: A JSON object containing the signed URL.
{
	"url": "SIGNED_URL"
}

Transforming the image

Now you can use the generated URL to execute the transformation of the image.
POST /SIGNED_URL_PATH HTTP/1.1
Host: SIGNED_URL_HOST
If the input parameter was set as "body" in your Transform Options, you will need to post image binary data as the body of the request.

Transform response

A typical response will look like this:
{
	"inputImage": {
		"pixelSize": { "width": 4032, "height": 3024 },
		"byteSize": 2938293
	},
	"outputImage": [
		{
			"fit": { "width": 512, "height": 512 },
			"pixelSize": { "width": 512, "height": 325 },
			"downloadUrl": 
				"https://w1.scaler.pics/temp/f93o-512x325.jpg",
			"fileId": "f93o-512x325.jpg"
		}
	],
	"deteleUrl": "https://w1.scaler.pics/image"
}

If you choose to download the image after transformation in your Transform Options, you will receive a download URL in the response as shown above. To complete the process, you need to download the image from the provided temporary URL, which is valid for only 15 minutes.

To cleanup the images from the server after successfull download you can call provided deleteUrl in the following way:

DELETE /DELETE_URL_PATH HTTP/1.1
Host: DELETE_URL_HOST
Content-Type: application/json

{ 
	images: ["f93o-512x325.jpg"]
}

Transfrom Options

Below are TypeScript interfaces for the available options, designed to be self-explanatory.
interface TransformOptions {
	input: 'body' | URLString;
	output: Output[];
	crop?: NormalizedCrop;
}

type URLString = string;

interface Output {
	fit: Fit;
	type: OutputImageType;
	quality?: number;
	upload?: Upload;
}

interface Fit {
	width: number;
	height: number;
	updscale?: boolean;
}

type OutputImageType = 
	'jpeg' | 'png' | 'heic';

interface Upload {
	url: string;
	method?: 'POST' | 'PUT';
}

interface NormalizedCrop {
	left: number;
	top: number;
	right: number;
	bottom: number;
}

The input parameter should have the value "body", requiring you to supply image data as the body of the transform request, or as a URL string to the image you want to transform, which will be downloaded by the worker. Ensure the image is accessible by the worker.

You can specify up to 10 output images. Each output has an optional upload parameter; if specified, the image will be uploaded to the provided URL. This feature is useful for uploading images to storage services like AWS S3 or Google Cloud Storage. If the upload parameter is not provided, you will need to download the image from the temporary download URL provided in the response.

Transfrom Response

TypeScript interfaces for the response are designed to be self-explanatory.
interface TransfomResponse {
	inputImage: InputImageInfo;
	outputImages: [OutputImage];
	deleteUrl: string;
	timeStats: {
		transformMs: number;
		uploadImagesMs?: number;
	};
}

interface InputImage {
	pixelSize: Size;
	byteSize: number;
}

interface OutputImage {
	fit: Fit;
	pixelSize: Size;
	downloadUrl?: string;
	fileId?: string;
}

interface Fit {
	width: number;
	height: number;
	updscale?: boolean;
}

interface Size {
	width: number;
	height: number;
}