Adding a video thumbnail

Written by

Yandex Cloud

Updated at January 26, 2026

Cloud Video UI

REST API

gRPC API

Open the Cloud Video home page.
Select a channel.
In the Video tab, select a video.
If the video already has a thumbnail, delete it. To do this, hover over the thumbnail preview and click .
Click Select file and select a new thumbnail image.

The following cover formats are supported: JPG, PNG, and GIF.
Click Save.

Getting started:
- Get the ID of the organization your Cloud Video channel belongs to.
- Get an IAM token, which is required for authentication in the Cloud Video API.
- To use the examples, install cURL.

Get a list of Cloud Video channels in your organization:

curl \
  --request GET \
  --url 'https://video.api.cloud.yandex.net/video/v1/channels?organizationId=<organization_ID>' \
  --header 'Authorization: Bearer <IAM_token>'

Where:

<organization_ID>: Organization ID you got before you started.
<IAM_token>: IAM token you got before you started.

Result:

{
 "channels": [
  {
   "id": "vplc3neipzso********",
   "organizationId": "bpfaidqca8vd********",
   "title": "my-first-channel",
   "description": "My very first Cloud Video channel",
   "createdAt": "2023-07-07T10:51:48.658737Z",
   "updatedAt": "2023-07-07T10:51:48.658737Z"
  },
  {
   "id": "vplc3vssjcxh********",
   "organizationId": "bpfaidqca8vd********",
   "title": "my-work-channel",
   "createdAt": "2023-08-09T23:32:55.372456Z",
   "updatedAt": "2023-08-09T23:32:55.372456Z"
  },
  {
   "id": "vplc4cfwamlx********",
   "organizationId": "bpfaidqca8vd********",
   "title": "my-personal-channel",
   "createdAt": "2024-03-14T13:48:34.535821Z",
   "updatedAt": "2024-03-14T13:48:34.535821Z"
  },
 ]
}

Save the id of the channel to whose storage you want to upload the thumbnail.

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

Save the thumbnailId value: you will need it later.

Get a thumbnail upload link:

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

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:
```
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 ~.

Get a list of videos on the channel:

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

Where:

<channel_ID>: ID of the channel with the video you want to add a thumbnail for.
<IAM_token>: IAM token you got before you started.

Result:

{
 "videos": [
  {
   "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-11-03T12:53:07.769557Z"
  },
  {
   "tusd": {
    "url": "https://tusd.video.cloud.yandex.net/files/a95b9affc003bfb23708ca989e88f6b0+00062602********"
   },
   "id": "vplvm7wbmkon********",
   "channelId": "vplcdyphvqik********",
   "title": "my-second-video",
   "status": "PROCESSING",
   "visibilityStatus": "PUBLISHED",
   "createdAt": "2024-11-03T13:54:54.248715Z",
   "updatedAt": "2024-11-03T13:55:17.112515Z"
  }
 ]
}

Save the id of the video you want to add a thumbnail for.

Add a thumbnail to your video:

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

Getting started:
- Get the ID of the organization your Cloud Video channel belongs to.
- Get an IAM token, which is required for authentication in the Cloud Video API.
- To use the examples, install cURL, gRPCurl, and jq.

Get a list of Cloud Video channels in your organization:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
    "organizationId": "<organization_ID>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ChannelService/List

Where:

<IAM_token>: IAM token you got before you started.
<organization_ID>: Organization ID you got before you started.

Result:

{
  "channels": [
    {
      "id": "vplc3neipzso********",
      "organizationId": "bpfaidqca8vd********",
      "title": "my-first-channel",
      "description": "My very first Cloud Video channel",
      "createdAt": "2023-07-07T10:51:48.658737Z",
      "updatedAt": "2023-07-07T10:51:48.658737Z"
    },
    {
      "id": "vplc3vssjcxh********",
      "organizationId": "bpfaidqca8vd********",
      "title": "my-work-channel",
      "createdAt": "2023-08-09T23:32:55.372456Z",
      "updatedAt": "2023-08-09T23:32:55.372456Z"
    },
    {
      "id": "vplc4cfwamlx********",
      "organizationId": "bpfaidqca8vd********",
      "title": "my-personal-channel",
      "createdAt": "2024-03-14T13:48:34.535821Z",
      "updatedAt": "2024-03-14T13:48:34.535821Z"
    },
  ]
}

Save the id of the channel to whose storage you want to upload the thumbnail.

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.

Get a thumbnail upload link:

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:
```
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 ~.

Get a list of videos on the channel:

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

Where:

<IAM_token>: IAM token you got before you started.
<channel_ID>: ID of the channel with the video you want to add a thumbnail for.

Result:

{
  "videos": [
    {
      "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-11-03T12:53:07.769557Z",
      "tusd": {
        "url": "https://tusd.video.cloud.yandex.net/files/75925d89ddc05c0d5ca3282781f13c6f+00062241********"
      },
      "publicAccess": {}
    },
    {
      "id": "vplvm7wbmkon********",
      "channelId": "vplcdyphvqik********",
      "title": "my-second-video",
      "status": "PROCESSING",
      "visibilityStatus": "PUBLISHED",
      "createdAt": "2024-11-03T13:54:54.248715Z",
      "updatedAt": "2024-11-03T14:05:52.004442Z",
      "tusd": {
        "url": "https://tusd.video.cloud.yandex.net/files/a95b9affc003bfb23708ca989e88f6b0+00062602********"
      }
    }
  ]
}

Save the id of the video you want to add a thumbnail for.

Add a thumbnail to your video:

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

Adding a video thumbnail

Was the article helpful?