Adding a thumbnail for a broadcast

Written by

Yandex Cloud

Updated at July 24, 2026

View in Markdown

To add a thumbnail for a broadcast:

Cloud Video UI

REST API

gRPC API

Open the Cloud Video home page.
Select a channel.
In the Broadcasts tab, select the broadcast you need.
Under Episodes, click and select Edit in the episode line.
If the episode 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.

Get a list of broadcasts on the channel:

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

Where:

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

Result:

{
 "streams": [
  {
   "onDemand": {},
   "id": "vplsfj23t7tf********",
   "channelId": "vplcdyphvqik********",
   "lineId": "vplldrpqy42y********",
   "title": "my-first-stream",
   "status": "OFFLINE",
   "createdAt": "2024-11-03T16:55:32.976950Z",
   "updatedAt": "2024-11-03T16:55:33.091744Z"
  },
  {
   "onDemand": {},
   "id": "vplsgchsr5gi********",
   "channelId": "vplcdyphvqik********",
   "lineId": "vpllxc2mfleb********",
   "title": "my-new-stream",
   "thumbnailId": "vpltznjxpnyj********",
   "status": "OFFLINE",
   "createdAt": "2024-11-03T16:34:10.617101Z",
   "updatedAt": "2024-11-03T16:35:06.601920Z"
  }
 ]
}

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

Get the list of broadcast episodes:

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

Where:

<broadcast_ID>: Previously saved broadcast ID.
<IAM_token>: IAM token you got before you started.

Result:

{
 "episodes": [
  {
   "id": "vpleof6lm40k********",
   "streamId": "vplsfj23t7tf********",
   "lineId": "vplldrpqy42y********",
   "title": "my-first-episode",
   "visibilityStatus": "PUBLISHED",
   "createdAt": "2024-11-03T16:55:32.976950Z",
   "updatedAt": "2024-11-03T16:55:33.091744Z"
  }
 ]
}

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

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

Where:

<IAM_token>: IAM token you got before you started.
episodeId: Previously saved episode 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********",
  "episodeId": "vpleof6lm40k********",
  "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 ~.

Add the thumbnail to your episode:

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

Where:

<episode_ID>: Previously saved episode ID 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.UpdateEpisodeMetadata",
  "episodeId": "vpleof6lm40k********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Episode",
  "id": "vpleof6lm40k********",
  "streamId": "vplsfj23t7tf********",
  "lineId": "vplldrpqy42y********",
  "title": "my-first-episode",
  "thumbnailId": "vpltxnjvjyzy********",
  "visibilityStatus": "PUBLISHED",
  "createdAt": "2024-11-03T16:55:32.976950Z",
  "updatedAt": "2024-11-03T17:21:31.672357Z"
 },
 "id": "vplpgadtyvhm********",
 "description": "Episode update",
 "createdAt": "2024-11-03T17:21:31.680037Z",
 "createdBy": "ajeol2afu1js********",
 "modifiedAt": "2024-11-03T17:21:31.680037Z"
}

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.

Get a list of broadcasts on the channel:

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

Where:

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

Result:

{
  "streams": [
    {
      "id": "vplsfj23t7tf********",
      "channelId": "vplcdyphvqik********",
      "lineId": "vplldrpqy42y********",
      "title": "my-first-stream",
      "status": "OFFLINE",
      "createdAt": "2024-11-03T16:55:32.976950Z",
      "updatedAt": "2024-11-03T16:55:33.091744Z",
      "onDemand": {}
    },
    {
      "id": "vplsgchsr5gi********",
      "channelId": "vplcdyphvqik********",
      "lineId": "vpllxc2mfleb********",
      "title": "my-new-stream",
      "thumbnailId": "vpltznjxpnyj********",
      "status": "OFFLINE",
      "createdAt": "2024-11-03T16:34:10.617101Z",
      "updatedAt": "2024-11-03T16:35:06.601920Z",
      "onDemand": {}
    }
  ]
}

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

Get the list of broadcast episodes:

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

Where:

<IAM_token>: IAM token you got before you started.
<broadcast_ID>: Previously saved broadcast ID.

Result:

{
  "episodes": [
    {
      "id": "vpleof6lm40k********",
      "streamId": "vplsfj23t7tf********",
      "lineId": "vplldrpqy42y********",
      "title": "my-first-episode",
      "visibilityStatus": "PUBLISHED",
      "createdAt": "2024-11-03T16:55:32.976950Z",
      "updatedAt": "2024-11-03T16:55:33.091744Z"
    }
  ]
}

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

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

Where:

<IAM_token>: IAM token you got before you started.
episode_id: Previously saved episode 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",
    "episodeId": "vpleof6lm40k********",
    "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 ~.

Add the thumbnail to your episode:

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

Where:

<IAM_token>: IAM token you got before you started.
<episode_ID>: Previously saved episode ID you want to add a thumbnail for.
<thumbnail_ID>: Previously saved thumbnail ID.

Result:

{
  "id": "vplpl2wqhe62********",
  "description": "Episode update",
  "createdAt": "2024-11-03T17:29:26.987297Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2024-11-03T17:29:26.987297Z",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.UpdateEpisodeMetadata",
    "episodeId": "vpleof6lm40k********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Episode",
    "createdAt": "2024-11-03T16:55:32.976950Z",
    "id": "vpleof6lm40k********",
    "lineId": "vplldrpqy42y********",
    "streamId": "vplsfj23t7tf********",
    "thumbnailId": "vpltxnjvjyzy********",
    "title": "my-first-episode",
    "updatedAt": "2024-11-03T17:29:26.986096Z",
    "visibilityStatus": "PUBLISHED"
  }
}

Adding a thumbnail for a broadcast

Was the article helpful?