VideoHost API — Документация

Базовый URL

text

https://api.videohost.example.com/v2

Аутентификация #

Каждый запрос должен содержать заголовок Authorization с Bearer-токеном. Получите токен в панели разработчика.

http

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Список видео #

Возвращает постраничный список видео, принадлежащих аутентифицированному пользователю.

GET /videos Список видео

Query-параметры

Параметр	Тип	Описание
page	integer	Номер страницы. По умолчанию `1`.
limit	integer	Элементов на странице. От `1` до `100`. По умолчанию `20`.
status	string	Фильтр по статусу: `ready`, `processing`, `failed`.
sort	string	Сортировка: `created_at`, `-created_at`, `views`, `-views`.

Пример запроса

bash

curl -X GET 'https://api.videohost.example.com/v2/videos?page=1&limit=2&status=ready' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ · 200 OK

json

{
  "data": [
    {
      "id": "vid_8aF2kL9mQx",
      "title": "Введение в WebRTC",
      "description": "Обзор протоколов и практический пример",
      "status": "ready",
      "duration": 843,
      "size_bytes": 184320000,
      "resolution": "1920x1080",
      "thumbnail_url": "https://cdn.videohost.example.com/thumbs/vid_8aF2kL9mQx.jpg",
      "playback_url": "https://cdn.videohost.example.com/hls/vid_8aF2kL9mQx/master.m3u8",
      "views": 12483,
      "likes": 942,
      "tags": ["webrtc", "streaming", "tutorial"],
      "created_at": "2025-03-14T09:21:43Z",
      "updated_at": "2025-03-14T10:02:11Z"
    },
    {
      "id": "vid_2pR7tY4nBv",
      "title": "Обзор Docker Compose",
      "description": "Мультиконтейнерные приложения за 20 минут",
      "status": "ready",
      "duration": 1204,
      "size_bytes": 245760000,
      "resolution": "1280x720",
      "thumbnail_url": "https://cdn.videohost.example.com/thumbs/vid_2pR7tY4nBv.jpg",
      "playback_url": "https://cdn.videohost.example.com/hls/vid_2pR7tY4nBv/master.m3u8",
      "views": 8341,
      "likes": 512,
      "tags": ["docker", "devops"],
      "created_at": "2025-02-28T17:44:12Z",
      "updated_at": "2025-03-01T08:11:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 47,
    "total_pages": 24
  }
}

Получить видео #

Возвращает полную информацию о конкретном видео по его идентификатору.

GET /videos/:id Одно видео

Пример запроса

bash

curl -X GET 'https://api.videohost.example.com/v2/videos/vid_8aF2kL9mQx' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ · 200 OK

json

{
  "id": "vid_8aF2kL9mQx",
  "title": "Введение в WebRTC",
  "description": "Обзор протоколов и практический пример",
  "status": "ready",
  "duration": 843,
  "size_bytes": 184320000,
  "resolution": "1920x1080",
  "fps": 30,
  "codec": "h264",
  "thumbnail_url": "https://cdn.videohost.example.com/thumbs/vid_8aF2kL9mQx.jpg",
  "playback_url": "https://cdn.videohost.example.com/hls/vid_8aF2kL9mQx/master.m3u8",
  "download_url": "https://cdn.videohost.example.com/dl/vid_8aF2kL9mQx.mp4",
  "views": 12483,
  "likes": 942,
  "dislikes": 17,
  "tags": ["webrtc", "streaming", "tutorial"],
  "owner": {
    "id": "usr_7Hn3kPq",
    "username": "dev_anna"
  },
  "created_at": "2025-03-14T09:21:43Z",
  "updated_at": "2025-03-14T10:02:11Z"
}

Загрузить видео #

Создаёт новое видео. Можно передать файл напрямую или указать URL для серверной загрузки.

POST /videos Создание видео

Параметры тела запроса

Поле	Тип	Описание
title	string required	Название видео, до 200 символов.
description	string optional	Описание, до 5000 символов.
source_url	string optional	URL исходного файла для серверной загрузки.
visibility	string optional	`public` (по умолчанию), `unlisted`, `private`.
tags	array<string> optional	До 15 тегов.

Пример запроса

bash

curl -X POST 'https://api.videohost.example.com/v2/videos' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Продвинутый TypeScript",
    "description": "Дженерики, условные типы и infer",
    "source_url": "https://storage.example.com/ts-advanced.mp4",
    "visibility": "public",
    "tags": ["typescript", "types"]
  }'

Ответ · 201 Created

json

{
  "id": "vid_5kLm9QwErT",
  "title": "Продвинутый TypeScript",
  "description": "Дженерики, условные типы и infer",
  "status": "processing",
  "visibility": "public",
  "tags": ["typescript", "types"],
  "progress": 0,
  "created_at": "2025-04-02T12:00:00Z"
}

Ошибка · 422 Unprocessable Entity

json

{
  "error": {
    "code": "validation_error",
    "message": "Не удалось проверить входные данные",
    "details": [
      {
        "field": "title",
        "issue": "Поле обязательно для заполнения"
      }
    ]
  }
}

Обновить видео #

Обновляет метаданные существующего видео. Изменение самого файла не поддерживается.

PUT /videos/:id Обновление

Пример запроса

bash

curl -X PUT 'https://api.videohost.example.com/v2/videos/vid_8aF2kL9mQx' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Введение в WebRTC (обновлено)",
    "visibility": "unlisted"
  }'

Ответ · 200 OK

json

{
  "id": "vid_8aF2kL9mQx",
  "title": "Введение в WebRTC (обновлено)",
  "description": "Обзор протоколов и практический пример",
  "status": "ready",
  "visibility": "unlisted",
  "updated_at": "2025-04-02T12:15:33Z"
}

Удалить видео #

Безвозвратно удаляет видео и все связанные файлы (thumbnail, HLS-сегменты, оригинал).

DELETE /videos/:id Удаление

Пример запроса

bash

curl -X DELETE 'https://api.videohost.example.com/v2/videos/vid_8aF2kL9mQx' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ · 204 No Content

http

HTTP/1.1 204 No Content
(пустое тело ответа)

Статистика видео #

Аналитика просмотров, удержания и вовлечённости за указанный период.

GET /videos/:id/stats Метрики

Query-параметры

Параметр	Тип	Описание
period	string	`24h`, `7d`, `30d`, `all`. По умолчанию `7d`.
granularity	string	`hour`, `day`. По умолчанию `day`.

Ответ · 200 OK

json

{
  "video_id": "vid_8aF2kL9mQx",
  "period": "7d",
  "totals": {
    "views": 2831,
    "unique_viewers": 2104,
    "watch_time_seconds": 189432,
    "avg_watch_duration": 66.9,
    "completion_rate": 0.42,
    "likes": 128,
    "comments": 37,
    "shares": 19
  },
  "series": [
    { "date": "2025-03-26", "views": 401, "watch_time_seconds": 27102 },
    { "date": "2025-03-27", "views": 388, "watch_time_seconds": 25844 },
    { "date": "2025-03-28", "views": 512, "watch_time_seconds": 34921 },
    { "date": "2025-03-29", "views": 336, "watch_time_seconds": 22110 },
    { "date": "2025-03-30", "views": 421, "watch_time_seconds": 28701 },
    { "date": "2025-03-31", "views": 398, "watch_time_seconds": 26433 },
    { "date": "2025-04-01", "views": 375, "watch_time_seconds": 24321 }
  ],
  "top_countries": [
    { "code": "RU", "views": 1204 },
    { "code": "KZ", "views": 512 },
    { "code": "BY", "views": 318 }
  ]
}

Комментарии #

Список комментариев к видео с поддержкой постраничной навигации и сортировки.

GET /videos/:id/comments Комментарии

Пример запроса

bash

curl -X GET 'https://api.videohost.example.com/v2/videos/vid_8aF2kL9mQx/comments?sort=-created_at&limit=2' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ · 200 OK

json

{
  "data": [
    {
      "id": "cmt_9xZk2pLq",
      "video_id": "vid_8aF2kL9mQx",
      "author": {
        "id": "usr_4Kp9Mx2",
        "username": "frontend_ninja",
        "avatar_url": "https://cdn.videohost.example.com/avatars/usr_4Kp9Mx2.jpg"
      },
      "text": "Отличное объяснение! Наконец-то понял, как работает ICE.",
      "likes": 24,
      "replies_count": 3,
      "created_at": "2025-04-01T15:22:10Z"
    },
    {
      "id": "cmt_3wYb7nHd",
      "video_id": "vid_8aF2kL9mQx",
      "author": {
        "id": "usr_8Qr2Vt5",
        "username": "dev_sergey",
        "avatar_url": "https://cdn.videohost.example.com/avatars/usr_8Qr2Vt5.jpg"
      },
      "text": "Было бы здорово увидеть продолжение про SFU и MCU.",
      "likes": 11,
      "replies_count": 0,
      "created_at": "2025-03-31T09:14:55Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 37,
    "total_pages": 19
  }
}

Коды ошибок #

Все ошибки возвращаются с единой структурой тела ответа.

200Успешный запрос
201Ресурс создан
204Успешно, без тела ответа
400Некорректный запрос
401Требуется аутентификация или токен недействителен
403Недостаточно прав
404Ресурс не найден
422Ошибка валидации полей
429Превышен лимит запросов
500Внутренняя ошибка сервера

Универсальный формат ошибки

json

{
  "error": {
    "code": "unauthorized",
    "message": "Токен отсутствует или недействителен",
    "request_id": "req_01HZ8K3M2N9P4Q7R",
    "documentation_url": "https://api.videohost.example.com/docs/errors#unauthorized"
  }
}