Contact UsGet started

How to get started with the Yandex Cloud Video API

Written by
Improved by
Updated at May 5, 2025

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.

To get started with the Cloud Video API:

  1. Create a channel.
  2. Create a video.
  3. Add a thumbnail to your video.
  4. Get a link to the video player.

Getting started

  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 you are going to create a channel in.

To use the examples, install these utilities:

Set up a service account

To access your organization and work with the Cloud Video API, you will need a service account with the video.admin or video.editor role and an IAM token.

Create a service account

Create a service account you will use to authenticate in the Cloud Video API.

  1. In the management console, select the folder you are going to use to work with the Cloud Video API.

  2. From the list of services, select Identity and Access Management.

  3. Click Create service account.

  4. Enter a name for the service account, e.g., sa-video-api.

    Follow these naming requirements:

    • It must be from 2 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

  5. Click Create.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

Run the following command to create a service account:

yc iam service-account create --name sa-video-api

Where --name is the service account name in the following format:

  • It must be from 2 to 63 characters long.
  • It may contain lowercase Latin letters, numbers, and hyphens.
  • It must start with a letter and cannot end with a hyphen.

Result:

id: ajehr0to1g8b********
folder_id: b1gv87ssvu49********
created_at: "2024-03-04T09:03:11.665153755Z"
name: sa-video-api

Save the id of the service account: you will need it to assign a role.

To create a service account, use the create REST API method for the ServiceAccount resource or the ServiceAccountService/Create gRPC call.

Assign a role to the service account

Assign the service account the video.admin or video.editor role for the organization. To learn more, see Access management in Yandex Cloud Video.

To grant a service account permissions to access an organization, you need the organization-manager.admin role or higher.

  1. Log in to Yandex Cloud Organization using an administrator or organization owner account.
  2. In the left-hand panel, select Access bindings.
  3. In the Account type filter, select Service accounts.
  4. Click Assign bindings in the top-right corner of the page.
  5. In the window that opens, go to Service accounts and select the previously created service account from the list or use the search bar to locate it.
  6. Click Add role and select the video.admin or video.editor role.
  7. Click Save.

Run this command:

yc organization-manager organization add-access-binding \
  --id <organization_ID> \
  --role <role> \
  --service-account-id <service_account_ID>

Where --role is video.admin or video.editor.

To assign a service account a role for an organization, use the updateAccessBindings REST API method for the Organization resource or the OrganizationService/UpdateAccessBindings gRPC API call.

Get an IAM token

To get an IAM token for a previously created service account, see Getting an IAM token for a service account.

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 into it via the tus protocol. If the upload fails, resume it from the same position in the file it was interrupted at.

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 was interrupted in the event of connection failure. You can code the upload yourself in your preferred programming language or use ready-made libraries for the same 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.

Make sure the video file has been uploaded

Make sure the video file has been 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. Proceed to add a thumbnail for the video.

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

Resume the interrupted upload

To resume an 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 to your video

To add a thumbnail to your Cloud Video video using the API, register the thumbnail on the channel, get an upload link, upload an image file using that link, and add the new 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 thumbnail upload link, 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 an 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 ~.

Add the thumbnail to your video

To add the new 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