Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

How to get started with the Yandex Cloud Video API

Written by
Updated at December 4, 2024

In this section, you will learn how to create channels, upload videos, and get links to the video player for the uploaded videos using the Cloud Video REST API and gRPC API.

Getting started

To get started with the Cloud Video API:

  1. In Yandex Cloud Billing, make sure you have a billing account linked and its status is ACTIVE or TRIAL_ACTIVE. If you do not have a billing account yet, create one.
  2. Get the ID of the organization to create a channel in.
  3. Assign the video.admin or video.editor role to the user or service account you will use to authenticate with the Cloud Video API. For more information, see Access management in Yandex Cloud Video.
  4. Get an IAM token for the user or service account you will use to authenticate with the Cloud Video API.

To use the examples, install these utilities:

Create a channel

To create a channel, run this command:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/channels' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization_id": "<organization_ID>",
    "title": "<channel_name>"
  }'

Where:

  • <IAM_token>: IAM token you got before you started.
  • <organization_ID>: Organization ID you got before you started.
  • <channel_name>: Name of the channel you are creating in Cloud Video.

Result:

{
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateChannelMetadata",
  "channelId": "vplcdyphvqik********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Channel",
  "id": "vplcdyphvqik********",
  "organizationId": "bpfaidqca8vd********",
  "title": "my-very-first-channel",
  "createdAt": "2024-09-16T19:01:10.591128Z",
  "updatedAt": "2024-09-16T19:01:10.591128Z"
 },
 "id": "vplp4vofhojp********",
 "description": "Channel create",
 "createdAt": "2024-09-16T19:01:10.596734Z",
 "createdBy": "ajeol2afu1js********",
 "modifiedAt": "2024-09-16T19:01:10.596734Z"
}

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
    "organization_id": "<organization_ID>",
    "title": "<channel_name>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ChannelService/Create

Where:

  • <IAM_token>: IAM token you got before you started.
  • <organization_ID>: Organization ID you got before you started.
  • <channel_name>: Name of the channel you are creating in Cloud Video.

Result:

{
  "id": "vplpvkqo2uyv********",
  "description": "Channel create",
  "createdAt": "2024-09-16T10:36:56.973051Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2024-09-16T10:36:56.973051Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateChannelMetadata",
    "channelId": "vplcqy2qxkjy********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Channel",
    "createdAt": "2024-09-16T10:36:56.968240Z",
    "id": "vplcqy2qxkjy********",
    "organizationId": "bpfaidqca8vd********",
    "title": "my-very-first-channel",
    "updatedAt": "2024-09-16T10:36:56.968240Z"
  }
}

Save the new channel's ID (channelId value) as you will need it later.

Create a video

To create a Cloud Video video using the API, register the video on the channel and then upload the video file to it using the tus protocol. If the upload fails, resume it from the position in the file where the interruption occurred.

Register your video on the channel

To register a video on the channel, follow these steps:

  1. Get the exact size of the video file in bytes:

    In the terminal, run this command by specifying the video file path:

    ls -l /Users/myuser/Downloads/sample-video.MOV

    Result:

    ...  100100627 ... /Users/myuser/Downloads/sample-video.MOV

    In PowerShell, run this command by specifying the video file path:

    (Get-Item "C:\Users\myuser\Downloads\sample-video.MOV").Length

    Result:

    100100627

  2. Run this command:

    curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel_id": "<channel_ID>",
    "title": "<video_name>",
    "tusd": {
      "file_size": <video_file_size>,
      "file_name": "<video_file_name>"
    },
    "public_access": {}
  }'

    Where:

    • <IAM_token>: IAM token you got before you started.
    • <channel_ID>: New channel's ID saved in the previous step.
    • <video_name>: Name the video will get when uploaded to the channel.
    • <video_file_size>: Video file size you got earlier, in bytes.
    • <video_file_name>: Name of the video file you are going to upload.

    Result:

    {
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateVideoMetadata",
  "videoId": "vplvh4wvqimx********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Video",
  "tusd": {
   "url": "https://tusd.video.cloud.yandex.net/files/75925d89ddc05c0d5ca3282781f13c6f+00062241********"
  },
  "publicAccess": {},
  "id": "vplvh4wvqimx********",
  "channelId": "vplcdyphvqik********",
  "title": "my-very-first-video",
  "status": "WAIT_UPLOADING",
  "visibilityStatus": "PUBLISHED",
  "createdAt": "2024-09-16T19:18:08.384540Z",
  "updatedAt": "2024-09-16T19:18:08.384540Z"
 },
 "id": "vplpjlgda3c2********",
 "description": "Video create",
 "createdAt": "2024-09-16T19:18:08.393546Z",
 "createdBy": "ajeol2afu1js********",
 "modifiedAt": "2024-09-16T19:18:08.393546Z"
}

    grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
    "channel_id": "<channel_ID>",
    "title": "<video_name>",
    "tusd": {
      "file_size": <video_file_size>,
      "file_name": "<video_file_name>"
    },
    "public_access": {}
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/Create

    Where:

    • <IAM_token>: IAM token you got before you started.
    • <channel_ID>: New channel's ID saved in the previous step.
    • <video_name>: Name the video will get when uploaded to the channel.
    • <video_file_size>: Video file size you got earlier, in bytes.
    • <video_file_name>: Name of the video file you are going to upload.

    Result:

    {
  "id": "vplpskiedayr********",
  "description": "Video create",
  "createdAt": "2024-09-16T12:16:03.921095Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2024-09-16T12:16:03.921095Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateVideoMetadata",
    "videoId": "vplvio5377ux********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Video",
    "channelId": "vplcqy2qxkjy********",
    "createdAt": "2024-09-16T12:16:03.905662Z",
    "id": "vplvio5377ux********",
    "publicAccess": {},
    "status": "WAIT_UPLOADING",
    "title": "my-very-first-video",
    "tusd": {
      "url": "https://tusd.video.cloud.yandex.net/files/5e7d6b3b68f9dc0d279ce719144c9caa+0006223B********"
    },
    "updatedAt": "2024-09-16T12:16:03.905662Z",
    "visibilityStatus": "PUBLISHED"
  }
}

    Save the video upload link (url field value) and video ID (videoId field value) as you will need them later.

Upload a video file

Video file uploads use the tus protocol which allows resuming the upload from where it stopped in case of a connection failure. You can either code the upload yourself in any programming language or use ready-made libraries for this purpose.

To upload a video file using curl, run this command:

curl \
  --location \
  --request PATCH '<video_upload_link>' \
  --header 'Content-Type: application/offset+octet-stream' \
  --header 'Upload-Offset: 0' \
  --header 'Tus-Resumable: 1.0.0' \
  --data-binary '@<video_file_path>'

Where:

  • <video_upload_link>: Previously saved upload link you got when creating the video.

  • <video_file_path>: Full video file path preceded with @.

    E.g., @/Users/myuser/Downloads/sample-video.MOV.

    Do not use any shortcuts, including ~, in the file path.

Check that the video file was uploaded

Check that your video file was fully uploaded. To do this, run the following command by specifying the video ID (videoId) you saved earlier:

curl \
  --request GET \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<video_ID>' \
  --header 'Authorization: Bearer <IAM_token>'

Result:

{
 "tusd": {
  "url": "https://tusd.video.cloud.yandex.net/files/75925d89ddc05c0d5ca3282781f13c6f+00062241********"
 },
 "publicAccess": {},
 "id": "vplvh4wvqimx********",
 "channelId": "vplcdyphvqik********",
 "title": "my-very-first-video",
 "status": "READY",
 "duration": "39.981s",
 "visibilityStatus": "PUBLISHED",
 "createdAt": "2024-09-16T19:18:08.384540Z",
 "updatedAt": "2024-09-16T19:31:31.471857Z"
}

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{"video_id": "<video_ID>"}' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/Get

Result:

{
  "id": "vplva3626rvh********",
  "channelId": "vplcqy2qxkjy********",
  "title": "my-very-first-video",
  "status": "READY",
  "duration": "39.981s",
  "visibilityStatus": "PUBLISHED",
  "createdAt": "2024-09-16T14:11:04.803285Z",
  "updatedAt": "2024-09-16T14:14:36.467614Z",
  "tusd": {
    "url": "https://tusd.video.cloud.yandex.net/files/55994a57bd30b2161399ccab7eb5f2de+0006223D********"
  },
  "publicAccess": {}
}

If you see PROCESSING or READY in the status field, the video file was fully uploaded. Now it is time to add a video thumbnail.

If you see WAIT_UPLOADING in the status field, the video file upload was interrupted. In which case you need to complete the upload.

Resume the interrupted upload

To complete the upload, you need to know the offset position the previous upload attempt was interrupted at.

  1. Get the offset position of the interrupted upload using the previously saved video upload link:

    curl \
  --head '<video_upload_link>' \
  --header 'Host: tusd.video.cloud.yandex.net' \
  --header 'Tus-Resumable: 1.0.0'

    Result:

    HTTP/1.1 200 OK
Server: nginx/1.18.0
Date: Mon, 16 Sep 2024 15:21:52 GMT
Connection: keep-alive
Cache-Control: no-cache
Tus-Resumable: 1.0.0
Upload-Length: 100100627
Upload-Metadata: filename c2FtcGxlLXZpZGVv********,video_id dnBsdjVpeWh2M2F6ZnYz********
Upload-Offset: 28231123
X-Content-Type-Options: nosniff
X-Request-Id: 3b775c2a********
X-Trace-Id: 95ab2f994557ce1b1ee9dd09********
X_h: edge-5b647c8d67-*****
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Expose-Headers: *
Expires: Thu, 01 Jan 1970 00:00:01 GMT

    Save the Upload-Offset field value as you will need it to complete the video file upload.

  2. Complete the file upload by running this command:

    curl \
  --location \
  --request PATCH '<video_upload_link>' \
  --header 'Content-Type: application/offset+octet-stream' \
  --header 'Upload-Offset: <offset_value>' \
  --header 'Tus-Resumable: 1.0.0' \
  --data-binary '@<video_file_path>'

    Where:

    • <video_upload_link>: Previously saved upload link you got when creating the video.

    • <offset_value>: Previously saved offset value indicating the position in the file the previous upload attempt was interrupted at.

    • <video_file_path>: Full video file path preceded with @.

      E.g., @/Users/myuser/Downloads/sample-video.MOV.

      Do not use any shortcuts, including ~, in the file path.

Check once again that the video file has been fully uploaded. If the upload was interrupted again, repeat the steps described in this subsection.

Add a thumbnail for your video

To add a thumbnail to your Cloud Video video using the API, register the thumbnail on your channel, get a link to upload your image to that thumbnail, upload the image file using that link, and assign the created thumbnail to your video.

Register the thumbnail

To register a thumbnail, run this command:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/thumbnails' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channelId": "<channel_ID>"
  }'

Where:

  • <IAM_token>: IAM token you got before you started.
  • <channel_ID>: Previously saved channel ID.

Result:

{
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateThumbnailMetadata",
  "thumbnailId": "vpltaurfr4pr********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Thumbnail",
  "id": "vpltaurfr4pr********",
  "channelId": "vplcdyphvqik********",
  "createdAt": "2024-11-02T16:56:19.296797Z"
 },
 "id": "vplpgbyqopdr********",
 "description": "Thumbnail create",
 "createdAt": "2024-11-02T16:56:19.301776Z",
 "createdBy": "ajeol2afu1js********",
 "modifiedAt": "2024-11-02T16:56:19.301776Z"
}

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -rpc-header 'Content-Type: application/json' \
  -d '{
    "channel_id": "<channel_ID>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ThumbnailService/Create

Where:

  • <IAM_token>: IAM token you got before you started.
  • <channel_ID>: Previously saved channel ID.

Result:

{
  "id": "vplpoqhxep6q********",
  "description": "Thumbnail create",
  "createdAt": "2024-11-02T19:04:28.412672Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2024-11-02T19:04:28.412672Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.CreateThumbnailMetadata",
    "thumbnailId": "vpltleyrfnjh********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Thumbnail",
    "channelId": "vplcdyphvqik********",
    "createdAt": "2024-11-02T19:04:28.402787Z",
    "id": "vpltleyrfnjh********"
  }
}

Save the thumbnailId value: you will need it later.

To get a link to upload a thumbnail image, run this command:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/thumbnails/<thumbnail_ID>:generateUploadURL' \
  --header 'Authorization: Bearer <IAM_token>'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
    "thumbnailId": "<thumbnail_ID>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ThumbnailService/GenerateUploadURL | jq

Where:

  • <IAM_token>: IAM token you got before you started.
  • <thumbnail_ID>: Previously saved thumbnail ID.

Result:

{
  "uploadUrl": "https://storage.yandexcloud.net/videoplatform-thumbnail/vpltleyrfnjh********?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=********3aBOmv27nzbJZaEHZ%2F20241102%2Fru-central1%2Fs3%2Faws4_request&X-Amz-Date=20241102T190000Z&X-Amz-Expires=43200&X-Amz-Signature=057fe4c0da26c7758474f5eaa85ff41d7212632572fb636ed6d8f65d039c309b&X-Amz-SignedHeaders=host"
}

The uploadUrl field contains a signed link you can use to upload the thumbnail file.

Upload the image file to the thumbnail

To upload your image to the thumbnail, run this command:

curl \
  --request PUT \
  --url '<signed_link>' \
  --header 'Content-Type: image/<image_format>' \
  --upload-file '<path_to_thumbnail_file>'

Where:

  • <signed_link>: Signed thumbnail file upload link you got in the previous step.
  • <image_format>: Format of the image to upload, such as png, jpeg, or gif.
  • <path_to_thumbnail_file>: Absolute path to the image file to upload. Do not use any shortcuts, including ~.

Assign a thumbnail to your video

To assign the created thumbnail to your video, run this command:

curl \
  --request PATCH \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<video_ID>' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "fieldMask": "thumbnailId",
    "thumbnailId": "<thumbnail_ID>"
  }'

Where:

  • <video_ID>: Previously saved ID of the video you want to add a thumbnail for.
  • <IAM_token>: IAM token you got before you started.
  • <thumbnail_ID>: Previously saved thumbnail ID.

Result:

{
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.UpdateVideoMetadata",
  "videoId": "vplvh4wvqimx********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Video",
  "tusd": {
   "url": "https://tusd.video.cloud.yandex.net/files/75925d89ddc05c0d5ca3282781f13c6f+00062241********"
  },
  "publicAccess": {},
  "id": "vplvh4wvqimx********",
  "channelId": "vplcdyphvqik********",
  "title": "my-very-first-video",
  "thumbnailId": "vpltqm4nubzl********",
  "status": "READY",
  "duration": "39.981s",
  "visibilityStatus": "PUBLISHED",
  "createdAt": "2024-09-16T19:18:08.384540Z",
  "updatedAt": "2024-11-02T21:08:33.443368Z"
 },
 "id": "vplpriyo7eom********",
 "description": "Video update",
 "createdAt": "2024-11-02T21:08:33.461610Z",
 "createdBy": "ajeol2afu1js********",
 "modifiedAt": "2024-11-02T21:08:33.461610Z"
}

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -rpc-header "Content-Type: application/json" \
  -d '{
    "videoId": "<video_ID>",
    "fieldMask": {"paths": ["thumbnail_id"]},
    "thumbnailId": "<thumbnail_ID>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/Update

Where:

  • <IAM_token>: IAM token you got before you started.
  • <video_ID>: Previously saved ID of the video you want to add a thumbnail for.
  • <thumbnail_ID>: Previously saved thumbnail ID.

Result:

{
  "id": "vplp77twonao********",
  "description": "Video update",
  "createdAt": "2024-11-03T09:38:13.363079Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2024-11-03T09:38:13.363079Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.UpdateVideoMetadata",
    "videoId": "vplvh4wvqimx********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Video",
    "channelId": "vplcdyphvqik********",
    "createdAt": "2024-09-16T19:18:08.384540Z",
    "duration": "39.981s",
    "id": "vplvh4wvqimx********",
    "publicAccess": {},
    "status": "READY",
    "thumbnailId": "vpltqlukqfoc********",
    "title": "my-very-first-video",
    "tusd": {
      "url": "https://tusd.video.cloud.yandex.net/files/75925d89ddc05c0d5ca3282781f13c6f+00062241********"
    },
    "updatedAt": "2024-11-03T09:38:13.354454Z",
    "visibilityStatus": "PUBLISHED"
  }
}

To get a link to the video player, run this command:

curl \
  --request GET \
  --header 'Authorization: Bearer <IAM_token>' \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<video_ID>:getPlayerURL'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
    "videoId": "<video_ID>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/GetPlayerURL

Where:

  • <IAM_token>: IAM token you got before you started.
  • <video_ID>: Previously saved ID of the video uploaded to the channel.

Result:

{
  "playerUrl": "https://runtime.video.cloud.yandex.net/player/video/vplva3626rvh********?autoplay=0\u0026mute=0",
  "html": "\u003ciframe width=\"560\" height=\"315\" src=\"https://runtime.video.cloud.yandex.net/player/video/vplva3626rvh********?autoplay=0\u0026mute=0\" allow=\"autoplay; fullscreen; accelerometer; gyroscope; picture-in-picture; encrypted-media\" frameborder=\"0\" scrolling=\"no\"\u003e\u003c/iframe\u003e"
}

Where:

  • playerUrl: Direct link to the video.
  • html: HTML embed code in Iframe format.
Previous
Authentication with the API
Next
Overview