Video status & details
api.video gives you ways of checking the video upload status and video details.
To check the video upload status or details of the encoding, you can either use webhooks or API polling by making a request to /videos/{videoId}/status
endpoint.
Listening to Webhooks for Video Status & Encoding
By subscribing to video.encoding.quality.completed
webhook, each time the video changes its upload status, the URL you've set, will receive a POST request with the following payload.
{
"type": "video.encoding.quality.completed",
"emittedAt": "2021-01-29T16:46:25.217+01:00",
"videoId": "viXXXXXXXX",
"encoding": "hls",
"quality": "720p"
}
You can subscribe to webhooks by making a request to the /webhooks endpoint.
Webhook payload details
Property | Type | Description |
---|---|---|
emittedAt | datetime | timestamp when the request was emitted from api.video |
videoId | string | The ID of the video that was encoded. |
encoding | string | The asset that the encoding was finished for. There are two types of assets that you will receive in the encoding: HLS , MP4 |
quality | string | The quality of the video was transcoded to the current encoding. The MP4 asset will only be transcoded once, hence you will receive a webhook only once for the MP4 asset with the final source quality. While the HLS asset webhook will be emitted multiple times with each quality (from the lowest 240p) to the highest of the source (up to 4k). For example, if you've uploaded a video where the source quality is 720p. You will receive 5 webhooks in total: - 1 webhook with 720p quality for the MP4 encoding. - 4 webhooks for 240p, 360p, 480p and 720p for the HLS encoding |
Retrieving The Video Status & Details
The other option at your disposal would be to poll the API for the video status and details. After creating the video object, and making a request to upload the video, you can start polling the /status
endpoint. You will get the video upload status, encoding, source video details, and more with the returned payload.
You can make a request to the /status
endpoint at any time even after the video was uploaded to get details like the video duration, file size, video size and etc.
The response from the /status
endpoint will be as follows:
{
"ingest": {
"status": "uploaded",
"filesize": 23037467,
"receivedBytes": []
},
"encoding": {
"playable": true,
"qualities": [
{
"type": "hls",
"quality": "240p",
"status": "waiting"
},
{
"type": "hls",
"quality": "360p",
"status": "encoding"
},
{
"type": "hls",
"quality": "480p",
"status": "encoding"
},
{
"type": "hls",
"quality": "720p",
"status": "waiting"
},
{
"type": "mp4",
"quality": "720p",
"status": "encoded"
}
],
"metadata": {
"width": 1280,
"height": 720,
"bitrate": 766,
"duration": 200,
"framerate": 24,
"samplerate": 44100,
"videoCodec": "h264",
"audioCodec": "aac",
"aspectRatio": "16:9"
}
}
}
ingest
The ingest property will reflect the status of the ingestion with the file size and if you are using progressive upload, then also the received bytes:
Reflects the current status of the video upload. The property can have the following values:status
uploading
last_chunck_uploaded
merging
uploaded
The size of the file you've uploaded in bytefilesize
receivedBytes
encoding
The encoding property will provide information about each asset and which quality was already encoded and can be delivered.
Will return a boolean that indicates if the video can already be delivered. The video will be playable as soon as the first asset is encoded.playable
An array of objects will provide the type of asset encoding, the different qualities encoded, and the status. The encoding will happen async. The following properties will be present in the object:qualities
- type : The type of the encoding, with possible values of
hls
ormp4
- quality : The quality of the encoded asset. Possible values:
240p
,360p
,480p
,720p
,1080p
,2160p
(4k) - status : The status of the current encoding. The status will reflect whether the video is enqueued, encoded, or failed. Possible values:
waiting
- enqueued for encoding.encoding
- the encoding is in progress.encoded
- the video has been encoded and is ready for delivery.failed
- the encoding for this particular quality has failed.
- type : The type of the encoding, with possible values of
metadata
Provides data on the source video
Usage
To install your selected client, do the following:
go get github.com/apivideo/api.video-go-client
Retrieve your API key
You'll need your API key to get started. You can sign up for one here: Get your api.video API key!. Then do the following:
Retrieve video upload status
To retrieve the status of a video you uploaded, use this code sample:
curl --request GET \
--url https://ws.api.video/videos/{video ID here}/status \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI3NDM2MjEuMDAxMTYzLCJuYmYiOjE2NDI3NDM2MjEuMDAxMTYzLCJleHAiOjE2NDI3NDcyMjEuMDAxMTYzLCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.c1rrzpPWno4spJvrlFdgvV7yqRk72lfjd9eXLlvbrCM06WCsJmC0ZJQsA8PcrjDvwNpgQiIwbYaIv7wg8_YvM1aUN4EmEF9JgInzVGQcu4Bluu5pb8P00nWaez4aR9AYkeaIwrsHdsR3kA_68Y7gy5uWzMElLREIT1z7TENW-8aOYv5rhxX502kDSbm8qZyL_2gaNi4WfyuF81Sq2siBlB2t2aGOwc7IB86kuyfWqmtzbwUvOgPcmaCKW9vapZO0WViJoT7pnKx5kIdggZNMH9wOELC_A5AujJBjvlNEmHAJ8xREUrgHTo87Oz920cNFOdj16Wx4OokbyNFJVL3mIA'