You can use two methods to work with the ArvanCloud video platform: the ArvanCloud User Panel or the ArvanCloud API. Although the first method is more suited for end users, the features and accessibility of the ArvanCloud Video Hosting API offer a powerful tool for developers.
Throughout this technical guide, we will introduce you to the ArvanCloud video platform API and show you how to work with it. For more information about this tool, you can also refer to the ArvanCloud Video Hosting Platform API documentation.
Getting started with the API
To work with the ArvanCloud API, you are going to need an API key. You can easily get it via the ArvanCloud user panel. You may refer to the API key creation guide for instructions on creating an API key.
Upon creating the API key, you can use the Postman or Insomnia tools to test the ArvanCloud Video API. To do so, and once you get one of these two tools, you first need to import the Postman collection file into one of these two installed programs and after that enter the API key you received from the ArvanCloud user panel in the Edit Collection section, Variables tab.
The selected subdomain must be created using the post request to make the video hosting service available. Use the following command to do this.
POST /domain Parameters Subdomain required
The important thing is that this request can be performed only once, and you cannot change the selected domain.
View the Domain
If you want to view the assigned domain, you can use the following method.
GET /domain
Manage Channels
Before uploading audio and video files to ArvanCloud’s video hosting servers, you will have to create at least one channel. Any files that are used in ArvanCloud’s video platform, such as video files, audio files, watermarks and profiles, are stored in a channel.
Create a Channel
The following command can create a channel using the ArvanCloud API.
POST /channels Parameters Title (string) required Description (string) Secure_link_enabled (boolean) Secure_link_enabled (string) required if “secure_link_enabled” is true
Show All Channels
Using the API of ArvanCloud’s video hosting service, you can view the list of channels available in your user account. To do this, you can use the below method.
GET /channels
Update a Channel
If you want to update a channel like when you create it, you have to send the body part and specify the channel ID in the URL as well.
PATCH /channels/{channel_id}
View a Particular Channel
This route will allow you to view information about a particular channel.
GET /channels/{channel_id}
Delete a Channel
You can completely delete a channel using the following method.
DELETE /channels/{channel_id}
Keep in mind that any files stored in it, including all audio files, video files, watermarks, and created profiles, will be deleted after deleting a channel.
File Upload
The TUS protocol is one of the most important concepts you must be aware of before uploading the file. Using this open-source protocol, you can upload in a resumable way. You can find more detailed information about this protocol and how to work with it in the Guide to Resumable Uploading of Files with the TUS Protocol.
An empty storage must be created based on the size of the file displayed in the View File Information section before you start sending the file to the server. Suppose there is an mp4 file named video.mp4 with a size of 6.8 MB (or 6777592 bytes), first of all the file size will be copied from the Properties section.
POST /channels/{channel_id}/files
Headers
tus-resumable: 1.0.0
upload_length: 6777592
upload-metadata: filename dmlkZW8ubXA0,filetype dmlkZW8vbXA0
Next, the ID of the created location will be copied from the Response Header field and the file will be sent to the server through the PATH request (the file ID and channel will be inserted into the URL).
POST /channels/{channel_id}/videos
Parameters
Title (string) required
Description (string)
Video_url (should be a valid URL. Otherwise, this will be corrupted)
File_id (should be string and it will be required whenever video_url is not available) required
Convert_mode (could be auto or manual or profile)
Profile_id (required if convert mode has set to profile)
Parallel_convert (boolean) required
Thumbnail_time (numeric) required
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
Watermark_id
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
When the audio or video file is available with a URL, the URL of the file could be entered directly in video_url / audio_url with no need to follow the previous steps. In addition, when the bitrate and resolution values are fixed, it is better to use the profile so that when converting the file, only the profile_id is needed.
To add an image to the video, you must create a watermark first and enter its ID when sending the file. For simultaneous converting of files, parallel_convert value must be set to true. Under normal mode, all files are queued and converted one by one. By selecting parallel_convert, you can convert up to 3 files at the same time, but note that there will be a charge for converting each file simultaneously.
Conversion Status
Once the file has been submitted for conversion, there are steps you must take to make the file available. First of all, you should use GET Request to determine the status of the file. The status value in the response will indicate the current status.
GET/videos/{video_id}
All of the videos in a channel can be viewed using the following route.
GET/channels/{channel_id}/videos
You can also update the title and description with the following route.
PATCH/videos/{video_id}
Parameters
Title (string) required
Description (string)
Subtitles
You can upload multiple subtitles for a video. Adding subtitles has to be done with a POST request. At the moment, only SRT and VTT formats are allowed as subtitle files.
POST /videos/{video_id}/subtitles
Parameters
subtitle (file) required
lang (string) required
View All Subtitles of a Video
View the Subtitles of a Specific Video
GET/videos/{video_id}/subtitles
Delete Subtitles
DELETE/subtitles/{subtitle_id}
Adding Watermark
In each channel, you can store different images separately to be used as a watermark during the video file conversion. To choose the watermark, you need to simply select the image ID you want to use.
POST /channels/{channel_id}/watermarks
Parameters
title (string) required
description (string)
watermark (file) required
Update Watermark
You can easily update the watermark using the ID of each watermark.
POST / watermarks /{ watermark _id}
Parameters
title (string) required
description (string)
View All Watermarks of a Channel
GET/channels/{channel_id}/watermarks
View a Watermark
GET/watermarks/{watermark_id}
Managing Profiles
In order to avoid manually entering file conversion settings whenever you convert a video or audio file, you can create a profile which, when selected, performs file conversion according to the profile settings. One channel can have several profiles.
POST /channels/{channel_id}/profiles
Parameters
Title (string) required
Description (string)
convert_mode ("auto", “manual”) required
thumbnail_time (number)
watermark_id (string)
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
Update Profile
PATCH /profiles/{profile_id}
Parameters
Title (string) required
Description (string)
convert_mode ("auto", “manual”) required
thumbnail_time (number)
watermark_id (string)
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
View All Profiles of a Channel
GET/channels/{channel_id}/profiles
View a Profile
GET/profiles/{profile_id}
Delete a Profile
DELETE/profiles/{profile_id}