Связаться с намиПодключиться

Как начать работать с API Yandex Cloud Video

Статья создана
Обновлена 18 ноября 2024 г.

В этом разделе вы научитесь создавать каналы, загружать видео и получать для загруженных видео ссылки на видеоплеер с помощью REST API и gPRC API Cloud Video.

Перед началом работы

Чтобы начать работать c API Cloud Video:

  1. В сервисе Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его.
  2. Получите идентификатор организации, в которой вы будете создавать канал.
  3. Назначьте пользователю или сервисному аккаунту, от имени которого вы будете аутентифицироваться в API Cloud Video, роль video.admin или video.editor. Подробнее см. в разделе Управление доступом в Yandex Cloud Video.
  4. Получите IAM-токен для пользователя или сервисного аккаунта, от имени которого вы будете аутентифицироваться в API Cloud Video.

Чтобы воспользоваться примерами, установите утилиты:

Создайте канал

Чтобы создать канал, выполните команду:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/channels' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization_id": "<идентификатор_организации>",
    "title": "<имя_канала>"
  }'

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_организации> — полученный перед началом работы идентификатор организации.
  • <имя_канала> — имя создаваемого канала в Cloud Video.

Результат:

{
 "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-токен>" \
  -d '{
    "organization_id": "<идентификатор_организации>",
    "title": "<имя_канала>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ChannelService/Create

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_организации> — полученный перед началом работы идентификатор организации.
  • <имя_канала> — имя создаваемого канала в Cloud Video.

Результат:

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

Сохраните идентификатор (значение channelId) созданного канала — он понадобится позднее.

Создайте видео

Чтобы создать видео в Cloud Video с помощью API, зарегистрируйте видео на канале и затем загрузите в него видеофайл по протоколу tus. В случае сбоя загрузки дозагрузите файл, продолжив загрузку с той позиции в файле, на которой произошел сбой.

Зарегистрируйте видео на канале

Чтобы зарегистрировать видео на канале:

  1. Узнайте точный размер видеофайла в байтах:

    В терминале выполните команду, указав путь к видеофайлу:

    ls -l /Users/myuser/Downloads/sample-video.MOV

    Результат:

    ...  100100627 ... /Users/myuser/Downloads/sample-video.MOV

    В powershell выполните команду, указав путь к видеофайлу:

    (Get-Item "C:\Users\myuser\Downloads\sample-video.MOV").Length

    Результат:

    100100627

  2. Выполните команду:

    curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channel_id": "<идентификатор_канала>",
    "title": "<имя_видео>",
    "tusd": {
      "file_size": <размер_видеофайла>,
      "file_name": "<имя_видеофайла>"
    },
    "public_access": {}
  }'

    Где:

    • <IAM-токен> — полученный перед началом работы IAM-токен.
    • <идентификатор_канала> — сохраненный на предыдущем шаге идентификатор созданного канала.
    • <имя_видео> — имя, которое будет присвоено видео при загрузке в канал.
    • <размер_видеофайла> — полученный ранее размер видеофайла в байтах.
    • <имя_видеофайла> — имя видеофайла, который вы будете загружать.

    Результат:

    {
 "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-токен>" \
  -d '{
    "channel_id": "<идентификатор_канала>",
    "title": "<имя_видео>",
    "tusd": {
      "file_size": <размер_видеофайла>,
      "file_name": "<имя_видеофайла>"
    },
    "public_access": {}
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/Create

    Где:

    • <IAM-токен> — полученный перед началом работы IAM-токен.
    • <идентификатор_канала> — сохраненный на предыдущем шаге идентификатор созданного канала.
    • <имя_видео> — имя, которое будет присвоено видео при загрузке в канал.
    • <размер_видеофайла> — полученный ранее размер видеофайла в байтах.
    • <имя_видеофайла> — имя видеофайла, который вы будете загружать.

    Результат:

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

    Сохраните ссылку на загрузку видео (значение поля url) и идентификатор видео (значение поля videoId) — они понадобятся позднее.

Загрузите видеофайл

Загрузка видеофайлов производится по протоколу tus, который в случае сбоя соединения позволяет возобновить загрузку с момента, на котором она была прервана. Загрузку вы можете реализовать самостоятельно на любом языке программирования или воспользоваться для этого готовыми библиотеками.

Чтобы загрузить видеофайл с помощью утилиты curl, выполните команду:

curl \
  --location \
  --request PATCH '<ссылка_на_загрузку_видео>' \
  --header 'Content-Type: application/offset+octet-stream' \
  --header 'Upload-Offset: 0' \
  --header 'Tus-Resumable: 1.0.0' \
  --data-binary '@<путь_к_видеофайлу>'

Где:

  • <ссылка_на_загрузку_видео> — сохраненная ранее ссылка на загрузку, полученная при создании видео.

  • <путь_к_видеофайлу> — полный путь к файлу с видео, предваряемый символом @.

    Например: @/Users/myuser/Downloads/sample-video.MOV.

    Не используйте в пути к файлу сокращения, в т.ч. тильду ~.

Убедитесь, что видеофайл загрузился

Убедитесь, что видеофайл был загружен полностью. Для этого выполните команду, указав сохраненный ранее идентификатор видео (videoId):

curl \
  --request GET \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<идентификатор_видео>' \
  --header 'Authorization: Bearer <IAM-токен>'

Результат:

{
 "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-токен>" \
  -d '{"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": {}
}

Если поле status имеет значение PROCESSING или READY, значит видеофайл загрузился полностью. Переходите к добавлению обложки видео.

Если поле status имеет значение WAIT_UPLOADING, значит загрузка видеофайла была прервана. В этом случае видео необходимо дозагрузить.

Продолжите прерванную загрузку

Чтобы дозагрузить видеофайл, необходимо знать позицию offset, на которой была прервана предыдущая попытка загрузки.

  1. Узнайте позицию offset прерванной загрузки, указав сохраненную ранее ссылку на загрузку видео:

    curl \
  --head '<ссылка_на_загрузку_видео>' \
  --header 'Host: tusd.video.cloud.yandex.net' \
  --header 'Tus-Resumable: 1.0.0'

    Результат:

    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

    Сохраните значение поля Upload-Offset — оно потребуется при дозагрузке видеофайла.

  2. Дозагрузите видеофайл, выполнив команду:

    curl \
  --location \
  --request PATCH '<ссылка_на_загрузку_видео>' \
  --header 'Content-Type: application/offset+octet-stream' \
  --header 'Upload-Offset: <значение_offset>' \
  --header 'Tus-Resumable: 1.0.0' \
  --data-binary '@<путь_к_видеофайлу>'

    Где:

    • <ссылка_на_загрузку_видео> — сохраненная ранее ссылка на загрузку, полученная при создании видео.

    • <значение_offset> — сохраненное ранее значение offset — позиции в файле, на которой прервалась предыдущая попытка загрузки.

    • <путь_к_видеофайлу> — полный путь к файлу с видео, предваряемый символом @.

      Например: @/Users/myuser/Downloads/sample-video.MOV.

      Не используйте в пути к файлу сокращения, в т.ч. тильду ~.

Повторно убедитесь, что видеофайл загрузился полностью. Если загрузка вновь была прервана, повторите действия, описанные в текущем подразделе.

Добавьте обложку к видео

Чтобы добавить обложку к видео в Cloud Video с помощью API, зарегистрируйте обложку на канале, получите ссылку на загрузку в нее вашего изображения, загрузите по этой ссылке файл с изображением и добавьте созданную обложку к вашему видео.

Зарегистрируйте обложку

Чтобы зарегистрировать обложку, выполните команду:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/thumbnails' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json' \
  --data '{
    "channelId": "<идентификатор_канала>"
  }'

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_канала> — сохраненный ранее идентификатор канала.

Результат:

{
 "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-токен>" \
  -rpc-header 'Content-Type: application/json' \
  -d '{
    "channel_id": "<идентификатор_канала>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ThumbnailService/Create

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_канала> — сохраненный ранее идентификатор канала.

Результат:

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

Сохраните значение идентификатора обложки (thumbnailId), оно понадобится позднее.

Чтобы получить ссылку на загрузку изображения обложки, выполните команду:

curl \
  --request POST \
  --url 'https://video.api.cloud.yandex.net/video/v1/thumbnails/<идентификатор_обложки>:generateUploadURL' \
  --header 'Authorization: Bearer <IAM-токен>'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
    "thumbnailId": "<идентификатор_обложки>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.ThumbnailService/GenerateUploadURL | jq

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_обложки> — сохраненное ранее значение идентификатора обложки.

Результат:

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

Поле uploadUrl содержит подписанную ссылку, с помощью которой вы сможете загрузить файл обложки.

Загрузите в обложку файл с изображением

Чтобы загрузить ваше изображение в обложку, выполните команду:

curl \
  --request PUT \
  --url '<подписанная_ссылка>' \
  --header 'Content-Type: image/<формат_изображения>' \
  --upload-file '<путь_к_файлу_с_обложкой>'

Где:

  • <подписанная_ссылка> — полученная на предыдущем шаге подписанная ссылка на загрузку файла обложки.
  • <формат_изображения> — в зависимости от формата загружаемого изображения, укажите png, jpeg или gif.
  • <путь_к_файлу_с_обложкой> — абсолютный путь к файлу с загружаемым изображением. Не используйте сокращения, в т.ч. тильду ~.

Добавьте обложку к видео

Чтобы добавить созданную обложку к вашему видео, выполните команду:

curl \
  --request PATCH \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<идентификатор_видео>' \
  --header 'Authorization: Bearer <IAM-токен>' \
  --header 'Content-Type: application/json' \
  --data '{
    "fieldMask": "thumbnailId",
    "thumbnailId": "<идентификатор_обложки>"
  }'

Где:

  • <идентификатор_видео> — сохраненный ранее идентификатор видео, для которого вы хотите добавить обложку.
  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_обложки> — сохраненный ранее идентификатор обложки.

Результат:

{
 "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-токен>" \
  -rpc-header "Content-Type: application/json" \
  -d '{
    "videoId": "<идентификатор_видео>",
    "fieldMask": {"paths": ["thumbnail_id"]},
    "thumbnailId": "<идентификатор_обложки>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/Update

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_видео> — сохраненный ранее идентификатор видео, для которого вы хотите добавить обложку.
  • <идентификатор_обложки> — сохраненный ранее идентификатор обложки.

Результат:

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

Чтобы получить ссылку на видеоплеер, выполните команду:

curl \
  --request GET \
  --header 'Authorization: Bearer <IAM-токен>' \
  --url 'https://video.api.cloud.yandex.net/video/v1/videos/<идентификатор_видео>:getPlayerURL'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d '{
    "videoId": "<идентификатор_видео>"
  }' \
  video.api.cloud.yandex.net:443 yandex.cloud.video.v1.VideoService/GetPlayerURL

Где:

  • <IAM-токен> — полученный перед началом работы IAM-токен.
  • <идентификатор_видео> — сохраненный ранее идентификатор видео, загруженного в канал.

Результат:

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

Где:

  • playerUrl — прямая ссылка на видео.
  • html — HTML-код для вставки видео в формате Iframe.
Предыдущая
Аутентификация в API
Следующая
Overview