Create video
Use this method to create a new video entity.
Methods of creating
To upload the original video file to the server, there are several possible scenarios:
-
Copy from another server – If your video is accessable via “http://”, “https://”, or “sftp://” public link, then you can use this method to copy a file from an external server. Set
origin_urlparameter with the link to the original video file (i.e. “https://domain.com/video.mp4”). After method execution file will be uploaded and will be sent to transcoding automatically, you don’t have to do anything else. Use extra fieldorigin_http_headersif authorization is required on the external server. -
Direct upload from a local device – If you need to upload video directly from your local device or from a mobile app, then use this method. Keep
origin_urlempty and use TUS protocol (tus.io) to upload file. More details are here “Get TUS’ upload”
After getting the video, it is processed through the queue. There are 2 priority criteria: global and local. Global is determined automatically by the system as converters are ready to get next video, so your videos rarely queue longer than usual (when you don’t have a dedicated region). Local priority works at the level of your account and you have full control over it, look at “priority” attribute.
AI processing
When uploading a video, it is possible to automatically create subtitles based on AI.
Read more:
- What is “AI Speech Recognition”.
- If the option is enabled via
auto_transcribe_audio_language: auto|<language_code>, then immediately after successful transcoding, an AI task will be automatically created for transcription. - If you need to translate subtitles from original language to any other, then AI-task of subtitles translation can be applied. Use
auto_translate_subtitles_language: default|<language_codes,>parameter for that. Also you can point several languages to translate to, then a separate subtitle will be generated for each specified language. - How to “add AI-generated subtitles to an exist video”.
The created AI-task(s) will be automatically executed, and result will also be automatically attached to this video as subtitle(s).
Please note that transcription is done automatically for all videos uploaded to our video hosting. If necessary, you can disable automatic creation of subtitles. If AI is disabled in your account, no AI functionality is called.
Advanced Features For details on the requirements for incoming original files, and output video parameters after transcoding, refer to the Knowledge Base documentation. By default video will be transcoded according to the original resolution, and a quality ladder suitable for your original video will be applied. There is no automatic upscaling; the maximum quality is taken from the original video. If you want to upload specific files not explicitly listed in requirements or wish to modify the standard quality ladder (i.e. decrease quality or add new non-standard qualities), then such customization is possible. Please reach out to us for assistance.
Additionally, check the Knowledge Base for any supplementary information you may need.
Authorizations
API key for authentication. Make sure to include the word apikey, followed by a single space and then your token.
Example: apikey 1234$abcdef
Body
{
"name": "IBC 2025 - International Broadcasting Convention",
"description": "We look forward to welcoming you at IBC2025, which will take place 12-15 September 2025.",
"origin_url": "https://www.googleapis.com/drive/v3/files/...?alt=media",
"origin_http_headers": "Authorization: Bearer ...",
"priority": 0,
"clip_start_seconds": 137,
"clip_duration_seconds": 60,
"directory_id": 800,
"projection": "regular",
"client_user_id": 10,
"stream_id": 1,
"poster": "data:image/jpeg;base64,/9j/4AA...qf/2Q==",
"screenshot_id": -1,
"auto_transcribe_audio_language": "auto"
}Response
Successful
Video ID
Title of the video.
Often used as a human-readable name of the video, but can contain any text you wish. The values are not unique and may be repeated. Examples:
- Educational training 2024-03-29
- Series X S3E14, The empire strikes back
- 480fd499-2de2-4988-bc1a-a4eebe9818ee
Additional text field for video description
Client ID
Size of original file
Original video duration in milliseconds
URL to an original file from which the information for transcoding was taken.
May contain a link for scenarios:
- If the video was downloaded from another origin
- If the video is a recording of a live stream
- Otherwise it is "null"
Copy from another server URL to an original file that was downloaded. Look at method "Copy from another server" in POST /videos. Recording of an original live stream
URL to the original non-transcoded stream recording with original quality, saved in MP4 format. File is created immediately after the completion of the stream recording. The stream from which the recording was made is reflected in "stream_id" field.
Can be used for internal operations when a recording needs to be received faster than the transcoded versions are ready. But this version is not intended for public distribution. Views and downloads occur in the usual way, like viewing an MP4 rendition.
The MP4 file becomes available for downloading when the video entity "status" changes from "new" to "pending". The file is stored for 7 days, after which it will be automatically deleted.
Format of URL is /videos/<cid>_<slug>/origin_<bitrate>_<height>.mp4
Where:
<bitrate>– Encoding bitrate in Kbps.<height>– Video height.
This is a premium feature, available only upon request through your manager or support team.
Video duration in milliseconds. May differ from "origin_video_duration" value if the video was uploaded with clipping through the parameters "clip_start_seconds" and "clip_duration_seconds"
A unique alphanumeric identifier used in public URLs to retrieve and view the video. It is unique for each video, generated randomly and set automatically by the system.
Format of usage in URL is .../videos/{client_id}_{slug}/...
Example:
- Player: /videos/
12345_neAq1bYZ2 - Manifest: /videos/
12345_neAq1bYZ2/master.m3u8 - Rendition: /videos/
12345_neAq1bYZ2/qid90v1_720.mp4
If the video was saved from a stream, then ID of that stream is saved here
If the video was saved from a stream, then start time of the stream recording is saved here. Format is date time in ISO 8601
Custom URL or iframe displayed in the link field when a user clicks on a sharing button in player. If empty, the link field and social network sharing is disabled
Poster is your own static image which can be displayed before the video begins playing. This is often a frame of the video or a custom title screen.
Field contains a link to your own uploaded image.
Also look at "screenshot" attribute.
Field contains a link to minimized poster image. Original "poster" image is proportionally scaled to a size of 200 pixels in height.
A URL to the default screenshot is here. The image is selected from an array of all screenshots based on the “screenshot_id” attribute. If you use your own "poster", the link to it will be here too.
Our video player uses this field to display the static image before the video starts playing. As soon as the user hits "play" the image will go away. If you use your own external video player, then you can use the value of this field to set the poster/thumbnail in your player.
Example:
video_js.poster:api.screenshot- clappr.poster:
api.screenshot
Array of auto generated screenshots from the video. By default 5 static screenshots are taken from different places in the video. If the video is short, there may be fewer screenshots.
Screenshots are created automatically, so they may contain not very good frames from the video. To use your own image look at "poster" attribute.
ID of auto generated screenshots to be used for default screenshot.
Counting from 0. A value of -1 sets the "screenshot" attribute to the URL of your own image from the "poster" attribute.
Link to picture with video storyboard. Image in JPG format. The picture is a set of rectangles with frames from the video. Typically storyboard is used to show preview images when hovering the video's timeline.
Storyboard in VTT format. This format implies an explicit indication of the timing and frame area from a large sprite image.
ID of ad that should be shown. If empty the default ad is show. If there is no default ad, no ad is shownю
A URL to a master playlist HLS (master.m3u8). Chunk type will be selected automatically:
-
TS if your video was encoded to H264 only.
-
CMAF if your video was encoded additionally to H265 and/or AV1 codecs (as Apple does not support these codecs over MPEG TS, and they are not standardized in TS-container).
You can also manually specify suffix-options that will allow you to change the manifest to your request:
/videos/{client_id}_{video_slug}/master[-cmaf][-min-N][-max-N][-img][-(h264|hevc|av1)].m3u8List of suffix-options:
- [-cmaf] – getting HLS CMAF version of the manifest. Look at the
hls_cmaf_urlfield. - [-min-N] – ABR soft limitation of qualities from below.
- [-max-N] – ABR soft limitation of qualities from above.
- [-img] – Roku trick play: to add tiles directly into .m3u8 manifest. Read the Product Documentation for details.
- [-(h264|hevc|av1) – Video codec soft limitation. Applicable if the video was transcoded into multiple codecs H264, H265 and AV1 at once, but you want to return just 1 video codec in a manifest. Read the Product Documentation for details.
ABR soft-limiting: Soft limitation of the list of qualities allows you to return not the entire list of transcoded qualities for a video, but only those you need. For example, the video is available in 7 qualities from 360p to 4K, but you want to return not more than 480p only due to the conditions of distribution of content to a specific end-user (i.e. free account): ABR soft-limiting examples:
- To a generic
.../master.m3u8manifest - Add a suffix-option to limit quality
.../master-max-480.m3u8 - Add a suffix-option to limit quality and codec
.../master-min-320-max-320-h264.m3u8For more details look at the Product Documentation.
Caution. Solely master.m3u8 (and master[-options].m3u8) is officially documented and intended for your use. Any additional internal manifests, sub-manifests, parameters, chunk names, file extensions, and related components are internal infrastructure entities. These may undergo modifications without prior notice, in any manner or form. It is strongly advised not to store them in your database or cache them on your end.
A URL to a master playlist HLS (master-cmaf.m3u8) with CMAF-based chunks. Chunks are in fMP4 container. It's a code-agnostic container, which allows to use any like H264, H265, AV1, etc.
It is possible to use the same suffix-options as described in the "hls_url" attribute.
Caution. Solely master.m3u8 (and master[-options].m3u8) is officially documented and intended for your use. Any additional internal manifests, sub-manifests, parameters, chunk names, file extensions, and related components are internal infrastructure entities. These may undergo modifications without prior notice, in any manner or form. It is strongly advised not to store them in your database or cache them on your end.
A URL to a master playlist MPEG-DASH (master.mpd) with CMAF or WebM based chunks.
Chunk type will be selected automatically for each quality:
-
CMAF for H264 and H265 codecs.
-
WebM for AV1 codec.
This URL is a link to the main manifest. But you can also manually specify suffix-options that will allow you to change the manifest to your request:
/videos/{client_id}_{slug}/master[-min-N][-max-N][-(h264|hevc|av1)].mpdList of suffix-options:
- [-min-N] – ABR soft limitation of qualities from below.
- [-max-N] – ABR soft limitation of qualities from above.
- [-(h264|hevc|av1) – Video codec soft limitation. Applicable if the video was transcoded into multiple codecs H264, H265 and AV1 at once, but you want to return just 1 video codec in a manifest. Read the Product Documentation for details.
Read more what is ABR soft-limiting in the "hls_url" field above.
Caution. Solely master.mpd is officially documented and intended for your use. Any additional internal manifests, sub-manifests, parameters, chunk names, file extensions, and related components are internal infrastructure entities. These may undergo modifications without prior notice, in any manner or form. It is strongly advised not to store them in your database or cache them on your end.
A URL to a built-in HTML video player with the video inside. It can be inserted into an iframe on your website and the video will automatically play in all browsers.
The player can be opened or shared via this direct link. Also the video player can be integrated into your web pages using the Iframe tag.
Example of usage on a web page:
There are some link modificators you can specify and add manually:
- ?
no_low_latency– player is forced to use non-low-latency streams HLS MPEG-TS, instead of MPEG-DASH CMAF or HLS/LL-HLS CMAF. - ?t=(integer) – time to start playback from specified point in the video. Applicable for VOD only.
- ?
sub_lang=(language) – force subtitles to specific language (2 letters ISO 639 code of a language). - Read more in the Product Documentation.
Custom URL of Iframe for video player to be used in share panel in player. Auto generated Iframe URL provided by default.
Number of video views through the built-in HTML video player of the Streaming Platform only. This attribute does not count views from other external players and native OS players, so here may be less number of views than in "cdn_views".
Total number of video views. It is calculated based on the analysis of all views, no matter in which player.
Custom meta field for storing the Identifier in your system. We do not use this field in any way when processing the stream. Example: client_user_id = 1001
Video processing status:
- empty – initial status, when video-entity is created, but video-file has not yet been fully uploaded (TUS uploading, or downloading from an origin is not finished yet)
- pending – video is in queue to be processed
- viewable – video has at least 1 quality and can already be viewed via a link, but not all qualities are ready yet
- ready – video is completely ready, available for viewing with all qualities
- error – error while processing a video, look at "error" field
empty, pending, viewable, ready, error Video processing error text will be saved here if "status: error"
Regulates the video format:
-
regular — plays the video as usual
-
vr360 — plays the video in 360 degree mode
-
vr180 — plays the video in 180 degree mode
-
vr360tb — plays the video in 3D 360 degree mode Top-Bottom.
Default is regular
Array of data about each transcoded quality