Adding a thumbnail for a broadcast

Written by

Yandex Cloud

Updated at March 6, 2025

To add a thumbnail for a broadcast:

Cloud Video interface

REST API

gRPC API

Open the Cloud Video home page.
Select a channel.
In the Broadcasts tab, in the row with the broadcast you need, click and select Edit.
If the broadcast already has a thumbnail, delete it. To do this, hover over the thumbnail preview and click .
Click Select file and select a new image for your thumbnail.

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

Getting started:
- Get the ID of the organization your Cloud Video channel is in.
- Get an IAM token 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 link to upload the image to your thumbnail:

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 the 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 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.

Add the new thumbnail to the selected broadcast:

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

Where:

<broadcast_ID>: Previously saved ID of the broadcast 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.UpdateStreamMetadata",
  "streamId": "vplsfj23t7tf********"
 },
 "response": {
  "@type": "type.googleapis.com/yandex.cloud.video.v1.Stream",
  "onDemand": {},
  "id": "vplsfj23t7tf********",
  "channelId": "vplcdyphvqik********",
  "lineId": "vplldrpqy42y********",
  "title": "my-new-stream",
  "thumbnailId": "vpltxnjvjyzy********",
  "status": "OFFLINE",
  "createdAt": "2024-11-03T16:55:32.976950Z",
  "updatedAt": "2024-11-03T17:21:31.672357Z"
 },
 "id": "vplpgadtyvhm********",
 "description": "Stream 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 is in.
- Get an IAM token 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 link to upload the image to your thumbnail:

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

Add the new thumbnail to the selected broadcast:

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

Where:

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

Result:

{
  "id": "vplpl2wqhe62********",
  "description": "Stream 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.UpdateStreamMetadata",
    "streamId": "vplsfj23t7tf********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.video.v1.Stream",
    "channelId": "vplcdyphvqik********",
    "createdAt": "2024-11-03T16:55:32.976950Z",
    "id": "vplsfj23t7tf********",
    "lineId": "vplldrpqy42y********",
    "onDemand": {},
    "status": "OFFLINE",
    "thumbnailId": "vpltxnjvjyzy********",
    "title": "my-new-stream",
    "updatedAt": "2024-11-03T17:29:26.986096Z"
  }
}

Adding a thumbnail for a broadcast

Was the article helpful?