Video Encoding 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 Video Encoding Processes.

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

Base URL

All URLs referenced in the documentation have the following base: https://venc.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://venc.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
🟠 409 Too Many Requests	Limit of simultaneous processes reached
🟠 429 Too Many Requests	Too many requests in a short period of time
🔴 500 Internal Server Error	Unexpected error on our end

1. Create Video Encoding Process

Create a new video encoding process. The process ID will be returned in the response.

POST https://venc.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.

source : string

Required

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

priority : string

Specifies the priority of the request. The priority can be either 'low' or 'high'.

callback : string

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

jobs : array

Required

An array of jobs to be applied to the source file - In this example we have an encoding job. In every object we must specify the type of job we are going to apply.

Encode Example Request

		{
  "service_id": 1,
  "source": "sources/my_4k_source.mp4",
  "priority": "low",
  "callback": "https://example.org/webhook/03c58960-343e-4baf-9921-9393ade6a7aa",
  "jobs": [
    {
      "type": "encode",
      "video_codec": "av1",
      "audio_codec": "aac",
      "quality": "premium",
      "destination": "encoded_av1_1080p.mp4",
      "transformations": [
        {
          "type": "resize",
          "width": 480,
          "height": 270
        }
      ]
    }
  ]
}

1.1 Jobs

Each job has its own parameters. Below are the parameters for each job type.

1.1.1 Encode Job Parameters

Encoding refers to the process of converting a source video file into a different format or compression scheme suitable for various playback devices and platforms.

type : 'encode'

Required

video_codec : string

Required

Video codec must be one of: 'h264', 'h265' or 'av1'.

audio_codec : string

Required

We only support the aac codec at the moment.

destination : string

Required

Name of the output file.
Note: We currently only encode to the MPEG-4 container, using the ".mp4" file extension. We are working on supporting more formats in the near future.

quality : string

Video quality can be either 'standard', 'optimal' or 'premium'. Defaults to 'standard'.

The quality parameter affects the encoded video's VMAF score:

Standard is 90 VMAF

Optimal is 93 VMAF

Premium is 96 VMAF

fps : number

Number between 0 and 60. Can have up to 2 decimals. Defaults to original fps.

transformations : array of transformations

Array of transformations to apply to the video before the job. See the transformations section for more details.

Example Encode

		{
  "type": "encode",
  "video_codec": "av1",
  "audio_codec": "aac",
  "destination": "encoded_av1_1080p.mp4",
  "quality": "premium"
}

1.1.2 PreviewClip Job

Designed to generate a concise preview clip based on a given video. This functionality is particularly useful for creating teasers or highlights from longer video content. Automatically extracts a one second clip every 30 seconds.

type : 'preview_clip'

Required

destination : string

Required

Name of the output file.
Note: We currently only encode to the MPEG-4 container, using the ".mp4" file extension. We are working on supporting more formats in the near future.

num_snippets : number

Sets the amount of snippets to extract from the video. Default is 5.

snippet_duration : number

Sets the duration of each snippet in seconds. Default is 1.

video_codec : string

Sets the video codec for the output file. If not set, the codec of the input file is used.

transformations : array of transformations

Array of transformations to apply to the video before the job. See the transformations section for more details.

Example PreviewClip

		{
  "type": "preview_clip",
  "destination": "/mydirectory/preview1.mp4",
  "num_snippets": 5,
  "snippet_duration": 1,
  "video_codec": "h264"
}

1.1.3 Storyboard Job

Generates a storyboard by capturing screenshots from a video, creating an image story similar to the functionality seen on platforms like YouTube, where hovering over the player seekbar displays thumbnails of key moments in the video.

type : 'storyboard'

Required

destination_dir : string

Required

Sets the name of the output directory.

sprite_file : string

Required

Sets the name of the output sprite file. Must end in '.jpg'.

vtt_file : string

Required

Sets the name of the output VTT file. Must end in '.vtt'.

interval : number

Sets the interval in seconds between each screenshot. Default is 10.

sprite_columns : number

Sets the amount of columns in the sprite file. Default is 10.

transformations : array of transformations

Array of transformations to apply to the video before the job. See the transformations section for more details.

Example Storyboard

		{
  "type": "storyboard",
  "destination_dir": "/mydirectory/storyboard1/",
  "sprite_file": "storyboard.jpg",
  "vtt_file": "vtt.vtt",
  "interval": 10,
  "sprite_columns": 10
}

1.1.4 Screenshots Job

Enables the extraction of multiple screenshots from a video, allowing for easy creation of previews or thumbnails. This feature is valuable for platforms requiring visual representations of video content.

type : 'screenshots'

Required

quantity : number

Required

Number of desired screenshots.

destination : string

Required

Sets the name of the output file. The %d is a mandatory placeholder ONLY if the number of screenshots is higher than 1 for the screenshot number. Must end in '.jpg'.

transformations : array of transformations

Array of transformations to apply to the video before the job. See the transformations section for more details.

Multiple Screenshots Example

		{
  "type": "screenshots",
  "quantity": 5,
  "destination": "/mydirectory/original/test_%d.jpg"
}

Single Screenshots Example

		{
  "type": "screenshots",
  "quantity": 1,
  "destination": "/mydirectory/original/test.jpg"
}

1.1.5 Transformations Parameters

Each job can have its own transformation parameters applied before the job. Below are the parameters for each transformation type.

1.1.5.1 Resize Transformation

Allows for adjusting the dimensions of a video, either by specifying absolute pixel values or by using percentages of the source video's width or height. This transformation is useful for resizing videos to fit specific display requirements or aspect ratios. Does NOT crop or stretch the video.

type : 'resize'

Required

width : string | number

Required

Possible values:
Pixels: 100, "100" or "100px"
Percentage of the source video's width: "100%"
Percentage of the source video's height: "100h"

Note: If there are transformations then the "source" is considered to be the result of the last transformation before this step

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 source video's height: "100%"
Percentage of the source video's width: "100w"

Note: If there are transformations then the "source" is considered to be the result of the last transformation before this step

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

upscale : boolean

Whether to upscale the video if the dimensions are larger than the source video. Defaults to false.

Example Resize

		{
  "type": "resize",
  "width": 480,
  "height": 270
}

1.1.5.2 Trim Transformation

Enables precise cutting of video content by specifying the start time and duration of the desired segment. This transformation is valuable for removing unwanted sections from videos, creating clips, or focusing on specific segments of interest.

type : 'trim'

Required

start_time : number

The start time of the trimmed video in seconds. Must be a positive number. If not set, the video will start from the beginning.

duration : number

The duration of the trimmed video in seconds. Must be a positive number. If not set, the video will be trimmed to the end.

Example Trim

		{
  "type": "trim",
  "start_time": 20,
  "duration": 15
}

1.1.5.3 Crop Transformation

Allows for the removal of unwanted sections of a video by specifying the desired width and height of the cropped area. This transformation is useful for focusing on specific segments of interest or for adjusting the aspect ratio of a video.

type : 'crop'

Required

width : string | number

Required

Possible values:
Pixels: 100, "100" or "100px"
Percentage of the source video's width: "100%"
Percentage of the source video's height: "100h"

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

height : string | number

Required

gravity : string

Required

The gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'. Defaults to 'center'.

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 Crop

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

1.1.5.4 Watermark Transformation

Allows for the addition of a watermark to a video, providing a way to brand content or protect against unauthorized use. This transformation is valuable for platforms requiring visual representations of video content.

type : 'watermark'

Required

Source : string

Required

Sets the source of the watermark.

width : string | number

Required

height : string | number

Required

gravity : string

Required

Sets the gravity. Must be one of 'center', 'north', 'northeast', 'east', 'southeast', 'south', 'southwest', 'west', 'northwest'. Defaults to 'southeast'.

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.

opacity : number

Sets the opacity. Must be a number between 0 and 1. Defaults to 1.

Example Watermark

		{
  "type": "watermark",
  "source": "source/watermark.png",
  "width": 750,
  "height": 500,
  "gravity": "center"
}

Responses

🟢 OK

		{
  "process_id": "1mQhK6J7azYy9LKo7Rbxp",
  "status": 200,
  "description": "Request received"
}

🟠 Bad Request

		{
  "status": 400,
  "error": "Failed to validate fields",
  "details": [
    {
      "name": "jobs",
      "message": [
        "destination should not be null or undefined",
        "destination should not be empty",
        "destination must be a string"
      ]
    }
  ]
}

Callback/Webhook

When you set a callback URL, we will send a POST request to that URL when the process as failed or finished.

process_id

The unique ID of the process.

success

Indicates the success of the processing task (1 in this case, meaning success).

status

This field specifies the status of the request.

Information about the total cost of the process.

Information about the original video file that was processed.

finished_download_at

Timestamp of when the download finished.

Detailed information about the processed jobs.

Example Callback

		{
  "process_id": "joIYQ-odv3H36x9OlEg71",
  "success": 1,
  "status": "FINISHED",
  "cost": {
    "base_credits_per_second": 0.02,
    "total_multiplier": 1,
    "credits": 0.30466666,
    "billed_seconds": 15.233333,
    "encoded_seconds": 15.233333,
    "billed_credits_per_second": 0.02
  },
  "source": {
    "audio_codec": "AAC",
    "audio_duration": 15.231995,
    "bit_rate": 13706361,
    "extension": "mp4",
    "file_md5": "27b0bd69bea34855f1b7c88dedb37306",
    "file_name": "/slashed/sources/518101_0.mp4",
    "file_sha1": "0d907d30cf2743a8a83e93182bc386d3124c3de6",
    "file_size": 26099197,
    "fps": 30,
    "height": 1920,
    "is_portrait": true,
    "video_codec": "H264",
    "video_duration": 15.233333,
    "width": 1080
  },
  "jobs": [
    {
      "audio_codec": "AAC",
      "bit_rate": 7297674,
      "cost": {
        "base_credits_per_second": 0.02,
        "total_multiplier": 1,
        "credits": 0.30466666,
        "billed_seconds": 15.233333,
        "encoded_seconds": 15.233333,
        "multipliers": [
          29,
          19,
          17,
          22
        ],
        "billed_credits_per_second": 0.02
      },
      "created_at": "2024-04-01 16:27:48",
      "duration": 15.233333,
      "extension": "mp4",
      "file_md5": "17789285d47beea8976e065a3fbec3fe",
      "file_name": "/slashed/destinations/22032024/279546_src.mp4",
      "file_sha1": "9640095eb7a41b814a97bdef660a3ce5f4a91bf8",
      "file_size": 13895989,
      "finished_at": "2024-04-01 16:27:57",
      "finished_upload_at": "2024-04-01 16:27:59",
      "fps": 30,
      "height": 1920,
      "id": "1kUZHD7dwb2uqgwSNTlGd",
      "index": 0,
      "started_upload_at": "2024-04-01 16:27:57",
      "status": "FINISHED",
      "type": "ENCODE",
      "video_codec": "H264",
      "width": 1080
    }
  ]
}

2. Get Process Status

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

Responses

🟢 Success

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

🟡 Pending

		{
  "status": "'RECEIVED' | 'VALIDATING' | 'ENQUEUED' | 'PROCESSING'",
  "updated_at": "2024-01-01 08:00:00"
}

🟠 Failed

		{
  "status": "'REJECTED' | 'FAILED' | 'FAILED_BILLING' | 'PARTIALLY_FAILED'",
  "updated_at": "2024-01-01 08:00:00",
  "fail_message": "Invalid video format"
}

🔴 Error

		{
  "status": 404,
  "message": "Process not found",
  "description": "No process found with the provided id.",
  "error_code": "PROCESS_NOT_FOUND"
}

Detailed Process Status

GET https://venc.slashed.cloud/status/detailed/joIYQ-odv3H36x9OlEg71

process_id

The unique ID of the process.

success

Indicates the success of the processing task (1 in this case, meaning success).

status

This field specifies the status of the request.

Information about the total cost of the process.

Information about the original video file that was processed.

finished_download_at

Timestamp of when the download finished.

Detailed information about the processed jobs.

Example Response

		{
  "process_id": "joIYQ-odv3H36x9OlEg71",
  "success": 1,
  "status": "FINISHED",
  "cost": {
    "base_credits_per_second": 0.02,
    "total_multiplier": 1,
    "credits": 0.30466666,
    "billed_seconds": 15.233333,
    "encoded_seconds": 15.233333,
    "billed_credits_per_second": 0.02
  },
  "source": {
    "audio_codec": "AAC",
    "audio_duration": 15.231995,
    "bit_rate": 13706361,
    "extension": "mp4",
    "file_md5": "27b0bd69bea34855f1b7c88dedb37306",
    "file_name": "/slashed/sources/518101_0.mp4",
    "file_sha1": "0d907d30cf2743a8a83e93182bc386d3124c3de6",
    "file_size": 26099197,
    "fps": 30,
    "height": 1920,
    "is_portrait": true,
    "video_codec": "H264",
    "video_duration": 15.233333,
    "width": 1080
  },
  "jobs": [
    {
      "audio_codec": "AAC",
      "bit_rate": 7297674,
      "cost": {
        "base_credits_per_second": 0.02,
        "total_multiplier": 1,
        "credits": 0.30466666,
        "billed_seconds": 15.233333,
        "encoded_seconds": 15.233333,
        "multipliers": [
          29,
          19,
          17,
          22
        ],
        "billed_credits_per_second": 0.02
      },
      "created_at": "2024-04-01 16:27:48",
      "duration": 15.233333,
      "extension": "mp4",
      "file_md5": "17789285d47beea8976e065a3fbec3fe",
      "file_name": "/slashed/destinations/22032024/279546_src.mp4",
      "file_sha1": "9640095eb7a41b814a97bdef660a3ce5f4a91bf8",
      "file_size": 13895989,
      "finished_at": "2024-04-01 16:27:57",
      "finished_upload_at": "2024-04-01 16:27:59",
      "fps": 30,
      "height": 1920,
      "id": "1kUZHD7dwb2uqgwSNTlGd",
      "index": 0,
      "started_upload_at": "2024-04-01 16:27:57",
      "status": "FINISHED",
      "type": "ENCODE",
      "video_codec": "H264",
      "width": 1080
    }
  ]
}

3. Retry Processes

POST https://venc.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

🟢 OK

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

🟠 Not Found

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