How to get started with the Yandex Cloud Video API

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 startedGetting 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:

• cURL (if using the REST API)
• cURL, gRPCurl and jq (if using the gRPC API)

Create a channelCreate 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>"
  }'

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

{
  "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 videoCreate 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 channelRegister 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:

   Linux/macOS

   Windows

   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:

   REST API

   gRPC API

   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 fileUpload 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 uploadedCheck 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>'

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

{
  "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 uploadResume 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 videoAdd 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 thumbnailRegister 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>"
  }'

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

{
  "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.

Get a link to upload the image to your thumbnailGet a link to upload the image to your thumbnail

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 thumbnailUpload 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 videoAssign 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>"
  }'

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

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

Get a link to the video playerGet a link to the video player

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.