Batch Image Processing API Documentation

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Requests

We provide an HTTP API with three endpoints to Create, Get and Retry Batch Image Processes.

All requests' body and response data are in JS format.

Base URL

All URLs referenced in the documentation have the following base: https://batch.slashed.cloud/

Authentication

We use Bearer Tokens to authenticate requests. You can find your token on your Dashboard. The Bearer Token must be included in all requests to the API in the Authorization header.

Example

curl https://batch.slashed.cloud/request -H 'Authorization: Bearer q77D1lMk...5Vh42Gzx'

We use HTTP response status codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request body couldn't be parsed, etc.), and codes in the 5xx range indicate an error with our servers.

Some errors may also include extra information in the response body. The error's message field will contain a human-readable explanation of the error.

Status	Description
🟢 200 OK	Request worked as expected
🟠 400 Bad Request	Missing or invalid body parameters
🟠 401 Unauthorized	Missing or invalid API secret
🟠 403 Forbidden	Valid API secret but no access to requested resource
🟠 404 Not Found	Requested resource was not found
🟠 429 Too Many Requests	Too many requests in a short period of time
🔴 500 Internal Server Error	Unexpected error on our end

1. Create Batch Image Transformation Process

Create a new batch image transformation process. The process ID will be returned in the response.

POST https://batch.slashed.cloud/request

Note: Requires Bearer Token

Parameters

service_id : number

Required

Your service ID, which is a unique identifier for the service you are using. It's essential to include this in your request so that the server knows which service you are accessing.

callback : string

This is the callback URL. After the server processes your batch request and completes the specified transformations, it will send the response back to this URL.

source : string

Required

The source file that you want to transform. The source file must be in the storage that you have set up.

jobs : array

Required

This is an array of jobs to be applied to the source file - In this example we have a transformation.

Batch Example Request

		{
  "service_id": 1,
  "source": "/480x360/1.jpg",
  "jobs": [
    {
      "destination": "/480x360/transformed/1.jpg",
      "quality": 70,
      "transformations": [
        {
          "type": "annotation",
          "font": "Arial",
          "color": "#000000",
          "text": "Test text",
          "size": 10,
          "gravity": "center"
        }
      ]
    }
  ]
}

1.1 Jobs

Each job has its own destination, quality parameter and transformation array. Below are the parameters for each.

1.2.1 Batch Job Parameters

destination : string

Required

The destination of the transformed file. The destination file must be in the storage that you have set up.

quality : string

The quality of the transformed file. The quality can be a number between 0 and 100. Default is 70.

transformations : array

Required

This is an array of transformations to be applied to the source file.

Example Batch Job

		[
  {
    "destination": "/480x360/transformed/1.jpg",
    "quality": 70,
    "transformations": [
      {
        "type": "annotation",
        "font": "Arial",
        "color": "#000000",
        "text": "Test text",
        "size": 10,
        "gravity": "center"
      }
    ]
  }
]

1.2 Transformations

1.2.1 Annotation

type : 'annotation'

Required

font : string

Required

This parameter sets the font. Must be a string.

color : string

Required

This parameter sets the color. Must be hexadecimal.

text : string

Required

This parameter sets the text. Must be a string.

size : number

Required

This parameter sets the size. Must be a number.

gravity : string

This parameter sets the gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'.

xoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Width Parameter with Percentage (%): Only one of 'width' or 'height' is required.

yoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Height Parameter with Percentage (%): Only one of 'width' or 'height' is required.

Example Annotation

		{
  "type": "annotation",
  "font": "Arial",
  "color": "#000000",
  "text": "Test text",
  "size": 10,
  "gravity": "center"
}

1.2.2 Blur

type : 'blur'

Required

sigma : number

Required

This parameter sets the sigma. Must be a number.

radius : number

Required

This parameter sets the radius. Must be a number.

Example Blur

		{
  "type": "blur",
  "sigma": 218,
  "radius": 465
}

1.2.3 Brightness

type : 'brightness'

Required

bright_level : number

Required

This parameter sets the brightness level. Must be a number between -255 and 255.

Example Brightness

		{
  "type": "brightness",
  "bright_level": 230
}

1.2.4 Colorize

type : 'colorize'

Required

red : number

Required

This parameter sets the red level. Must be a number between 0 and 255.

green : number

Required

This parameter sets the green level. Must be a number between 0 and 255.

blue : number

Required

This parameter sets the blue level. Must be a number between 0 and 255.

Example Colorize

		{
  "type": "colorize",
  "red": 200,
  "green": 120,
  "blue": 150
}

1.2.5 Contrast

type : 'contrast'

Required

level : number

Required

This parameter sets the contrast level. Must be a number between -100 and 100.

Example Contrast

		{
  "type": "contrast",
  "level": 55
}

1.2.6 Crop

type : 'crop'

Required

gravity : string

Required

This parameter sets the gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'.

width : string | number

Required

Possible values:
Pixels: 100, "100" or "100px"
Percentage of the original width: "100%"
Percentage of the original height: "100h"

Width Parameter with Percentage (%): Only one of 'width' or 'height' is required.

height : string | number

Required

Possible values:
Pixels: 100, "100" or "100px"
Percentage of the original height: "100%"
Percentage of the original width: "100w"

Height Parameter with Percentage (%): Only one of 'width' or 'height' is required.

xoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Width Parameter with Percentage (%): Only one of 'width' or 'height' is required.

yoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Height Parameter with Percentage (%): Only one of 'width' or 'height' is required.

fit : boolean

This parameter calculates the best fit. Must be a boolean. Defaults to true.

Ensures that the image fits within certain dimensions (presumably maximum dimensions) while maintaining its original aspect ratio, if the fit parameter is set to true. It's a way to prevent the image from becoming too large or too distorted during resizing.

Example Crop

		{
  "type": "crop",
  "gravity": "center",
  "width": "750",
  "height": "500",
  "yoffset": "300",
  "xoffset": "500",
  "fit": true
}

1.2.7 Enhance

type : 'enhance'

Required

Example Enhance

		{
  "type": "enhance"
}

1.2.8 Filter

type : 'filter'

Required

filter : string

Required

This parameter sets the filter. Must be one of 'bw', 'sepia', 'negate', 'grayscale', 'edgedetect', 'emboss', 'blurgaussian', 'blurselective', 'meanremoval', 'smooth'.

Example Filter

		{
  "type": "filter",
  "filter": "sepia"
}

1.2.9 Fitmethod

type : 'fitmethod'

Required

color : string

Required

This parameter sets the color. Must be hexadecimal.

fit_type : string

Required

This parameter sets the fit type. Must be one of 'box', 'stretch', 'cropbox', 'letterbox', 'outside'.

gravity : string

Required

This parameter sets the gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'.

width : string | number

Required

height : string | number

Required

opacity : number

This parameter sets the opacity. Must be a number between 0 and 10.

Example Fitmethod

		{
  "type": "fitmethod",
  "color": "#000000",
  "fit_type": "cropbox",
  "gravity": "center",
  "width": 550,
  "height": 300,
  "opacity": 0
}

1.2.10 Flip

type : 'flip'

Required

direction : string

Required

This parameter sets the direction of the flip. Must be one of 'x', 'y', 'vertical' or 'horizontal'.

Example Flip

		{
  "type": "flip",
  "direction": "y"
}

1.2.11 Resize

type : 'resize'

Required

width : string | number

Required

height : string | number

Required

Example Resize

		{
  "type": "resize",
  "width": 500,
  "height": 300
}

1.2.12 Rotate

type : 'rotate'

Required

degrees : number

Required

This parameter sets the degrees of the rotation. Must be a number between 0 and 360 with up to two decimal places.

Example Rotate

		{
  "type": "rotate",
  "degrees": 20
}

1.2.13 Ulb

type : 'ulb'

Required

Example Ulb

		{
  "type": "ulb"
}

1.2.14 Watermark

type : 'watermark'

Required

gravity : string

Required

This parameter sets the gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'.

width : string | number

Required

height : string | number

Required

Source : string

Required

This parameter sets the source of the watermark.

xoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Width Parameter with Percentage (%): Only one of 'width' or 'height' is required.

yoffset : string | number

Can be a negative value. Possible values:
Pixels: 100, "100" or "100px"
Percentage: "100%"

Height Parameter with Percentage (%): Only one of 'width' or 'height' is required.

Example Watermark

		{
  "type": "watermark",
  "gravity": "middle",
  "width": 200,
  "height": 200,
  "source": "watermark.png",
  "yoffset": 0,
  "xoffset": 0
}

1.2.15 Zoom

type : 'zoom'

Required

width : string | number

Required

height : string | number

Required

level : number

Required

This parameter sets the level of zoom. Must be a number from 0 to 10.

Example Zoom

		{
  "type": "zoom",
  "width": "200",
  "height": "200",
  "level": 0
}

Responses

🟢 Success

		{
  "status": "SUCCESS",
  "process_id": "Fcl_b6psriLi7lBYAshhp"
}

🟠 Error

		{
  "message": "Invalid Secret"
}

2. Get Process Status

GET https://batch.slashed.cloud/status/Fcl_b6psriLi7lBYAshhp

Responses

🟢 Success

		{
  "status": "FINISHED",
  "updated_at": "2024-01-01 08:00:00"
}

🟠 Error

		{
  "status": "FAILED",
  "updated_at": "2024-01-01 08:00:00"
}

3. Retry Processes

POST https://batch.slashed.cloud/retry

Parameters

service_id : number

Required

Your service ID, which is a unique identifier for the service you are using. It's essential to include this in your request so that the server knows which service you are accessing.

process_ids : array

Required

This is an array of process IDs to be reprocessed.

Example Retry Request

		{
  "service_id": 1,
  "process_ids": [
    "1mQhK6J7azYy9LKo7Rbxp",
    "eeTP9A-jMrljQiDS1_K2S"
  ]
}

Responses

🟢 Success

		[
  {
    "status": 200,
    "process_id": "1mQhK6J7azYy9LKo7Rbxp",
    "description": "Reprocessing process, attempt: 1"
  },
  {
    "status": 200,
    "process_id": "eeTP9A-jMrljQiDS1_K2S",
    "description": "Reprocessing process, attempt: 1"
  }
]

🟠 Error

		{
  "status": 404,
  "process_id": "krLSWSF0gp6tpWPk3Okrl",
  "description": "Process not found"
}

Batch Image Processing API Documentation

Requests

Base URL

Authentication

Errors

1. Create Batch Image Transformation Process

Parameters

1.1 Jobs

1.2 Transformations

1.2.1 Annotation

1.2.2 Blur

1.2.3 Brightness

1.2.4 Colorize

1.2.5 Contrast

1.2.6 Crop

1.2.7 Enhance

1.2.8 Filter

1.2.9 Fitmethod

1.2.10 Flip

1.2.11 Resize

1.2.12 Rotate

1.2.13 Ulb

1.2.14 Watermark

1.2.15 Zoom

Responses

2. Get Process Status

Responses

3. Retry Processes

Parameters

Responses