Dashboard

Video Encoding
Your First Video Encoding Request

For this tutorial we'll be using Postman. You'll also need a Venc Service already setup.
Don't have a Venc Service yet? Click Here!

There are a few requirements in order to make your first video encoding request, these are:

  1. Service ID: This can be found inside your service page on the SlashedCloud dashboard.
  2. Service Secret Key: This can be found inside your service page on the SlashedCloud dashboard.
  3. API Endpoint: https://venc.slashed.cloud
  4. Source: The path of your video source.
  5. Destination: The path of your video destination.
Service Details
Example of what you see in your service page.

What does a video encoding request look like?

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

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.

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

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

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.

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"
}

How to send a video encoding request?

Head over to Postman:

  1. Method: Set the Method to POST.
  2. API URL: Set the URL to https://venc.slashed.cloud
  3. Go to Body and select raw and JSON.
  4. Copy and paste the JSON request above into the body.
    Note: Please make sure you insert YOUR service ID, source and destination.
    5. venc Postman Request
  5. Go to Headers and add the following:
    Authorization: Bearer YourSecretKey
    Content-Type: application/json
    6. venc Headers
  6. Click Send and you should get a response back with the status of your request.