testube — справочник для фронтенда
Всё, что нужно, чтобы написать клиент: адреса, формы запросов и ответов, правила доступа и грабли, на которые здесь легко наступить.
- Базовый адрес:
http://localhost:8080(порт изAPP__SERVER__PORT). - Формат — JSON, кодировка UTF-8. Тела запросов требуют
Content-Type: application/json. - CORS открыт полностью, так что клиент можно поднимать на любом порту.
Аутентификация
JWT в заголовке: Authorization: Bearer <access_token>. Access-токен живёт
expires_in секунд (по умолчанию час), после чего меняется на новый через
/auth/refresh — заново спрашивать пароль не нужно.
| Метод | Путь | Тело | Ответ |
|---|---|---|---|
| POST | /auth/register | {username, email, password} | 201 TokenResponse |
| POST | /auth/login | {email, password} | 200 TokenResponse |
| POST | /auth/google | {id_token, username?} | 200 TokenResponse |
| POST | /auth/refresh | {refresh_token} | 200 TokenResponse |
| POST | /auth/logout | {refresh_token} | 204 |
| POST | /auth/logout-all | — (токен) | 204 |
| GET | /auth/me | — | 200 User |
Ещё несколько ручек работают кодом из письма — сброс пароля, подтверждение адреса, вход по коду, смена адреса. Общие правила и первые три — ниже, в «Кодах из писем»; смена адреса — в «Смене email», рядом с личными данными.
// TokenResponse
{
"access_token": "eyJhbGciOi...",
"refresh_token": "7TXspv4MCFitf_Z1MOvBNbF8xXlEsKE7UPJFKYkPaXs",
"token_type": "Bearer",
"expires_in": 3600,
"user": {
"id": "...",
"username": "neo",
"display_name": "Нео",
"email": "neo@example.com",
"email_verified": false,
"avatar_url": null,
"created_at": "2026-09-06T10:00:00Z"
}
}
Refresh-токен одноразовый. Каждый обмен выдаёт новую пару и гасит
предъявленный токен; храните только последний. Если предъявить уже
потраченный, вся цепочка обновлений этой сессии гасится целиком и приходит
401 — это защита от повторного использования украденного токена, а не
ошибка клиента. Практический вывод: не обновляйте токен из двух вкладок
одновременно, иначе вторая уронит сессию обеим. Живёт refresh-токен 30 суток
(JWT__REFRESH_TTL_SECS).
/auth/logout гасит одну сессию и не требует access-токена: выйти нужно
уметь и с протухшим. /auth/logout-all гасит все сессии пользователя.
Ограничения: username — 3–32 символа латиницы, цифр, _ и -;
пароль — 8–128 символов. Email приводится к нижнему регистру.
/auth/register принимает ещё три необязательных поля — first_name,
last_name, phone — с теми же правилами, что у PATCH /me/profile
(см. «Личные данные»); null и отсутствие поля значат «не указано».
В TokenResponse их нет: читать их — GET /me/profile.
username — это ещё и адрес канала (@username в ссылке), а display_name —
показываемое имя: его правят через PATCH /me/channel, и ссылки при этом
не ломаются.
/auth/login не уточняет, что именно неверно — email или пароль:
иначе эндпоинт превращается в оракул для перебора зарегистрированных адресов.
Показывайте пользователю общее «неверный email или пароль».
email_verified в User — подтверждён ли адрес кодом из письма (см.
«Подтверждение адреса»). У аккаунтов, заведённых до появления кодов, он
false. Подтверждением считается и любой другой верно введённый код,
пришедший на этот адрес: сброса пароля или входа по коду.
Коды из писем
Сброс пароля, подтверждение адреса, вход по коду и смена адреса устроены одинаково: API шлёт на почту пятизначный код, клиент возвращает его в следующем запросе. Общие правила:
- код — ровно 5 цифр, ведущие нули значимы (
"04217"), передаётся строкой; - живёт 10 минут;
- новый код можно запросить не раньше чем через 72 секунды после прошлого
письма (обратный отсчёт «Kodni qayta olish mumkin: 01:12» в макете).
Раньше —
429сRetry-Afterи тем же числом секунд в теле:{"error": "...", "retry_after": 58}. Тело сretry_afterу любого429, в том числе от общего лимита частоты; - новый код заменяет прежний: старый с этого момента не подходит;
- код одноразовый, а пять неверных попыток сжигают его: после этого не подходит и верный, нужен новый;
- неверный, просроченный и сожжённый код дают один и тот же ответ — различать их клиенту незачем, нужен новый код;
- все ручки
/auth/*из этого раздела под строгим лимитом/auth/*(см. «Ограничение частоты»).
Почта может быть выключена. Если на сервере не настроена отправка
писем (MAIL__TRANSPORT=none, так по умолчанию), каждая ручка, которая
шлёт код, отвечает 503 с текстом в error: код не придёт, ждать его
незачем. Показывайте этот текст и предлагайте вход по паролю. Ручки,
которые код только проверяют, работают как обычно.
Телефона и SMS нет: коды приходят только на почту. Вкладка «Telefon raqam» на экранах сброса и входа по коду пока ничего не отправляет.
Восстановление пароля
Три шага, экраны «Parolni tiklash» → «Kodni kiriting» → «Yangi parol yarating».
POST /auth/password-reset
{"email": "aziz@example.com"}
-> 202 (тело пустое)
POST /auth/password-reset/verify
{"email": "aziz@example.com", "code": "04217"}
-> 200 {"reset_token": "...", "expires_in": 600}
-> 400 {"error": "..."} неверный, просроченный или сожжённый код
POST /auth/password-reset/confirm
{"reset_token": "...", "password": "новый пароль"}
-> 200 TokenResponse
-> 400 {"error": "..."} короткий пароль или негодный reset_token
POST /auth/password-resetотвечает202одинаково, есть такой аккаунт или нет, и пауза в 72 секунды ставится на сам адрес в обоих случаях: по ответу нельзя узнать, зарегистрирован ли адрес. Письмо уходит только зарегистрированному. Негодный по форме адрес —400.verifyдля незнакомого адреса отвечает так же, как на неверный код.reset_tokenодноразовый и живётexpires_inсекунд (10 минут); новыйverifyзаменяет прежний токен.confirmприменяет правила регистрации (пароль 8–128 символов). Короткий пароль —400, иreset_tokenпри этом не тратится: можно исправить и отправить снова.confirmгасит все прежние сессии пользователя, как/auth/logout-all: раз пароль сбрасывают, одна из них может быть чужой. Взамен приходит новая пара токенов, как после входа, — пользователь сразу внутри.
Подтверждение адреса
POST /auth/email/verify/request (токен)
-> 202 (тело пустое)
-> 409 {"error": "..."} адрес уже подтверждён
POST /auth/email/verify (токен)
{"code": "04217"}
-> 200 User (с "email_verified": true)
-> 400 {"error": "..."} неверный, просроченный или сожжённый код
POST /auth/registerсам отправляет первый код (если почта включена), так что с формы регистрации можно сразу переходить на экран «Kodni kiriting». Пауза в 72 секунды при этом уже идёт:verify/requestсразу после регистрации ответит429.- Без почты (
MAIL__TRANSPORT=none) регистрация проходит как обычно, ничего не отправляет,email_verifiedостаётсяfalse, аverify/requestотвечает503. - Код привязан к адресу, на который ушёл: если адрес успели сменить, код
для прежнего не подходит (
400).
Что значит неподтверждённый адрес — решение продукта, пока такое:
- неподтверждённый аккаунт ничем не ограничен: загрузка, комментарии,
подписки и всё остальное работают так же, как у подтверждённого.
email_verified— только сведение для клиента (например, плашка «подтвердите почту»); - неподтверждённый адрес нельзя занять второй регистрацией: она
по-прежнему получает
409, сколько бы времени ни прошло.
Оба пункта можно пересмотреть; когда это случится, об изменении будет сказано здесь.
Вход по коду
Экран «OTP orqali kirish», затем «Kodni kiriting».
POST /auth/otp/request
{"email": "aziz@example.com"}
-> 202 (тело пустое)
POST /auth/otp/verify
{"email": "aziz@example.com", "code": "04217"}
-> 200 TokenResponse
-> 401 {"error": "..."} неверный, просроченный или сожжённый код
- Только для существующих аккаунтов: регистрация по-прежнему
POST /auth/register, ей нужен постоянныйusername. requestотвечает202одинаково для зарегистрированного и незнакомого адреса, с одной и той же паузой; письмо уходит только зарегистрированному. Негодный по форме адрес —400.verifyдля незнакомого адреса отвечает тем же401, что и на неверный код, — как/auth/login.- Успешный
verify— это вход: новая сессия (своя цепочка refresh-токенов, ровно как после/auth/login), иemail_verifiedстановитсяtrue. - Телефона нет: вкладка «Telefon raqam» пока ничего не отправляет.
Вход через Google
Клиент получает ID-токен Google сам (в браузере через Google Identity Services, с тем же client id, что настроен на сервере) и меняет его на нашу пару токенов:
POST /auth/google
{"id_token": "eyJ...", "username": "aziz"}
API проверяет подпись токена ключами Google, iss
(accounts.google.com), aud (наш client id), срок действия и
email_verified: true. Затем ищет аккаунт:
- уже привязанный к этому аккаунту Google (по его постоянному
sub); - иначе с тем же email (без учёта регистра), но только если у аккаунта
email_verified: true: такой аккаунт привязывается к Google, его пароль продолжает работать. Если адрес у аккаунта не подтверждён, приходит409и привязки нет: иначе тот, кто первым зарегистрировал чужой адрес с паролем, делил бы аккаунт с владельцем адреса. Пользователю нужно войти паролем и подтвердить адрес (или сбросить пароль кодом из письма), после чего вход через Google сработает; - иначе создаёт новый. Для него нужен
usernameпо правилам регистрации (это адрес канала, потом его не сменить);display_nameберётся из имени в Google, email из токена. Пароля у такого аккаунта нет:/auth/loginотвечает ему тем же401, что и на неверный пароль, а завести пароль можно сбросом пароля по коду из письма.
Созданный или привязанный через Google аккаунт получает
email_verified: true: адрес подтвердил Google.
username читается только в третьем случае; в первых двух его можно не
слать. Каждый вход начинает новую сессию, как /auth/login.
| Ответ | Когда |
|---|---|
200 | TokenResponse: вход в найденный аккаунт или в только что созданный |
400 | username не проходит правила регистрации |
401 | токен испорчен, просрочен, выписан для другого client id или email не подтверждён |
409 | аккаунта нет, а username не прислан или занят (тело ниже) |
409 | аккаунт с этим email уже привязан к другому аккаунту Google (только error) |
409 | аккаунт с этим email есть, но адрес не подтверждён (только error) |
503 | вход через Google не настроен на сервере или ключи Google недоступны |
// 409: нужно имя пользователя
{
"error": "аккаунта ещё нет: выберите имя пользователя",
"suggested_username": "aziz"
}
suggested_username выведен из email и свободен на момент ответа. Покажите
то же поле имени, что на форме регистрации, с этим значением, и повторите
запрос с тем же id_token и выбранным username. ID-токен Google живёт
час, так что повтор укладывается.
Запрос считается в лимит /auth/*. Сервер включает вход, когда задан
GOOGLE__CLIENT_ID (client id OAuth из Google Cloud; через запятую, если
клиентов несколько, например веб и мобильное приложение). Без него ручка
отвечает 503, и кнопку стоит прятать или объяснять, что вход недоступен.
Идентификаторы
У видео короткий публичный идентификатор — 11 символов алфавита
A-Za-z0-9_-, как в ссылках YouTube (dQw4w9WgXcQ). Именно он приходит
в поле id и подставляется во все пути:
/videos/dQw4w9WgXcQ
/videos/dQw4w9WgXcQ/playback
/videos/dQw4w9WgXcQ/hls/master.m3u8
Внутренний UUID наружу не выходит вовсе. Идентификатор непрозрачен: не разбирайте его и не пытайтесь по нему что-то вычислить.
Где видео упоминается внутри другой модели (Comment.video_id,
Playlist.cover_video_id, Notification.video_id), там тоже публичный id,
и /videos/{video_id} по нему открывается.
Остальные сущности — пользователи, каналы, комментарии, плейлисты,
уведомления — адресуются UUID. Канал вдобавок доступен по имени:
/channels/by-username/neo. Строка неверного формата в пути видео даёт 404,
а не 400: API не подсказывает, какие идентификаторы бывают.
Ошибки
Тело всегда одинаковое: {"error": "человекочитаемый текст"}.
| Код | Когда |
|---|---|
400 | не прошла валидация, битый курсор, подписка на себя |
401 | нет токена, токен просрочен или испорчен |
403 | доступ есть, но действие чужое (правка чужого видео) |
404 | нет объекта — или он есть, но скрыт (см. ниже) |
409 | состояние не позволяет: файл не загружен, видео не готово |
413 | загруженный файл больше лимита (/complete, см. «Загрузка») |
422 | тело не разобралось (не тот тип поля, неизвестный enum) |
429 | превышен лимит частоты, см. заголовок Retry-After |
500 | внутренняя ошибка; подробности только в логах сервера |
503 | на сервере выключена почта, а ручка шлёт код (см. «Коды…») |
503 | вход через Google не настроен или ключи Google недоступны |
404 вместо 403 для приватного. Чужое приватное видео отвечает 404,
как будто его не существует. Это намеренно: иначе по кодам ответов можно
перебором узнать, какие идентификаторы заняты. Не показывайте пользователю
«нет доступа» там, где пришёл 404.
Ограничение частоты
Общий лимит — 20 запросов в секунду с всплеском до 40, на /auth/* строже:
10 в минуту. При отказе приходит 429 и Retry-After в секундах.
Клиенту стоит уважать Retry-After и не ретраить вслепую: параллельные
вкладки складываются в один счётчик.
По чему считается общий лимит:
- запрос с валидным access-токеном (
Authorization: Bearer ...) — по пользователю, так что зрители за одним офисным NAT не делят счётчик; - запрос без токена, с просроченным или испорченным — по IP-адресу клиента. Невалидный токен сам по себе лимитер не отвергает, это решает роут.
Лимит /auth/* всегда считается по IP-адресу, даже если токен есть.
IP-адрес клиента — это адрес соединения. За обратным прокси, чья сеть
указана в RATE_LIMIT__TRUSTED_PROXIES, адресом считается самый правый
элемент X-Forwarded-For, который сам не входит в доверенные сети. От
остальных соединений заголовок игнорируется, поэтому подставить в него чужой
адрес бесполезно. Серверный код (например, Next.js), который ходит в API от
имени зрителя без его токена, делит один счётчик на всех, если только он не
приходит из доверенной сети и не передаёт адрес зрителя в X-Forwarded-For.
Пагинация
Два разных механизма — не перепутайте.
Курсорная (/videos, /videos/my, /feed, /channels/{id}/videos,
/me/history, /notifications, комментарии). Параметры ?limit= (1–100,
по умолчанию 20) и ?cursor=.
{ "items": [/* ... */], "next_cursor": "dHwyMDI2LTA5LTA2VDEwOjAwOjAwWnw..." }
Следующая страница — тот же запрос с cursor=next_cursor. next_cursor: null
означает, что данные кончились. Курсор непрозрачен: не разбирайте его и не
конструируйте сами.
Внутри курсора спрятаны две разные формы пагинации. Хронологические
сортировки листаются по ключу «время + id», ранжированные (sort=trending,
sort=most_viewed, sort=top у комментариев) — по смещению: keyset-пагинация
требует стабильного полного порядка, а ранг не уникален и меняется вместе
с данными. Снаружи разницы нет, но курсор нельзя переносить между
сортировками: смена sort без сброса cursor даёт 400. Меняете
сортировку — начинайте список заново.
Курсор помнит сортировку, под которой выдан, поэтому 400 придёт и при
переходе между сортировками одного вида (newest → oldest). У /videos/my
курсор помнит и sort, и order.
/me/watch-later листается по третьему ключу, порядку, который задал сам
зритель (см. «Смотреть позже и понравившееся»); курсор другого вида там
тоже 400.
Offset-овая (/videos/search, /subscriptions, /playlists,
/playlists/{id}/items, /me/reports). Параметры ?limit= и ?offset=,
в ответе они же:
{ "items": [/* ... */], "limit": 20, "offset": 0 }
Модели
type VideoStatus = "uploading" | "processing" | "ready" | "failed";
type VideoKind = "regular" | "short" | "live";
type VideoCategory =
// словарь закрыт, см. «Категория»
| "music"
| "podcasts"
| "news"
| "nature"
| "animation"
| "gaming"
| "education"
| "sports"
| "entertainment";
type FailureReason = "unsupported_format" | "corrupt" | "no_video_stream" | "internal";
type Visibility = "public" | "unlisted" | "private";
type Reaction = "like" | "dislike";
type FeedSort = "newest" | "oldest" | "trending" | "most_viewed";
type CommentSort = "newest" | "top";
interface ChannelSummary {
// всё, что нужно строке под заголовком
id: string; // UUID автора, он же id канала
username: string;
display_name: string;
avatar_url: string | null;
subscriber_count: number;
}
interface Video {
id: string; // 11 символов, короткая ссылка
channel: ChannelSummary; // канал едет вместе с видео, второй запрос не нужен
title: string;
description: string | null;
location: string | null; // место съёмки, до 100 символов; null, если не указано
category: VideoCategory | null; // одна категория или null; название берите из каталогов клиента
status: VideoStatus;
kind: VideoKind; // чем видео является; со статусом не связано
visibility: Visibility;
duration_secs: number | null; // появляется после транскодинга
thumbnail_url: string | null; // путь этого же API; владельцу приватного — подписан
hls_url: string | null; // null, пока видео не транскодировано
view_count: number;
like_count: number;
dislike_count: number;
comment_count: number;
tags: string[]; // до 15 штук, нижний регистр
published_at: string | null; // когда стало видно; null — не публиковалось
created_at: string; // RFC 3339
updated_at: string;
// Только владельцу: в GET /videos/{id} своего видео, GET /videos/my и в
// ответах на свои POST/PATCH. У всех остальных этих ключей нет вовсе.
failure_reason?: FailureReason | null; // непусто только при status = failed
source_filename?: string | null; // имя файла из POST /videos, без пути
}
// Только GET /videos/{id}: карточка плюс то, что касается этого зрителя.
// В лентах, поиске, списках и ответах на POST/PATCH этих ключей нет.
interface VideoDetail extends Video {
in_watch_later: boolean | null; // в «Смотреть позже» зрителя; null без токена
captions: CaptionTrack[]; // всегда есть; [] — субтитров нет, см. «Субтитры»
}
interface CaptionTrack {
lang: string; // тег BCP 47: "uz", "uz-Cyrl", "ru", "en"; в <track srclang>
label: string; // подпись в меню: присланная автором или самоназвание языка
url: string; // путь этого API, как thumbnail_url; владельцу приватного — подписан
kind: "subtitles"; // других видов пока нет
auto: false; // распознавания речи нет, дорожки загружает автор
}
interface Comment {
id: string;
video_id: string; // публичный id видео (11 символов), как Video.id
author_id: string;
author_username: string;
author_display_name: string;
author_avatar_url: string | null;
parent_id: string | null; // на что ответили: корень или ответ; null — сам корень
body: string;
like_count: number;
dislike_count: number; // публичный, как и like_count
reply_count: number; // прямые ответы; есть и у ответов, у второго уровня всегда 0
my_reaction: Reaction | null; // null для анонима и для того, кто не голосовал
liked_by_me: boolean | null; // my_reaction === "like"; null для анонима
edited_at: string | null; // непусто → показать «изменено»
created_at: string;
updated_at: string;
}
interface ChannelLink {
label: string;
display: string;
url: string;
icon_url: string | null; // значок сайта: путь этого API или null, см. «Значки ссылок»
}
interface Channel {
id: string;
username: string; // адрес канала: @username
display_name: string;
description: string; // короткая строка карточки
about: string | null; // длинный текст вкладки «о канале»
avatar_url: string | null; // путь этого API после загрузки, см. «Аватар и баннер»
banner_url: string | null;
country: string | null; // ISO 3166-1 alpha-2, всегда в верхнем регистре
links: ChannelLink[];
created_at: string;
subscriber_count: number;
video_count: number; // только публичные готовые видео
view_count: number; // суммарно по всем публичным видео канала
subscribed: boolean | null; // null для анонима
notifications_enabled: boolean | null; // колокольчик; null, если подписки нет
}
interface Playlist {
id: string;
owner_id: string;
owner_username: string;
owner_display_name: string;
owner_avatar_url: string | null;
title: string;
description: string | null;
visibility: Visibility;
video_count: number;
cover_video_id: string | null; // первое видео плейлиста — обложка карточки
cover_thumbnail_url: string | null; // превью обложки; своё приватное — подписано
created_at: string;
updated_at: string;
}
interface WatchProgress {
position_secs: number; // где остановились
watched_secs: number; // суммарно просмотрено
completed: boolean;
last_watched_at: string;
}
type NotificationKind = "new_video" | "comment_reply" | "video_comment";
interface Notification {
id: string;
kind: NotificationKind;
actor_id: string;
actor_username: string;
actor_display_name: string;
actor_avatar_url: string | null;
video_id: string | null; // короткий id, если событие про видео
video_title: string | null;
comment_id: string | null;
read: boolean;
created_at: string;
}
type ReportReason =
"spam" | "sexual" | "violence" | "hate" | "harassment" | "misinformation" | "copyright" | "other";
interface Report {
id: string;
video_id: string;
reason: ReportReason;
details: string | null;
status: "pending" | "reviewed" | "dismissed";
created_at: string;
}
Формулировку уведомления («X выложил Y») собирает клиент: она зависит от
языка, а API отдаёт только kind, автора и заголовок видео.
Жизненный цикл видео: uploading → (подтверждение загрузки) → processing →
(воркер) → ready, либо failed, если транскодинг не удался. Пока статус не
ready, hls_url и thumbnail_url пустые (кроме случая, когда владелец
уже загрузил своё превью, см. «Выбор превью»), а видео не попадает ни
в ленту, ни в поиск.
Видео
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| POST | /videos | токен | Создать запись, получить ссылку для загрузки |
| POST | /videos/{id}/complete | владелец | Подтвердить загрузку |
| POST | /videos/{id}/upload-url | владелец | Новая ссылка для загрузки |
| POST | /videos/{id}/multipart | владелец | Начать загрузку частями |
| GET | /videos/{id}/multipart | владелец | Какие части уже легли |
| POST | /videos/{id}/multipart/parts | владелец | Подписать части |
| POST | /videos/{id}/multipart/complete | владелец | Собрать файл и подтвердить |
| DELETE | /videos/{id}/multipart | владелец | Отменить загрузку частями |
| POST | /videos/{id}/retranscode | владелец | Перегнать исходник заново |
| GET | /videos | все | Лента: public + ready, курсор |
| GET | /videos/search?q= | все | Поиск, offset; фильтры, см. «Поиск» |
| GET | /videos/search/suggest?q= | все | Подсказки: список строк |
| GET | /videos?kind= | все | Лента одного рода: short, live |
| GET | /videos?category= | все | Лента одной категории |
| GET | /categories | все | Словарь категорий, см. «Категория» |
| GET | /videos/my | токен | Свои видео: фильтры студии, курсор |
| GET | /videos/my/counts | токен | Счётчики вкладок студии |
| GET | /videos/{id} | по видимости | Карточка (VideoDetail) |
| PATCH | /videos/{id} | владелец | Правка метаданных |
| DELETE | /videos/{id} | владелец | Удалить запись и файлы |
| GET | /videos/{id}/playback | по видимости | Как воспроизводить |
| POST | /videos/{id}/view | все | Засчитать просмотр |
| POST | /videos/{id}/share | все | Записать репост |
| GET | /videos/{id}/related | по видимости | Похожие видео (до 20), ?for=viewer |
| GET | /videos/{id}/thumbnail | по видимости | Превью (картинка); подпись заменяет токен |
| GET | /videos/{id}/thumbnails | владелец | Варианты превью и какой выбран |
| GET | /videos/{id}/thumbnails/{t} | владелец | Один вариант (картинка); подпись заменяет токен |
| POST | /videos/{id}/thumbnail/upload | владелец | Ссылка для загрузки своей картинки |
| POST | /videos/{id}/thumbnail/complete | владелец | Проверить картинку и выбрать её |
| GET | /videos/{id}/hls/{path} | по видимости | Манифест и сегменты |
| GET | /videos/{id}/captions/{lang}.vtt | по видимости | Файл субтитров (WebVTT); подпись заменяет токен |
| POST | /videos/{id}/captions/{lang} | владелец | Ссылка для загрузки дорожки субтитров |
| POST | /videos/{id}/captions/{lang}/complete | владелец | Проверить .vtt и опубликовать дорожку |
| DELETE | /videos/{id}/captions/{lang} | владелец | Снять дорожку субтитров |
| GET | /feed/mixes | все | Полка миксов для главной, до 20 |
Лента: сортировка и категории
GET /videos?sort=trending&category=music&limit=20
sort — newest (по умолчанию), oldest, most_viewed, trending.
«В тренде» — просмотры, поделённые на возраст: без деления подборка навсегда
застревала бы на старых роликах с большим счётчиком.
category фильтрует ленту по одной категории из словаря: это и есть чипы
категорий над ней и страница /music (см. «Категория»). Неизвестный слаг
отвечает 400, пустой category= значит «без фильтра».
tag фильтрует ленту по одному свободному тегу, который набрал автор. Для
чипов он больше не нужен: тег ничем не ограничен, и чип, отправленный как
тег, находил только то, что автор случайно так назвал. Теги хранятся в
нижнем регистре, так что фильтр регистронезависим только если вы шлёте их
уже нормализованными.
kind сужает ленту до одного рода видео при любой sort, см. «Род видео».
Все фильтры складываются через «И»: ?category=music&kind=short отдаёт
музыкальные шортсы.
Смена sort требует сбросить cursor (см. «Пагинация»).
Похожие и «для вас»
GET /videos/{id}/related отдаёт до 20 видимых видео, кроме самого {id}:
сначала по пересечению тегов с играющим видео, потом свежие. Ответ — голый
массив карточек Video, без конверта items / next_cursor.
GET /videos/{id}/related?for=viewer — та же колонка, ранжированная для
зрителя (чип «Siz uchun»). Форма ответа, лимит, правила видимости и лимит
запросов те же.
- С токеном: ранг — число общих тегов с последними 50 видео из истории
зрителя плюс 2 за подписку на канал автора; при равенстве — теги играющего
видео, потом свежесть. Видео, которые зритель досмотрел
(
progress.completed), в выдачу не попадают. - Без токена: ровно тот же ответ, что без параметра, так что у гостя чип не пустеет.
Другое значение for — 400.
Полка миксов
Дизайн главной ставит в сетку видео карточку микса: обложка со стопкой
листов, бейдж «Miks» вместо длительности и одна строка каналов вместо
автора. GET /videos её не отдаёт и не будет: превратить элементы ленты в
объединение «видео или микс» значило бы сломать каждого клиента, который
уже рисует их как видео. Поэтому миксы отдельный ресурс, а в сетку их
вставляет клиент.
GET /feed/mixes?limit=4 открыт всем, токен необязателен:
{
"items": [
{
"id": "6f1c2b9e-0d4a-4c51-9a3e-2b7d8f0e1a22",
"title": "Kechki jazz",
"cover_url": "/videos/dQw4w9WgXcQ/thumbnail",
"item_count": 12,
"contributors": [
{ "display_name": "Biznesnoma" },
{ "display_name": "IGLEES" },
{ "display_name": "NAVJAAX" }
],
"contributor_count": 7,
"source": "playlist"
}
]
}
limitот 1 до 20, по умолчанию 4. Вне этих границ400, а не прижатие: полка не листается, курсора иnext_cursorу неё нет.sourceговорит, откуда микс. Сейчас это всегда"playlist": микс это публичный плейлист, в котором хотя бы два публичных готовых видео, аidэто id плейлиста, карточка ведёт на него (GET /playlists/{id},GET /playlists/{id}/items). Автоматические миксы появятся в этом же ресурсе с другимsource; карточку с незнакомымsourceпропускайте.- Плейлисты «по ссылке» и приватные в полку не попадают никогда. С токеном в ней нет и плейлистов самого зрителя.
item_count,contributorsиcontributor_countсчитают только публичные готовые видео: приватное, «по ссылке» или ещё не перегнанное видео в плейлисте не видно ни в числе, ни в именах. Поэтомуitem_countможет быть меньшеvideo_countтого же плейлиста.contributors: до трёх разных каналов в порядке плейлиста, каждый по своему первому видео. Автор плейлиста не исключается: если в подборке его видео, его канал в ней и правда есть, а подписать автора можно изGET /playlists/{id}.contributor_countговорит, сколько каналов всего; если он больше длиныcontributors, допишите «va boshqalar».cover_url: превью первого публичного готового видео плейлиста (не обязательно первого вообще, какcover_thumbnail_urlу плейлиста), ссылка без подписи.null, если у него ещё нет превью.- Порядок: сумма просмотров засчитанных видео, затем недавно изменённые плейлисты (правка или состав), затем id. Он устойчив: два запроса подряд без новых просмотров отдают одно и то же.
Как вставлять в сетку. Загрузите полку один раз вместе с первой страницей
GET /videos и ставьте миксы на фиксированные места: первый, по дизайну,
вторым элементом первого ряда (на узком экране первой карточкой),
следующие через равный шаг рядов, пока они не кончатся. Полка не зависит
от cursor, sort и tag ленты, поэтому при подгрузке следующих страниц
её не перезапрашивайте, а в отфильтрованной по тегу или роду ленте не
показывайте. Видео, которые есть и в миксе, и в ленте, не убирайте: микс
это ссылка на плейлист, а не его содержимое.
Просмотры
POST /videos/{id}/view возвращает {"view_count": 123}.
Зовите его один раз на начало просмотра, а не по таймеру. Для авторизованного зрителя повторный заход в пределах получаса не засчитывается — дедупликация идёт по истории просмотров. Анонимов дедуплицировать нечем, их просмотры считаются всегда. Ответ приходит и в том случае, когда просмотр не зачли: в нём текущее значение счётчика, которое и надо нарисовать.
Каждый засчитанный просмотр, кроме счётчика, попадает в журнал просмотров,
по которому считается аналитика владельца (см. «Аналитика»). Правила у них
общие: что не увеличило view_count, не попало и в журнал.
Репосты
POST /videos/{id}/share записывает репост и отвечает 204 без тела.
Зовите его, когда зритель выбрал способ в поповере «Поделиться» (а не когда
поповер открылся). Токен необязателен: поделиться может и аноним.
{ "target": "telegram" }
Тело необязательно: запрос без Content-Type или с {} записывает репост
без способа. target — слово до 30 символов из строчной латиницы, цифр,
_, - и .: telegram, copy_link, whatsapp и так далее. Список
способов на сервере не зашит, но регистр и пробелы не нормализуются,
поэтому Telegram или copy link дают 400: иначе один способ
расходился бы на несколько написаний. Пустая строка равна отсутствию поля.
Видимость та же, что у просмотра: чужое приватное видео — 404. Повторы
не схлопываются (отличить второе нажатие от второго адресата нечем), от
накрутки защищает только общий лимит частоты. Счётчика репостов у видео
нет: число видит только владелец, в totals.shares аналитики.
Загрузка: три шага
// 1. Создаём запись. visibility по умолчанию private.
const created = await post("/videos", {
title: "Прогулка по городу",
description: null,
location: "Toshkent", // необязательно, см. «Место съёмки»
category: "music", // необязательно, см. «Категория»
visibility: "public",
source_filename: file.name, // необязательно
});
// { video: Video, upload_url: "https://s3...", expires_in: 900 }
// 2. Кладём файл прямо в хранилище. Этот запрос идёт мимо API.
await fetch(created.upload_url, { method: "PUT", body: file });
// 3. Подтверждаем: API сам проверит, что объект появился в хранилище.
await post(`/videos/${created.video.id}/complete`);
// Video со статусом processing
Замечания:
upload_urlживётexpires_inсекунд (на проде 900). Срок проверяется в момент, когда запрос приходит в хранилище: PUT, начатый до истечения ссылки, может закончиться после него. Замерено на проде 2026-09-23 (#254): файл в 1 014 527 байт на скорости 1000 байт/с шёл 1014 с приexpires_in: 900и получил200, а/completeпосле него — тоже200. Таймауты nginx перед хранилищем (300 с) — это паузы между записями, а не предел на весь запрос, поэтому непрерывно идущее тело они не рвут.- Начинать PUT по просроченной ссылке бесполезно (
403), но и создавать видео заново не нужно:POST /videos/{id}/upload-urlвыдаёт новую ссылку на тот же файл того же видео (см. ниже). - Шаг 2 не отправляйте с заголовком
Authorization: подпись уже в ссылке, лишние заголовки только мешают. - Если браузер ругается на CORS на шаге 2, это настройка хранилища
(
MINIO_API_CORS_ALLOW_ORIGIN), а не API. - Повторный
/completeна уже подтверждённом видео вернёт409— это защита от повторной постановки в очередь. /completeвернёт409и в том случае, если файла в хранилище нет: API верит хранилищу, а не клиенту.- Файл больше 15 000 000 000 байт (десятичные 15 ГБ, как на экране выбора
файла; настройка сервера
UPLOAD__MAX_BYTES)/completeне примет: ответ413 {"error": "..."}, и запись вместе с файлом к этому моменту уже удалены. Повторять/completeбессмысленно, следующий запрос по этомуidдаст404. Сама ссылкаupload_urlразмер не ограничивает, поэтому проверяйте размер доPOST /videos, чтобы не гонять гигабайты впустую. - Брошенная загрузка не живёт вечно: запись, которая провисела в
uploadingбольше суток (настройка воркераWORKER__ABANDONED_UPLOAD_SECS), сервер удаляет вместе с файлом, если тот успел лечь. Удаляет фоновый обход раз в минуту, так что точный момент не гарантирован. Такое видео пропадает и изGET /videos/my.
Имя файла и причина отказа
source_filename в POST /videos необязателен. API отрезает путь (по /
и \), убирает управляющие символы и пробелы по краям; длиннее 255 символов —
400. Пустое после этого имя хранится как null. Видит его только владелец.
failure_reason появляется у видео в failed и стирается, как только видео
снова уходит в перегон:
| Код | Что значит | Повторять? |
|---|---|---|
unsupported_format | файл не распознан как видео | нет |
corrupt | файл распознан, но не читается до конца | нет |
no_video_stream | в файле нет видеодорожки (например, один звук) | нет |
internal | сбой на стороне сервера | да |
С первыми тремя воркер не тратит попыток и отказывает сразу: тот же файл не перегонится и с третьего раза. Текст ошибки перегона наружу не отдаётся, только код.
Новая ссылка на тот же файл
POST /videos/{id}/upload-url
-> 200 {"upload_url": "https://s3...", "expires_in": 900}
Только владельцу и только пока видео в uploading; иначе 409. Ссылка та же
по смыслу, что из POST /videos: PUT целиком, потом /complete. Старая
ссылка при этом не отзывается и живёт свой срок. Тела у запроса нет.
Загрузка частями (multipart)
Для больших файлов. Файл режется на части по part_size байт (16 МиБ),
каждая часть кладётся своим PUT по своей ссылке, и легшие части хранилище
помнит. Обрыв стоит одной части, а не всего файла; после перезагрузки
страницы догружается только недостающее, и id видео не меняется.
// 1. Создаём запись, как обычно (POST /videos). Её upload_url не нужен.
const { video } = await post("/videos", { title, visibility });
// 2. Начинаем загрузку частями. size — размер файла в байтах.
const mp = await post(`/videos/${video.id}/multipart`, { size: file.size });
// { upload_id: "…", part_size: 16777216, part_count: 895,
// parts: [{ n: 1, url: "https://s3..." }, …], expires_in: 900 }
// 3. Кладём части. Часть n — байты [(n-1)*part_size, n*part_size).
// ETag каждой части берём из заголовка ответа на её PUT.
const res = await fetch(url, { method: "PUT", body: file.slice(from, to) });
const etag = res.headers.get("ETag");
// 4. Ссылки на следующие части (или взамен просроченных) — по номерам,
// не больше 100 за запрос.
const more = await post(`/videos/${video.id}/multipart/parts`, {
upload_id: mp.upload_id, numbers: [33, 34, 35],
});
// { parts: [{ n: 33, url: "…" }, …], expires_in: 900 }
// 5. Собираем файл. Части — по возрастанию номера, все до одной.
await post(`/videos/${video.id}/multipart/complete`, {
upload_id: mp.upload_id,
parts: [{ n: 1, etag: "\"…\"" }, …],
});
// Video со статусом processing — то же, что ответ /complete
Продолжить после обрыва или перезагрузки:
GET /videos/{id}/multipart (или ?upload_id=…)
-> 200 {"upload_id": "…", "part_size": 16777216,
"parts": [{"n": 1, "etag": "\"…\"", "size": 16777216}, …]}
Без upload_id отвечает про текущую загрузку видео, так что клиенту, который
потерял id вместе с вкладкой, достаточно id видео и того же файла. Части из
ответа уже лежат; недостающие номера подписываются через /multipart/parts.
Сверять, что выбран тот же файл, должен клиент: API файла не видит.
Отменить: DELETE /videos/{id}/multipart?upload_id=… → 204. Видео остаётся
в uploading, можно начать заново любым способом.
Замечания:
- Частей не больше 10 000, каждая, кроме последней, ровно
part_size. Файл большеpart_size × 10 000(160 ГиБ) отклоняется400сразу на шаге 2. - При создании подписываются только первые 32 части: ссылка живёт
expires_inсекунд, а девятьсот частей грузятся часами, и подписанные заранее ссылки протухли бы в очереди. Остальные просите по мере надобности. - PUT части, начатый до истечения ссылки, может закончиться после него — так же, как одиночный PUT (замер выше).
- У видео одна текущая загрузка частями. Новый
POST /multipartотменяет прежнюю вместе с её частями. Чужой или устаревшийupload_idв/parts,/complete,GETиDELETE—404, как и отсутствие текущей загрузки. /multipart/completeотвечает400, если хранилище не собрало файл из присланного списка (неверный ETag, пропущенная часть, часть меньше 5 МиБ не в конце). Повтор после того, как ответ на успешную сборку потерялся, безопасен: файл уже собран, и API просто подтвердит загрузку./completeи/multipart/completeпроверяют одно и то же: видео вuploading, файл лежит в хранилище. Подтверждение любым путём отменяет незаконченную загрузку частями, если она осталась.DELETE /videos/{id}отменяет её тоже.- ETag из ответа на PUT браузер видит, только если хранилище отдаёт
Access-Control-Expose-Headers: ETag. CORS бакета у нас — умолчание MinIO (своей политики нет, nginx перед хранилищем CORS не трогает), и по исходникам MinIO это умолчание отдаётETagсреди открытых заголовков. На проде это не замерено; еслиres.headers.get("ETag")вернётnull, это настройка хранилища, а не API.
Перегон заново
POST /videos/{id}/retranscode (владелец) отправляет уже подтверждённое
видео через воркер ещё раз. Файл при этом не меняется: ручка нужна, когда
поменялись настройки перегона, а исходник остался прежним.
await post(`/videos/${id}/retranscode`);
// Video со статусом processing
Замечания:
- Это не замена
/complete. На видео со статусомuploadingвернётся409: подтверждать загрузку эта ручка не умеет. - На видео, которое уже в
processing, тоже409, пока его перегон жив. Исключение — зависший перегон: если воркер не подавал признаков жизни по задаче этого видео дольше 10 минут (настройка сервераTRANSCODE__STALLED_SECS), ручка возвращает задачу в очередь с чистым счётчиком попыток и отвечает200сVideoвprocessing. Так что «Повторить» на видео, которое давно висит вprocessing, имеет смысл показывать:409означает «перегон идёт, ждите». Воркер и сам возвращает брошенные задачи в очередь через несколько минут после остановки, так что обычно до кнопки дело не доходит. - Как и
/complete, проверяет исходник в хранилище и отвечает409, если его там больше нет. - Пока идёт перегон, статус
processing, а лента отдаёт толькоpublic+ready, поэтому публичное видео на это время из неё пропадает. Смотреть его можно всё это время:playbackсмотрит на готовый HLS, а не на статус, и старые сегменты лежат в хранилище, пока воркер не перезапишет их.
Удаление
DELETE /videos/{id} (владелец) отвечает 204 и удаляет запись вместе со
всеми файлами видео в хранилище: исходником, сегментами HLS и превью. Удалять
можно в любом статусе, в том числе посреди перегона: то, что воркер успеет
дописать после удаления, он уберёт сам, когда закончит. Отменённую загрузку
(оборванный PUT) удаляют тем же запросом.
Род видео
kind отвечает на вопрос «что это за видео», а status — «в каком оно
состоянии». Это разные вопросы: запись трансляции точно так же проходит
uploading → processing → ready, как обычная загрузка.
kind | что это |
|---|---|
regular | обычная загрузка, умолчание |
short | короткое вертикальное видео для деки /shorts |
live | запись прошедшего эфира |
live — это архив, а не идущий эфир. Живого вещания в системе нет: ни
ingest, ни пакетизатора, ни скользящего окна HLS, и VideoStatus не растёт
ради него новым членом. Вкладка Translatsiya и страница /live рисуют
законченные трансляции той же карточкой, что и обычные видео, — так они и
нарисованы в макете.
Задаётся при создании (POST /videos, поле kind, по умолчанию regular).
PATCH /videos/{id} его не трогает: род есть свойство снятого материала, а не
настройка, которую переигрывают.
Шортс по исходнику. Род после создания меняет только воркер.
Разобрав исходник через ffprobe, он делает regular шортсом, если кадр на
экране выше, чем шире, и ролик не длиннее 180 секунд (то же правило
height > width && duration <= 180, что проверяет браузер перед
POST /videos). Поворот из метаданных учитывается: телефонный ролик,
записанный кадром 1920x1080 с поворотом на 90°, вертикальный. Род меняется
в той же записи, что переводит видео в ready, поэтому в лентах оно сразу
появляется с итоговым родом. Так шортсом становится и файл, который браузер
не смог разобрать (HEVC в части сборок Chrome, ProRes, часть MKV) и прислал
как regular, и старый вертикальный ролик после POST /videos/{id}/retranscode.
Правило работает только в одну сторону:
- присланный
shortне понижается никогда, даже если кадр горизонтальный или ролик длиннее трёх минут: автор выбрал это сам, и молча переделать его выбор хуже, чем не исправить чужую ошибку; liveне трогается вовсе: запись эфира остаётся записью эфира при любой форме кадра.
Пока видео в uploading или processing, kind равен присланному; верным
он становится, когда видео ready. Тег shorts воркер не ставит.
Фильтр ?kind= есть у /videos, у /channels/{id}/videos, у /videos/my
и у /videos/my/counts и сочетается с остальными параметрами при любой
сортировке. Неизвестное значение отвечает 400.
Тот же фильтр с теми же значениями есть у поиска, см. «Поиск».
Отсутствие параметра означает «любые», а не «только обычные»: лента без
фильтра показывает всё, иначе шортсы пропали бы с главной.
GET /videos?kind=short дека /shorts
GET /channels/{id}/videos?kind=live вкладка Translatsiya
GET /channels/{id}/videos вкладка Videolar: пока все роды
GET /videos/my?kind=short студия: только свои шортсы
Последняя строка — известное упрощение: вкладка Videolar показывает и шортсы
тоже. Чтобы она показывала только regular, ей нужен ?kind=regular, и это
решение клиента, а не сервера.
До этого поля короткие видео опознавались по тегу shorts — строке, которую
автор может написать с опечаткой, удалить или занять под обычную тему. Тег
остаётся обычным тегом и ничего больше не значит.
Теги
tags задаются при создании и заменяются целиком при правке (PATCH с полем
tags). До 15 штук, каждый 1–30 символов. API обрезает пробелы, приводит
к нижнему регистру и убирает повторы, так что ["Rust", "rust", " Axum "]
превращается в ["rust", "axum"]. Теги участвуют в поиске с меньшим весом,
чем заголовок и описание, и по ним же фильтруется лента.
Место съёмки
location задаёт необязательное место съёмки свободным текстом («Toshkent»,
«Samarqand, Registon»). Его рисует карточка описания на странице просмотра:
значок метки и название. Задаётся в POST /videos и меняется в
PATCH /videos/{id}, а приходит в каждом Video, где бы видео ни
отдавалось: в ленте, поиске, истории, плейлисте, ответе на правку.
API обрезает пробелы по краям. После обрезки допускается до 100 символов
(символов, а не байт), на более длинное ответ 400. Пустая строка, в том числе из одних
пробелов, ошибкой не считается: в POST это то же, что поля нет, а в
PATCH то же, что null, то есть очистка. Поэтому в ответе место либо
непустая строка, либо null, и рисовать метку нужно только в первом
случае.
Категория
category задаёт одну категорию видео из закрытого словаря, которую выбирает
автор. У видео её либо нет (null), либо она одна. Задаётся в
POST /videos, меняется в PATCH /videos/{id} и приходит в каждом Video.
Словарь отдаёт GET /categories (без токена) в порядке показа чипов:
[{ "id": "music" }, { "id": "podcasts" }, { "id": "news" }, ...]
id | чип в макете |
|---|---|
music | Musiqa |
podcasts | Podkastlar |
news | Yangiliklar |
nature | Tabiat |
animation | Animatsiyalar |
gaming | в макете нет |
education | в макете нет |
sports | в макете нет |
entertainment | в макете нет |
Ответ кэшируется (Cache-Control: public, max-age=3600): словарь меняется
только с новой сборкой API. Первые пять id совпадают с id чипов веба,
так что чипу достаточно слать ?category= вместо ?tag=.
Названий в ответе нет, и это решение, а не пропуск. Название категории
является текстом интерфейса на четырёх языках, и живёт оно в каталогах клиента, как и
любые другие подписи. Одна непереведённая строка от API вернула бы ровно ту
ошибку, что чинили в #174. Новый слаг, пришедший из /categories раньше,
чем клиент получил его перевод, клиенту лучше не рисовать вовсе.
Что категорией не является. Четыре чипа из ряда в макете не категории и в словарь не входят:
| чип | что это на самом деле |
|---|---|
| Barchasi | отсутствие фильтра: запрос без category |
| Pleylistlar | другой ресурс: GET /playlists |
| Jonli efirlar | род видео: ?kind=live, см. «Род видео» |
| Yaqinda yuklangan | сортировка: ?sort=newest, окно считает клиент |
Правила. Слаг сравнивается точно: Music, music и musiqa
считаются неизвестными слагами, и на них, как и на пустую строку в теле, API отвечает
400. В PATCH отсутствие поля оставляет категорию как есть, а null
убирает её. Фильтр ?category= есть у GET /videos (при любой sort),
GET /channels/{id}/videos, GET /videos/search, GET /videos/my и
GET /videos/my/counts; он сочетается с kind, tag, q и остальными
фильтрами через «И». В query-строке пробелы по краям срезаются, а пустое
значение значит «без фильтра»; на неизвестное ответ 400.
Видео, загруженные до категорий. Автоматической разметки нет, с одним
исключением: видео, у которого был тег, в точности равный слагу
(например music), получило эту категорию при переходе на неё, чтобы
/music находил то же, что находил через ?tag=music. Если таких тегов
было несколько, взят первый в порядке, в каком их записал автор. Сами теги
не тронуты. У остальных старых видео категория null, пока автор её не
выберет.
Правка
PATCH /videos/{id} принимает любое подмножество полей title,
description, location, category, visibility, tags, thumbnail_id.
Отсутствие поля и null различаются:
{ "title": "Новый заголовок" } // описание, место и категория не тронуты
{ "description": null } // описание очищено
{ "location": "Toshkent" } // место задано
{ "location": null } // место очищено
{ "category": "news" } // категория задана
{ "category": null } // категории больше нет
{ "thumbnail_id": "t50" } // показывать кадр на 50% (см. «Выбор превью»)
Мои видео: вкладки, фильтры, сортировка
GET /videos/my?state=published&visibility=public,unlisted&q=bozor&sort=view_count&order=desc&limit=50
GET /videos/my/counts?q=bozor
Всё, что рисует страница «Videolar» студии, считается на сервере: вкладки со счётчиками, поиск, фильтр «Holati» и сортировка колонок.
| Параметр | Значения | По умолчанию |
|---|---|---|
state | published, draft, archived | все видео |
status | через запятую: uploading, processing, ready, failed | любой |
visibility | через запятую: public, unlisted, private | любая |
q | слова для поиска в названии и описании | без поиска |
kind | один род: regular, short, live (см. «Род видео») | любой |
category | одна категория из GET /categories (см. «Категория») | любая |
sort | created_at, published_at, view_count, comment_count, like_count, title | created_at |
order | asc, desc | desc |
Любое неизвестное значение (в том числе внутри списка) — 400. Без
параметров ответ тот же, что и раньше: все свои видео, новые сверху.
Вкладки выводятся из полей, которые уже есть у видео, и это контракт:
state | Вкладка | Правило |
|---|---|---|
published | Nashr etilgan | published_at не null и visibility не private |
draft | Qoralamalar | published_at равен null |
archived | Arxivdagilar | published_at не null и visibility = private |
Правила точны, потому что published_at ставится один раз (при первой
публикации готового видео) и больше не сбрасывается: опубликованное однажды
видео черновиком уже не станет. Отдельного состояния «в архиве» нет.
Заархивировать — PATCH /videos/{id} с {"visibility": "private"}.
Восстановить — PATCH с public или unlisted, и выбирает владелец:
прежняя видимость не хранится, и угадывать public значило бы открыть
всем видео, которое было доступно только по ссылке.
Поиск q режется на слова по пробелам (первые восемь); видео подходит,
если каждое слово нашлось подстрокой без учёта регистра в названии или
описании. % и _ ищутся буквально. Пустой q — без поиска.
Сортировка. title — без учёта регистра. При sort=published_at
черновики (без даты) идут последними в обе стороны. При равных значениях
порядок решает время создания в том же направлении. Курсор помнит sort
и order; меняете любой из них или фильтры — начинайте список заново.
GET /videos/my/counts отвечает {"published": 12, "draft": 3, "archived": 1}
одним запросом. Принимает те же q, status, visibility, kind и category, что и список
(state, sort и order ему не нужны), поэтому при поиске показывает
число совпадений на каждой вкладке. Первая страница плюс счётчики — два
запроса, сколько бы видео ни было на канале.
Воспроизведение
GET /videos/{id}/playback возвращает один из двух вариантов:
{ "hls_url": "/videos/<id>/hls/master.m3u8" }
{ "source_url": "https://s3...", "expires_in": 3600 }
Первый — готовое видео. Второй отдаётся только владельцу и только пока
транскодинг не закончен, чтобы автор мог проверить загрузку сразу. Остальным
до готовности приходит 409.
Манифест и сегменты идут через API, а не по presigned-ссылкам: пути внутри манифеста относительные, и подписать их по отдельности плеер не умеет. Поэтому каждый запрос сегмента проверяет видимость видео — и требует токен, если видео не публичное.
Как подключать плеер
// hls.js предпочтительнее нативного HLS везде, где поддерживается.
// Проверять canPlayType первым нельзя: Chromium отвечает "maybe",
// хотя HLS не играет, и вы уйдёте на путь без токена.
if (Hls.isSupported()) {
const hls = new Hls({
xhrSetup: (xhr) => xhr.setRequestHeader("Authorization", `Bearer ${token}`),
});
hls.loadSource(playback.hls_url);
hls.attachMedia(video);
} else if (video.canPlayType("application/vnd.apple.mpegurl")) {
video.src = playback.hls_url; // Safari; приватные видео так не откроются
}
Уровни качества берите из события MANIFEST_PARSED (data.levels),
переключение — присваиванием hls.currentLevel (-1 — автовыбор).
Каждая строка #EXT-X-STREAM-INF мастер-плейлиста несёт FRAME-RATE
(частота кадров исходника, три знака после точки, например 25.000): перегон
fps не меняет, так что у всех ступеней она одна. hls.js кладёт её в
level.frameRate, и длина кадра для покадрового шага — это 1 / frameRate.
У видео, перегнанных до появления атрибута, его нет, и у файлов, для которых
ffprobe не назвал частоту, тоже; тогда берите запасное значение.
Обработчик ERROR обязан считать попытки восстановления: и startLoad(),
и recoverMediaError() заново тянут сегменты, а на битом файле ошибка
повторяется мгновенно — без счётчика плеер уходит в бесконечный цикл
запросов к серверу.
Превью
thumbnail_url — это путь API (/videos/{id}/thumbnail), а не ссылка на
хранилище. Берите его целиком, не собирайте сами: у приватного видео он
бывает подписан.
Тег <img> не умеет отправлять Authorization, а превью приватного
видео отдаётся только владельцу. Поэтому владельцу (в GET /videos/my,
в GET /videos/{id} и в ответах на собственные POST/PATCH над видео,
в содержимом и обложках плейлистов) thumbnail_url приватного видео
приходит подписанным:
/videos/dQw4w9WgXcQ/thumbnail?exp=1790000000&sig=Zk9v...
Такая ссылка открывается без токена, обычным <img src>, с любого
origin. sig — HMAC-SHA256 над коротким id видео и exp (unix-время,
секунды); ключ выводится из JWT__SECRET, так что его смена отзывает
и выданные ссылки. Живёт ссылка 15–20 минут: exp округлён до пяти минут,
и пять минут подряд ссылка одна и та же, поэтому браузер не качает картинку
заново при каждом обновлении списка. После exp, с подделанным sig или
exp, или с подписью другого видео приватное превью без токена — 404,
как и без подписи. Истёкшую ссылку обновляет повторный запрос списка
или карточки.
Публичным и доступным по ссылке видео подпись не нужна, и их
thumbnail_url остаётся голым путём. Ответ на превью всегда
Cache-Control: private, max-age=300 и X-Content-Type-Options: nosniff.
Выбор превью
thumbnail_url всегда ведёт на выбранное превью, и это то же поле, что
и раньше: показывающим превью клиентам о выборе знать не нужно. После выбора
в ссылке появляется ?v=<метка> (?v=t50, ?v=custom-…): сервер её не
читает, она лишь меняет адрес, чтобы браузер не показывал пять минут
закэшированное старое превью. У auto метки нет.
Варианты (thumbnail_id):
auto— кадр на 10% длительности, который воркер снимал всегда. Он показывается, пока владелец ничего не выбрал;t25,t50,t75— кадры на 25, 50 и 75% длительности. Воркер снимает их при транскодинге; у видео, перегнанных до их появления, кандидатов нет, пока видео не перегнать (POST /videos/{id}/retranscode);custom— своя картинка владельца.
GET /videos/{id}/thumbnails (владелец) перечисляет только существующие
варианты, в этом порядке:
[
{ "id": "auto", "url": "/videos/dQw4w9WgXcQ/thumbnails/auto?exp=…&sig=…", "selected": false },
{ "id": "t25", "url": "/videos/dQw4w9WgXcQ/thumbnails/t25?exp=…&sig=…", "selected": false },
{ "id": "t50", "url": "/videos/dQw4w9WgXcQ/thumbnails/t50?exp=…&sig=…", "selected": true },
{ "id": "t75", "url": "/videos/dQw4w9WgXcQ/thumbnails/t75?exp=…&sig=…", "selected": false },
{
"id": "custom",
"url": "/videos/dQw4w9WgXcQ/thumbnails/custom?v=custom-…&exp=…&sig=…",
"selected": false
}
]
url каждого варианта подписан так же, как thumbnail_url (см. «Превью»), и
открывается в <img> без токена при любой видимости видео: варианты видит
только владелец. Без подписи GET /videos/{id}/thumbnails/{t} отдаёт вариант
лишь по токену владельца, остальным — 404.
Выбор — PATCH /videos/{id} с {"thumbnail_id": "t50"}, ответ — Video.
Несуществующий вариант (кандидат, который воркер не снял, или custom без
загруженной картинки) — 409, и остальные поля того же запроса не
применяются; неизвестное значение — ошибка разбора тела. Перегон видео
сохраняет выбор, кроме случая, когда выбранный кадр-кандидат не удалось
снять заново: тогда превью возвращается к auto.
Своя картинка загружается как видео, мимо API:
POST /videos/{id}/thumbnail/upload→{"upload_url": "...", "expires_in": 900, "max_bytes": 2097152};PUT upload_urlс телом картинки (JPEG, PNG или WebP, не больше 2 МБ);POST /videos/{id}/thumbnail/complete→Video, гдеthumbnail_urlуже ведёт на новую картинку, аthumbnail_idвыбранcustom.
/complete проверяет сам файл в хранилище, а не то, что о нём сказал клиент:
размер — по HEAD, формат — по первым байтам. Файл больше 2 МБ или не JPEG,
PNG и WebP — 400, и он удаляется; файла нет — 409. Тип ответа превью
определяется по тем же байтам, Content-Type из PUT значения не имеет.
Загружать можно в любом статусе видео, в том числе пока оно в обработке.
Повторная загрузка заменяет прежнюю картинку.
Субтитры
Субтитры загружает автор видео: файл WebVTT, одна дорожка на язык.
Распознавания речи нет, и воркер субтитров не создаёт, поэтому auto
всегда false. В мастер-плейлист HLS дорожки не попадают
(#EXT-X-MEDIA:TYPE=SUBTITLES нет): клиент подключает их сам, элементом
<track>, а не через hls.js.
Какие дорожки есть
GET /videos/{id} (VideoDetail) несёт captions всегда, даже пустым
списком: [] — честный ответ «субтитров нет», и меню плеера по нему
прячет строку «Субтитры». Дорожки идут в порядке lang.
"captions": [
{
"lang": "uz",
"label": "Oʻzbekcha",
"url": "/videos/kBeaJSmGT7c/captions/uz.vtt?v=3f2a…",
"kind": "subtitles",
"auto": false
}
]
В лентах, поиске, списках и ответах на POST/PATCH над видео поля
captions нет: оно стоило бы ещё одного запроса к базе на каждую страницу
ради меню, которое открывают только в плеере. Список дорожек берите из
карточки, которую плеер и так запрашивает.
label — то, что автор прислал при загрузке, а если не прислал —
самоназвание языка: uz → «Oʻzbekcha», uz-Cyrl → «Ўзбекча»,
ru → «Русский», en → «English». Для остальных языков подпись по
умолчанию — сам тег (de), так что для них автору стоит прислать свою.
Как подключать
url — путь этого API, как thumbnail_url и hls_url, а не ссылка на
хранилище. Пропускайте его через тот же резолвер медиа-путей, что и
thumbnail_url (MediaUrlResolver / resolveMedia из
@tes-tube/core/wire): в браузере он даёт путь того же origin с
префиксом /v1, на сервере — абсолютный адрес API. Сами адрес не
собирайте: у приватного видео он подписан, а ?v= меняется с каждой
загрузкой.
<video>
<track
kind="subtitles"
src="/v1/videos/kBeaJSmGT7c/captions/uz.vtt?v=3f2a…"
srclang="uz"
label="Oʻzbekcha"
/>
</video>
GET /videos/{id}/captions/{lang}.vtt отдаёт файл с
Content-Type: text/vtt; charset=utf-8, X-Content-Type-Options: nosniff
и Cache-Control: private, max-age=300, как сегменты HLS. Файл идёт через
API, а не по presigned-ссылке, и каждый запрос проверяет видимость видео
так же, как GET /videos/{id}/hls/{path}: приватное видео без токена
владельца — 404, а не 403. Нет такой дорожки или путь без .vtt —
тоже 404. v сервер не читает: он лишь меняет адрес после новой
загрузки, чтобы браузер не держал пять минут прежний файл.
<track>, как и <img>, не умеет приложить Authorization. Поэтому
владельцу приватного видео url приходит подписанным, той же подписью,
что thumbnail_url (см. «Превью»): …/uz.vtt?v=…&exp=…&sig=… открывается
без токена 15–20 минут, потом карточку нужно запросить заново. Публичным
и доступным по ссылке видео подпись не нужна. <track> с другого origin
браузер грузит только с атрибутом crossorigin на <video>; веб ходит в
API тем же origin (/v1/), и там это не нужно.
Загрузка
Как у своего превью: ссылка, файл прямо в хранилище, подтверждение.
// 1. Ссылка для загрузки. Тело необязательно; без label подпись — самоназвание языка.
const { upload_url, expires_in, max_bytes } = await post(`/videos/${id}/captions/uz-Cyrl`, {
label: "Ўзбекча (кирилл)",
});
// 2. Файл прямо в хранилище, без заголовка Authorization.
await fetch(upload_url, { method: "PUT", body: file });
// 3. Подтверждение: API проверяет файл и отдаёт CaptionTrack.
const track = await post(`/videos/${id}/captions/uz-Cyrl/complete`);
lang— подмножество BCP 47: язык из 2–3 латинских букв, затем необязательные письменность (4 буквы) и регион (2 буквы или 3 цифры):uz,uz-Cyrl,en-US,es-419. Регистр приводится к каноническому, так чтоUZ-cyrlиuz-Cyrl— одна дорожка, и в ответе всегдаuz-Cyrl. Другой тег —400.label— до 50 символов, одна строка; пустая строка — то же, что отсутствие поля./completeпроверяет сам файл в хранилище, а не то, что о нём сказал клиент: не пустой, не больше 512 КБ (max_bytes), целиком UTF-8 (метка BOM в начале допустима) и начинается сWEBVTT. Не прошёл —400, файл удаляется, прежняя дорожка этого языка остаётся на месте. SRT не принимается: переведите его в WebVTT на клиенте./completeбез начатой загрузки или до того, как файл лёг в хранилище, —409. Подтвердить можно только последнюю ссылку на этот язык: новая отменяет прежнюю.- Повторная загрузка на тот же язык заменяет дорожку: новый
url(другойv), прежний файл удаляется, подпись — та, что прислана в последний раз. - Неподтверждённый файл живёт сутки (
WORKER__ABANDONED_UPLOAD_SECS) с момента загрузки, потом воркер его удаляет, как и неподтверждённые картинки канала./completeпосле этого —409. - У видео не больше 20 языков (опубликованных и начатых вместе); загрузка
двадцать первого —
409. - Загружать можно в любом статусе видео, в том числе пока оно в обработке.
- Чужому видео все три роута отвечают
404, при любой его видимости.
DELETE /videos/{id}/captions/{lang} снимает дорожку и её файл, а заодно
начатую на этот язык загрузку; ответ — 204, а если не было ни того,
ни другого — 404. Удаление видео удаляет и все его субтитры.
Реакции
| Метод | Путь | Тело | Ответ |
|---|---|---|---|
| PUT | /videos/{id}/reaction | {"reaction": "like"} | счётчики |
| DELETE | /videos/{id}/reaction | — | счётчики |
| GET | /videos/{id}/reaction | — | счётчики и свой голос |
{ "likes": 12, "dislikes": 1, "my_reaction": "like" }
Реакция у пользователя одна: PUT с другим значением переносит голос, а не
добавляет второй. Все три ручки требуют токен. Счётчики в карточке видео
(like_count, dislike_count) обновляются той же транзакцией, так что после
ответа можно просто перерисовать число из него.
Комментарии
| Метод | Путь | Доступ |
|---|---|---|
| GET | /videos/{id}/comments | по видимости, курсор |
| POST | /videos/{id}/comments | токен, тело {"body": "...", "parent_id": null} |
| GET | /comments/{id}/replies | по видимости, курсор |
| PATCH | /comments/{id} | только автор |
| DELETE | /comments/{id} | автор или владелец видео |
| PUT | /comments/{id}/like | токен |
| DELETE | /comments/{id}/like | токен |
| PUT | /comments/{id}/dislike | токен, ответ 204 |
| DELETE | /comments/{id}/dislike | токен, ответ 204 |
| GET | /me/comments | токен, только свои видео, курсор |
Длина текста — 1–10 000 символов после обрезки пробелов. Владелец видео может
удалять чужие комментарии под своим роликом, но не править их. Правка
проставляет edited_at — по нему и рисуется метка «изменено»; updated_at
для этого не годится, его двигают и служебные пересчёты счётчиков.
Ответы двухуровневые, как в макете: корень, ответ на него и ответ на
ответ. GET /videos/{id}/comments отдаёт только верхний уровень с
reply_count у каждого. GET /comments/{id}/replies отдаёт прямые ответы на
комментарий {id}, старые сверху (ветку читают как разговор), с тем же
курсором, что и везде; {id} может быть и корнем, и ответом. Ответы на ответ
в выдачу корня не попадают: их разворачивают тем же запросом с id ответа.
reply_count есть у каждого комментария и считает только прямые ответы,
ровно столько вернёт /comments/{id}/replies. У ответа он показывает, нужен
ли переключатель «N ta javob» под ним; у ответа второго уровня он всегда 0.
Число всего обсуждения под плеером — comment_count видео, оно считает все
уровни.
parent_id в POST указывает на корень или на ответ первого уровня этого же
видео. Ответ на ответ второго уровня — 400 (третьего уровня нет), чужой или
несуществующий родитель — 404. Удаление комментария уносит все ответы под
ним на любой глубине; reply_count его родителя и comment_count видео
пересчитываются той же транзакцией.
?sort=top сортирует верхний уровень по лайкам вместо свежести.
Лайки и дизлайки устроены как реакция на видео: у зрителя на комментарий
один голос. PUT .../dislike снимает его лайк, PUT .../like снимает его
дизлайк. DELETE снимает только названную реакцию: DELETE .../like не
трогает дизлайк, и наоборот. Все четыре ручки идемпотентны: повторное
нажатие не удваивает счётчик, снять то, чего нет, тоже успех. Голосовать
можно за то, что видно: комментарий под чужим приватным видео даёт 404.
Дизлайк отвечает 204 без тела. Лайк по-прежнему отвечает 200 с телом
{"like_count", "dislike_count", "my_reaction", "liked_by_me"}: два
последних поля добавлены, потому что лайк теперь двигает оба числа.
Перерисовать строку можно и из него, и из следующего чтения ленты.
У каждого Comment (лента, ветка ответов, ответ на POST и PATCH,
/me/comments) есть like_count, dislike_count и my_reaction. Оба
счётчика публичны и приходят и анониму, потому что макет рисует число на
пилюле дизлайка. Продакт может позже решить скрыть число дизлайков, как
YouTube; тогда пропадёт dislike_count, а пара ручек останется. О дизлайке
автору не сообщают, уведомлений о голосах нет вовсе.
my_reaction показывает собственный голос: "like", "dislike" или null. У
анонима он всегда null. liked_by_me оставлен ради совместимости и
выводится из my_reaction: true при "like", false при "dislike" и
без голоса, null у анонима. Новый код читает my_reaction. Ответы на
PATCH собирают комментарий без зрителя, поэтому там оба поля null.
Комментарий под чужим видео создаёт уведомление владельцу, ответ — автору того комментария, на который ответили (корня или ответа). Себе уведомления не приходят.
Комментарии канала
GET /me/comments — одна лента комментариев под всеми видео вызывающего,
любой видимости (public, unlisted, private), для страницы комментариев
в студии. Комментариев под чужими видео в ней нет, даже своих.
| Параметр | Значение |
|---|---|
video_id | публичный id одного своего видео; чужое или несуществующее — [] |
q | подстрока текста, логина или имени автора, без учёта регистра |
sort | newest (по умолчанию) или top — по лайкам |
scope | roots (по умолчанию) — только верхний уровень; all — и ответы |
cursor | как везде; курсор от другой sort — 400 |
limit | 1–100, по умолчанию 20 |
q ищет буквально: % и _ в нём — обычные символы, а не шаблон. Пустой
q фильтром не считается. Неизвестное значение sort или scope, как и
нечисловой limit, дают 400.
Элемент — обычный Comment и ещё два поля:
interface MyComment extends Comment {
video: {
id: string; // публичный id, тот же, что в Comment.video_id
title: string;
thumbnail_url: string | null;
visibility: "public" | "unlisted" | "private";
};
replied_by_owner: boolean;
}
replied_by_owner — владелец канала ответил прямо на этот комментарий. У
корня засчитывается и ответ владельца на любой ответ в его ветке; у ответа
любого уровня — и реплика владельца рядом с ним, у того же родителя, но позже
него. my_reaction и liked_by_me здесь показывают голос самого владельца.
Каналы и подписки
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| GET | /channels/{id} | все | Карточка канала |
| GET | /channels/by-username/{username} | все | Она же по имени из ссылки |
| GET | /channels/{id}/videos | все | Публичные видео, sort, kind |
| PATCH | /me/channel | токен | Правка своего профиля |
| POST | /me/channel/avatar | токен | Ссылка для загрузки |
| POST | /me/channel/avatar/complete | токен | Подтвердить загрузку |
| POST | /me/channel/banner | токен | Ссылка для загрузки |
| POST | /me/channel/banner/complete | токен | Подтвердить загрузку |
| GET | /channels/{id}/avatar | все | Аватар (картинка) |
| GET | /channels/{id}/banner | все | Баннер (картинка) |
| GET | /link-icons/{hash} | все | Значок сайта из ссылки канала |
| GET | /me/profile | токен | Свои личные данные |
| PATCH | /me/profile | токен | Правка личных данных |
| PUT | /channels/{id}/subscription | токен | Подписаться / колокольчик |
| DELETE | /channels/{id}/subscription | токен | Отписаться |
| GET | /subscriptions | токен | Мои подписки, offset |
| GET | /feed | токен | Лента подписок, курсор |
Идентификатор канала — это channel.id из карточки видео. Адресовать канал
можно и по имени: /channels/by-username/neo или /channels/by-username/@neo
— ведущая @ принимается, регистр не важен.
Подписка и отписка идемпотентны: повтор возвращает тот же 204. Подписка
на себя — 400, на несуществующий канал — 404. Тело PUT необязательно;
{"notifications_enabled": false} оставляет подписку, но выключает
уведомления о новых видео. Тем же запросом колокольчик и переключают.
Строки GET /subscriptions — те же карточки Channel, что у
GET /channels/{id}: subscribed в них всегда true, а
notifications_enabled — настоящее состояние колокольчика. Перечитывать
каждый канал ради него не нужно.
{
"items": [{ "id": "...", "username": "neo", "subscribed": true, "notifications_enabled": false }],
"limit": 20,
"offset": 0
}
Видео канала: сортировка
GET /channels/{id}/videos?sort=most_viewed&limit=20
Это лента GET /videos, суженная до одного канала, с теми же значениями
sort и той же семантикой: newest (по умолчанию), oldest, most_viewed,
trending. Чипы вкладки «Видео» — «Eng yangi», «Mashxur», «Eng eski» — это
newest, most_viewed и oldest. Неизвестное значение — 400. Курсор
привязан к сортировке, под которой выдан: смена sort без сброса cursor
даёт 400 (см. «Пагинация»). Отдельного фильтра channel_id у /videos
нет: ссылка «видео канала» живёт здесь. kind и category работают так же,
как у /videos.
Правка профиля
PATCH /me/channel
{
"display_name": "Нео",
"description": "про матрицу",
"about": "длинный текст вкладки «о канале»",
"avatar_url": "https://...",
"banner_url": null,
"country": "UZ",
"links": [{"label": "Сайт", "display": "example.com", "url": "https://example.com"}]
}
Все поля необязательны. Отсутствие поля означает «не трогать», явный null —
«очистить»; строка из одних пробелов равносильна null. links заменяется
целиком (до 10 штук). Адрес ссылки принимается только со схемой http://,
https:// или mailto: — он уходит в href на клиенте, и javascript:
там был бы XSS. icon_url в ссылках запроса пропускается молча: значок
выводит сервер из адреса (см. «Значки ссылок»). Отказ 400 сломал бы
клиента, который отправляет назад ссылки ровно в том виде, в каком их
прочитал, вместе с icon_url.
Значения нормализуются при записи и читаются уже нормализованными:
country приводится к верхнему регистру ("uz" → "UZ"), а label,
display и url каждой ссылки обрезаются по краям (" Sayt " →
"Sayt").
avatar_url и banner_url, записанные руками, принимаются только как
https://... без пробелов, не длиннее 2000 символов и только на хосте из
списка разрешённых (настройка сервера APP__MEDIA__AVATAR_HOSTS, точное
совпадение имени). Иначе — 400: data:, javascript:, http: и любой
другой хост. По умолчанию список пуст, то есть внешний адрес не
принимается никакой, и картинку нужно загрузить. Причина: картинку со
стороннего хоста каждый зритель запрашивает сам, и владелец хоста видит
адрес, браузер и время каждого, кому показали комментарий или
уведомление с этим аватаром. Правило проверяет только новые адреса.
Записанные до него ссылки https:// сохранены на любом хосте и
приходят как есть; прочие (javascript:, data:, http:) обнулены
миграцией и приходят как null. Сохранённая ссылка, присланная назад
без изменений вместе с остальной формой, означает «не трогать» и 400
не вызывает. Путь этого API (/channels/...) руками не записать: его ставит
только загрузка (см. ниже), и любой путь, кроме текущего, — 400. Текущее
значение, отправленное назад вместе с остальной формой, означает «не
трогать». Любая другая запись (новый адрес или null) отвязывает
загруженную картинку, и её файл удаляется.
username не меняется вовсе: он адресует канал, и смена сломала бы все
ссылки @username. Тело с ключом username (с любым значением, в том числе
null) отвергается целиком: 400 {"error": "...username нельзя изменить..."},
и остальные поля этого запроса тоже не применяются. Остальные незнакомые
ключи по-прежнему молча пропускаются: отвергать их все значило бы ломать
клиентов, которые шлют форму с лишними безвредными полями, а тихий 200
опасен только для username, который клиент мог бы счесть сохранённым.
Ответ — та же карточка канала, что и у GET /channels/{id}.
Личные данные
GET /me/profile (токен)
-> 200 {"first_name": "Aziz", "last_name": null, "phone": "+998901234567", "email": "aziz@example.com"}
PATCH /me/profile (токен)
{"first_name": "Aziz", "last_name": "Karimov", "phone": "+998901234567"}
-> 200 тот же объект
Имя, фамилия и телефон — данные человека, а не канала: их отдаёт только
/me/profile и только владельцу токена. Ни карточка канала, ни
/auth/me, ни комментарии, ни любая другая ручка их не содержат.
- Отсутствие поля — «не трогать»,
null— «очистить», как уPATCH /me/channel. first_nameиlast_name— от 1 до 60 символов после обрезки пробелов; хранятся обрезанными. Строка из одних пробелов —400, а не очистка: очищаютnull-ом.phone— в формате E.164:+, код страны без ведущего нуля, всего от 7 до 15 цифр, без пробелов, скобок и дефисов (+998901234567). Маску ввода снимает клиент. Иначе —400.emailтолько для показа: этим запросом он не меняется, ключemailв телеPATCHпропускается. Меняют его кодом из письма, см. ниже.
Смена email
POST /me/email (токен)
{"email": "new@example.com"}
-> 202 (тело пустое)
-> 409 {"error": "..."} адрес уже занят другим аккаунтом
POST /me/email/confirm (токен)
{"code": "04217"}
-> 200 User (новый email, "email_verified": true)
-> 400 {"error": "..."} неверный, просроченный или сожжённый код
-> 409 {"error": "..."} адрес успели занять, пока шёл код
- Код уходит на новый адрес; до
confirmаккаунт живёт со старым, и входить нужно по нему. - Адрес нормализуется, как при регистрации: пробелы по краям срезаются,
регистр приводится к нижнему. Негодный адрес или тот же, что сейчас, —
400. - Занятость проверяется дважды: при запросе кода (
409сразу) и при подтверждении (409, если адрес заняли за эти 10 минут; адрес тогда остаётся прежним). - Пауза в 72 секунды ставится на пользователя, а не на адрес: запросить код на другой адрес раньше тоже нельзя. Новый запрос заменяет прежний код, даже если адрес другой.
- После смены
email_verified—true: код дошёл до нового ящика. Входить дальше — по новому адресу. Сессии не гасятся. - Без почты (
MAIL__TRANSPORT=none)POST /me/emailотвечает503.
Аватар и баннер
Загрузка устроена как у видео: ссылка, файл прямо в хранилище, подтверждение.
// 1. Ссылка для загрузки. Для баннера — /me/channel/banner.
const { upload_url, expires_in } = await post("/me/channel/avatar");
// 2. Файл прямо в хранилище, без заголовка Authorization.
await fetch(upload_url, { method: "PUT", body: file });
// 3. Подтверждение: API проверяет файл и отдаёт карточку канала.
const channel = await post("/me/channel/avatar/complete");
// channel.avatar_url === "/channels/<id>/avatar?v=<версия>"
- Аватар — не больше 4 МБ, баннер — не больше 6 МБ (макет советует
2048x1152). Формат — JPEG, PNG или WebP. Проверяет
/complete: размер по хранилищу, формат по первым байтам файла, а не по расширению илиContent-Type. Не прошёл —400, файл удаляется, прежняя картинка остаётся на месте. /completeбез начатой загрузки или до того, как файл лёг в хранилище, —409. Подтвердить можно только последнюю выданную ссылку: новая отменяет прежнюю.- Неподтверждённый файл живёт сутки (
WORKER__ABANDONED_UPLOAD_SECS, 86400 по умолчанию) с момента загрузки, потом воркер его удаляет. Это касается и файла, положенного по уже отменённой ссылке./completeпосле этого —409, загрузку нужно начать заново. - После подтверждения
avatar_url(banner_url) — путь этого API, какthumbnail_urlу видео; он же приезжает вauthor_avatar_urlкомментариев,actor_avatar_urlуведомлений иowner_avatar_urlплейлистов. Картинка канала публична, поэтому<img>без токена её показывает. vв адресе меняется с каждой загрузкой. Адрес с текущейvотдаётся сCache-Control: public, max-age=31536000, immutable, без неё или со старой — сmax-age=300. Прежний файл после новой загрузки удаляется.- Убрать картинку —
PATCH /me/channel {"avatar_url": null}.
Значки ссылок
У каждой ссылки канала есть icon_url: значок сайта, на который она
ведёт. Он приходит везде, где приходят ссылки: GET /channels/{id},
GET /channels/by-username/{username}, GET /subscriptions, ответы
PATCH /me/channel и /me/channel/{avatar,banner}/complete.
"links": [
{ "label": "Instagram", "display": "@eslcs", "url": "https://instagram.com/eslcs",
"icon_url": "/link-icons/5b1f0c6c…e2" },
{ "label": "Gmail", "display": "eslcs@gmail.com", "url": "mailto:eslcs@gmail.com",
"icon_url": null }
]
icon_urlэто путь этого API, какthumbnail_urlу видео, а не ссылка на сайт или на хранилище. Разрешайте его тем же способом, что иthumbnail_url(в браузере это тот же origin с префиксом/v1), и берите целиком, не собирайте сами.nullзначит, что значка нет: рисуйте общий знак ссылки. Так бывает уmailto:, у адреса с IP вместо имени хоста, пока значок ещё не скачан и когда скачать его не удалось.- Значок качает сервер, один раз на хост, и хранит в нашем бакете.
Браузер зрителя на сайт из ссылки не ходит никогда: иначе владелец
сайта видел бы адрес, браузер и время каждого, кто открыл вкладку
«О канале» (та же причина, по которой внешние
avatar_urlне принимаются). Сторонних сервисов значков API тоже не зовёт. - Значок появляется не сразу.
PATCH /me/channelтолько ставит хост в очередь, и в ответе на негоicon_urlновой ссылки обычноnull. Воркер обходит очередь раз в минуту (WORKER__MAINTENANCE_INTERVAL_SECS), так что перечитайте карточку позже. Не удалось: повтор через 15 минут, час и четыре часа; после четвёртой неудачи хост остаётся без значка. - Один хост, один значок:
instagram.com/aиinstagram.com/bделят его, аwww.instagram.comэто другой хост. Регистр и порт не важны. - Владелец значок не задаёт:
icon_urlвPATCH /me/channelпропускается. Своей загрузки значка для ссылки нет.
Как сервер ищет значок: https://{host}/favicon.ico, а если его нет, то
первый <link rel="icon">, rel="shortcut icon" или
rel="apple-touch-icon" с главной страницы https://{host}/. Ходит он
только по https, только на порт 443, только на сам хост или его поддомен,
не дальше трёх перенаправлений и не дольше 5 секунд на хост; адрес,
который резолвится во внутреннюю сеть (loopback, частные сети, link-local,
CGNAT и прочее не глобальное), отвергается до соединения. Файл больше
256 КБ не принимается. Принимаются PNG, ICO, JPEG, GIF и WebP, формат
определяется по первым байтам; SVG не принимается никогда: внутри него
бывает скрипт.
GET /link-icons/{hash} отдаёт файл без токена, с типом, определённым по
сигнатуре, X-Content-Type-Options: nosniff,
Content-Security-Policy: default-src 'none' и
Cache-Control: public, max-age=31536000, immutable: значок хоста
скачивается один раз и больше не меняется. Хэш, которого нет, или значок,
который ещё не скачан, дают 404.
Поиск
GET /videos/search?q=прогулка+по+городу&limit=20&offset=0
Ищет по заголовку и описанию публичных готовых видео; заголовок весит больше.
Запрос разбирается как в поисковике: кавычки задают точную фразу, -слово
исключает. Пустой q — 400. Результаты отсортированы по релевантности,
затем по свежести.
Фильтры поиска
GET /videos/search?q=bozor&category=music&kind=short&watched=false&limit=20&offset=0
Все четыре параметра необязательны, складываются через «И» и сочетаются с q,
limit и offset. Они только сужают выдачу: порядок остаётся тем же,
по релевантности.
| параметр | значения | что делает |
|---|---|---|
category | слаг из GET /categories | как GET /videos?category=: чипы категорий |
tag | один тег | как GET /videos?tag=: свободный тег автора |
kind | regular, short, live | как GET /videos?kind=, см. «Род видео» |
watched | true, false | есть ли видео в истории зрителя; нужен токен |
categoryиtagразбираются так же, как в ленте: пробелы по краям срезаются, пустое значение значит «без фильтра». Неизвестная категория отвечает400, неизвестный тег просто ничего не находит.kindберёт словарь самого API:regular,short,live. Значенияvideoнет, обычное видео называетсяregular. Неизвестное значение отвечает400, как у/videos. Отсутствие параметра значит «любые».watched=trueоставляет видео, у которых есть запись в истории просмотров зрителя (чип Ko'rilgan),watched=falseоставляет те, у которых её нет (Ko'rilmagan). Досмотрено ли видео до конца, не важно: в историю оно попадает с первой отправленной позиции.watchedбез токена отвечает401: без зрителя не у кого спросить историю, а молча отдать нефильтрованную выдачу значило бы показать гостю «непросмотренное», которое им не является. Гостю чипы Ko'rilgan и Ko'rilmagan рисовать не нужно. Любое значение, кромеtrueиfalse(в том числе1,yesи пустое), отвечает400.
Какой ряд чипов на /results канонический (категории на 1920 или
род и история на 430), решает продукт; API отдаёт оба.
Подсказки (/videos/search/suggest) этих фильтров не принимают: они
дополняют строку ввода, а чипы относятся к уже найденной выдаче.
Подсказки
GET /videos/search/suggest?q=биз&limit=8
{ "suggestions": ["Ermak Biznes segodnya", "Biznes s nulya"] }
Отдаёт строки, а не видео: подсказка заполняет строку ввода, и вычитывать
заголовки из полного ответа /videos/search, чтобы получить восемь строк, —
это обход, а не решение. Не вызывайте ради подсказок /videos/search.
- Источники — заголовки публичных готовых видео и их теги. Совпадение по
началу слова:
бизпредложит «Ermak Biznes»,изнне предложит ничего. - Регистр не важен. Спецсимволы (
%,_) — обычные буквы запроса. - Порядок: сначала популярность (просмотры у заголовков, частота у тегов), при равенстве — алфавит.
limit1–20, по умолчанию 8.- Пустой
q— это200с пустым списком, а не400, в отличие от/videos/search. Только что открытая панель подсказок — обычное состояние, и подменять этот случай запросом к ленте клиенту не нужно.
Чего ручка не делает: она не знает, что люди ищут, и не предложит слово, которого никто не опубликовал. Для этого нужен журнал запросов, а он упирается в решения о сроке хранения и о том, записывать ли запросы анонимов.
История просмотров
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| PUT | /videos/{id}/progress | токен | Сохранить позицию |
| GET | /videos/{id}/progress | токен | Где остановились |
| GET | /me/history | токен | История, q |
| DELETE | /me/history/{id} | токен | Убрать одно видео |
| DELETE | /me/history | токен | Очистить целиком |
PUT /videos/dQw4w9WgXcQ/progress
{"position_secs": 42.5, "watched_delta_secs": 10, "completed": false}
watched_delta_secs — приращение с прошлого отчёта, а не «сколько всего»:
суммарного времени клиент не знает, смотреть могли и с другого устройства.
Отправляйте отчёт раз в 10 секунд воспроизведения, а не на каждый тик.
Один отчёт засчитывает не больше 21 600 секунд (6 часов): больше API не
отвергает, а урезает, и отвечает 200. Так отчёт, накопивший секунды после
обрыва сети, не застревает на 400. Отрицательное приращение по-прежнему
400. Сумма watched_secs одной строки истории не растёт выше 1e9 секунд.
completed только взводится: досмотрев ролик и перемотав назад, зритель
не делает его недосмотренным. Порог «досмотрено» решает клиент — он знает
и длительность, и то, что для тридцатисекундного ролика и двухчасового фильма
это разный запас.
GET /videos/{id}/progress отвечает 404, если это видео ещё не смотрели:
«нечего возобновлять» — отсутствие записи, а не нулевой прогресс, который
пришлось бы отличать от настоящего нуля.
Строка /me/history — это карточка видео плюс поле progress:
{
"id": "dQw4w9WgXcQ",
"title": "...",
"channel": {},
"progress": {
"position_secs": 42.5,
"watched_secs": 60,
"completed": false,
"last_watched_at": "2026-09-07T10:00:00Z"
}
}
Удалённые и ставшие приватными чужие видео из истории выпадают сами.
Поиск по истории
GET /me/history?q=bozor&limit=20
q ищет по всей истории, а не по загруженным страницам: фильтр на клиенте
говорил бы «ничего нет», пока совпадение лежит на следующей странице.
Строка режется на слова по пробелам (берутся первые восемь), и запись
подходит, если каждое слово нашлось подстрокой без учёта регистра
в названии видео или в имени канала (channel.display_name). Это не
полнотекстовый поиск /videos/search: тот стеммит по-русски и не находит
узбекское слово по его части. % и _ ищутся буквально. Пустой или
пробельный q — вся история, как без параметра. Порядок (недавние сверху),
конверт и правила курсора те же; меняете q — начинайте список заново.
Смотреть позже и понравившееся
Два системных списка зрителя. Оба приватные, оба страницами по курсору, и оба отдают ту же карточку видео, что и лента, — свой маппер писать не нужно.
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| GET | /me/watch-later | токен | Список, курсор |
| GET | /me/watch-later/{id} | токен | Есть ли: 204 / 404 |
| PUT | /me/watch-later/{id} | токен | Положить наверх, идемпотентно |
| PUT | /me/watch-later/{id}/position | токен | Переставить |
| DELETE | /me/watch-later/{id} | токен | Убрать одно видео |
| DELETE | /me/watch-later | токен | Очистить целиком |
| GET | /me/liked | токен | Что лайкнул, курсор |
Это не плейлисты. У них нет названия, описания и видимости, их нельзя
переименовать или удалить, и в GET /playlists они не появляются. Не
изобретайте вместо них приватный плейлист с зарезервированным названием:
зритель увидит его в своём списке и в панели «сохранить в плейлист» и сможет
удалить из-под функции, а название придётся либо показывать как внутренний
токен, либо переводить на четыре локали.
Замечания:
PUTкладёт видео наверх списка. Он возвращает204и в том случае, если видео уже в списке. Второй раз оно не добавляется и с места не сдвигается: место выбирает зритель (см. ниже), и «положил ещё раз» не должно отменять его перестановку. Убрал и положил снова — это новое добавление, наверх.DELETEодного видео тоже204, даже если его в списке не было: результат один и тот же, а разбирать гонку двух вкладок клиенту незачем.- Положить чужое приватное видео нельзя —
404, то же правило, по которому оно не видно и в остальных ручках. - Лежит ли видео в списке, можно узнать двумя способами, и листать весь
список ради этого не нужно. В
GET /videos/{id}с токеном естьin_watch_later: true | false(без токенаnull); это поле только у этой карточки, в лентах, поиске и списках его нет. Если карточка уже на руках,GET /me/watch-later/{id}отвечает204, когда видео в списке, и404, когда нет (с обычным телом ошибки); смотрите только на статус.404же и на видео, которого зритель не видит. Панель «сохранить» берёт отсюда галочку первой строки, какGET /videos/{id}/playlistsдаёт галочки плейлистов. /me/liked— обратная сторонаGET /videos/{id}/reaction, который отвечает про одно видео. Только лайки:?reaction=нет, потому что список дизлайков не запрашивает ни один экран. Смена лайка на дизлайк убирает видео из выдачи — реакция на пару «видео + зритель» одна.- Сортировка разная (#231). «Смотреть позже» идёт в порядке, который задал
зритель; пока он ничего не переставлял, это порядок добавления, недавние
сверху, как и раньше.
/me/likedидёт по моменту реакции, недавние сверху, и переставить его нельзя: это лента событий, а не список, который зритель собирает сам. Ни один из двух не сортируется по дате видео. Значок перетаскивания на строках «Понравившихся» в макете — вопрос дизайна, а не API: эндпоинта для него нет и не будет.
Перестановка в «Смотреть позже»
PUT /me/watch-later/{id}/position
{"position": 0} -> 200 {"position": 0}
position— новое место видео, с нуля, в том списке, который отдаётGET /me/watch-later.0— наверх.- Только целое число.
"top"и"bottom"не принимаются: наверх — это0, а вниз — длина списка минус один или просто любое большое число. Место за пределами списка прижимается к краю (отрицательное к0, слишком большое к последнему), и ответ говорит, куда видео встало на самом деле. Тело другой формы (не число, дробь,null, нет поля, не JSON) —400. 404, если видео нет в списке зрителя, если его нет вообще и если зритель его не видит.- Места считаются по тому, что видит зритель. Чужое видео, которое автор
сделал приватным, остаётся в списке, но в выдаче его нет, и в счёт мест
оно не входит: индекс в ответе совпадает с индексом в
GET /me/watch-later. - Перетаскивание: шлите место, на которое строку бросили, считая в списке
после того, как её оттуда вынули (то есть ровно индекс, под которым она
окажется). Перестановка в соседней вкладке до перезагрузки списка не
видна; ответ
position— тот, по которому ставить строку у себя. - Курсор списка — порядок, а не время. Видео, которые не двигали, своих мест
не меняют, поэтому листание не теряет и не повторяет их, даже если между
страницами что-то переставили; переставленное видео окажется там, куда его
поставили (выше курсора — не придёт, ниже — придёт, возможно второй раз).
Исключение одно и редкое: после трёх десятков перестановок подряд в одно
и то же место сервер перенумеровывает список, и курсор, выданный до этого,
может повторить или пропустить строки. Дубли по
idна клиенте всё равно стоит отбрасывать. Курсор, выданный этим списком до #231, теперь чужой:400, начните заново.
Плейлисты
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| POST | /playlists | токен | Создать |
| GET | /playlists?owner_id= | по видимости | Библиотека, offset |
| GET | /playlists/{id} | по видимости | Карточка |
| PATCH | /playlists/{id} | владелец | Правка |
| DELETE | /playlists/{id} | владелец | Удалить |
| GET | /playlists/{id}/items | по видимости | Содержимое по порядку, offset |
| POST | /playlists/{id}/items | владелец | Добавить видео в конец |
| PUT | /playlists/{id}/items/{video_id} | владелец | Переставить |
| DELETE | /playlists/{id}/items/{video_id} | владелец | Убрать |
| GET | /videos/{id}/playlists | токен | В каких моих плейлистах уже есть |
| GET | /me/saved-playlists | токен | Сохранённые чужие, offset |
| PUT | /me/saved-playlists/{id} | токен | Сохранить чужой, идемпотентно |
| DELETE | /me/saved-playlists/{id} | токен | Убрать из библиотеки |
GET /playlists без owner_id показывает свою библиотеку целиком; с чужим
owner_id — только публичные плейлисты этого канала. Без токена и без
owner_id — 401: чья библиотека, неизвестно.
Повторное добавление того же видео — 409, а не второй экземпляр. Чужое
приватное видео в плейлист не кладётся (404): это был бы обход приватности.
Наоборот тоже: приватные видео не отдаются из чужого публичного плейлиста.
Позиции плотные и считаются с нуля. PUT .../items/{video_id} с
{"position": 0} двигает видео в начало, сдвигая остальных; позиция за
пределами списка прижимается к краю, и ответ говорит, куда видео встало
на самом деле. Удаление подтягивает позиции за собой, дыр не остаётся.
cover_video_id — короткий id первого видео плейлиста, а
cover_thumbnail_url — готовая ссылка на его превью (null, если видео
нет или превью у него ещё нет). Рисуйте обложку из cover_thumbnail_url,
а не собирайте путь из cover_video_id: если обложка — ваше же приватное
видео, ссылка подписана (см. «Превью») и открывается в <img> без токена.
GET /videos/{id}/playlists возвращает массив UUID — это галочки в меню
«сохранить в плейлист».
Сохранённые плейлисты
Чужой плейлист можно сохранить в свою библиотеку, не копируя его: правки
автора видны сразу. GET /me/saved-playlists?limit=&offset= отдаёт те же
карточки Playlist, что и GET /playlists, в том же offset-конверте,
недавно сохранённые сверху. Чтобы собрать библиотеку целиком, склейте его
с GET /playlists: свои плейлисты в сохранённых не появляются.
Автор уже есть в карточке, плоскими полями owner_id, owner_username,
owner_display_name и owner_avatar_url, по тому же соглашению, что и у
автора комментария. Подпись «<канал> · Pleylist» собирайте из них;
вложенного объекта owner нет, чтобы одно и то же не приходило дважды.
GET /playlists/{id} дополнительно отдаёт saved_by_me: boolean | null:
null без токена, false на своём плейлисте. В списках этого поля нет.
Замечания:
PUTвозвращает204и тогда, когда плейлист уже сохранён. Второй раз он не добавляется и наверх не поднимается.- Чужой приватный плейлист и несуществующий дают одинаковый
404, как и вGET /playlists/{id}. Плейлист «по ссылке» сохранить можно: ссылка у зрителя уже есть. - Свой плейлист даёт
400: он и так в вашей библиотеке. Кнопку «Сохранить» на своём плейлисте не показывайте. - Если автор сделал сохранённый плейлист приватным, он пропадает из
/me/saved-playlists, а откроет снова, вернётся сам, без повторного сохранения. Пока он приватный,PUTна него даёт404. DELETEотвечает204всегда: и когда плейлиста в библиотеке не было, и когда он стал приватным или удалён. Плейлист при этом не трогается.- Удаление плейлиста автором убирает его из всех библиотек.
Уведомления
| Метод | Путь | Описание |
|---|---|---|
| GET | /notifications?unread=true | Ящик, курсор |
| GET | /notifications/unread-count | Цифра на колокольчике |
| POST | /notifications/{id}/read | Отметить прочитанным |
| POST | /notifications/read | Отметить прочитанным весь ящик |
| DELETE | /notifications/{id} | Убрать из ящика |
Все требуют токен. Уведомления создаются сами:
new_video— канал из подписок опубликовал видео. Рассылается подписчикам с включённым колокольчиком один раз за жизнь видео, при первом переходе вvisibility = "public"приstatus = "ready", где бы он ни случился:PATCH /videos/{id}на готовом видео или окончание транскодинга видео, которое владелец сделал публичным ещё вprocessing(обычный путь загрузки).unlisted(«по ссылке») не рассылает ничего; последующий перевод вpublicрассылает. Архивирование (private) и возврат вpublicвторой рассылки не дают;video_comment— под вашим видео появился комментарий;comment_reply— вам ответили в ветке.
Если видео, о котором уведомление, удалено или стало приватным (и оно не
ваше), уведомление остаётся в ящике, но video_id и video_title приходят
null. Рисуйте такую строку без ссылки на видео.
Чужое уведомление отвечает 404 и на отметку, и на удаление.
Жалобы
| Метод | Путь | Доступ |
|---|---|---|
| POST | /videos/{id}/report | токен |
| GET | /me/reports | токен, offset |
POST /videos/dQw4w9WgXcQ/report
{"reason": "spam", "details": "сплошная реклама"}
reason — из перечисления ReportReason; неизвестное значение даёт 422.
Для other пояснение обязательно (400 без него), в остальных случаях —
необязательно, до 1000 символов. Повторная жалоба того же человека на то же
видео — 409: форму отправляют дважды случайно, и это не должно выглядеть
как две жалобы.
Разбор жалоб живёт вне API: status меняет модератор, клиент видит его
в /me/reports.
Аналитика
| Метод | Путь | Доступ | Описание |
|---|---|---|---|
| GET | /me/analytics | токен | Дашборд Студии: весь канал |
| GET | /videos/{id}/analytics | владелец | То же для одного видео |
Период задаётся либо period, либо парой from и to:
GET /me/analytics?period=7d (7d, 30d, 90d, all; без параметров — 30d)
GET /me/analytics?from=2026-09-01&to=2026-09-23
Дни считаются по UTC, обе границы включительно; 7d — сегодня и шесть дней
перед ним. all начинается в день регистрации канала (у видео — в день его
создания). Свой диапазон — не длиннее 3660 дней; period вместе с from/to,
одна граница без другой или from позже to — 400.
{
"period": {
"from": "2026-09-17",
"to": "2026-09-23",
"days": 7,
"previous_from": "2026-09-10",
"previous_to": "2026-09-16"
},
"totals": {
"views": 120,
"watch_time_secs": 5400,
"subscribers_gained": 4,
"subscribers_lost": 1,
"likes": 10,
"comments": 3,
"shares": 2
},
"previous": { "...": "те же ключи за previous_from..previous_to" },
"daily": [
{
"date": "2026-09-17",
"views": 20,
"watch_time_secs": 800,
"subscribers_gained": 1,
"subscribers_net": 0
}
],
"audience": { "views_by_subscribers": 70, "views_by_non_subscribers": 50 },
"basis": {
"signed_in_only": ["watch_time_secs", "daily.watch_time_secs"],
"unknown": [],
"events_since": "2026-10-06T09:12:44.123456Z"
}
}
previous — период той же длины вплотную перед текущим, для дельт на
карточках. У all сравнивать не с чем: previous, previous_from
и previous_to — null. daily идёт без пропусков, день без событий
приходит нулями.
Числа собраны из двух источников, и ответ говорит сам в basis, какое
число чем является. Рисовать стоит по нему, а не по этому тексту.
Журналы событий (вторая фаза): просмотры, репосты, подписки и отписки.
views,daily.viewsиaudience— засчитанные просмотры из журнала, по тем же правилам, чтоview_count(см. «Просмотры»): с анонимами, повтор вошедшего зрителя через полчаса считается снова. Просмотры самого владельца не считаются, если он смотрел вошедшим; анонимные заходы владельца отличить не от кого, и они считаются.audienceделит эти просмотры по тому, был ли зритель подписан на канал в момент просмотра. Аноним всегда вviews_by_non_subscribers.subscribers_gained— подписки за период, включая отменённые потом;subscribers_lost— отписки за период;daily.subscribers_net— их разность за день. Повторная подписка (переключение колокольчика) новой не считается. Подписчик, удаливший аккаунт, исчезает из журнала целиком, как и из числа подписчиков, поэтому суммаsubscribers_netза всё время равна текущемуsubscriber_countканала.shares— все репосты видео канала за период, в том числе анонимов и самого владельца, как лайки и комментарии.
Журналы начинаются с момента обновления, basis.events_since. Раньше
него просмотров по дням, репостов и отписок не записано нигде, и за более
ранние дни эти поля приходят нулями: это «неизвестно», а не «никого не
было». Числа фазы 1 за те дни (просмотры из истории вошедших зрителей) не
подмешиваются: у них другой смысл, и один график из двух источников
выглядел бы как обрыв аудитории в день обновления. Если from раньше
events_since, отметьте эту часть оси. Подписки, действовавшие в момент
обновления, перенесены в журнал с их настоящим временем, поэтому прирост
за прошлые дни виден (кроме тех, кто успел отписаться до обновления).
Существующие таблицы, как в первой фазе:
basis.signed_in_only— только по вошедшим зрителям, из истории просмотров:watch_time_secsиdaily.watch_time_secs. В истории одна строка на пару «зритель, видео», и всё накопленное время просмотра приписано дню первого захода. Анонимы сюда не входят, а зритель может очистить историю (DELETE /me/history), и тогда эти числа уменьшаются задним числом. Заходы самого владельца не считаются.likesиcomments— лайки и комментарии (с ответами) на видео канала, поставленные в период и не снятые до сих пор. Лайк, переключённый из дизлайка, датирован первой реакцией.
Остальное:
basis.unknown— неизвестно, такие поля всегдаnull. У канала список пуст. У видео этоsubscribers_gained,subscribers_lostи оба поля подписчиков вdaily: подписку к ролику не привязать.totals.viewsприperiod=all— не журнал, а счётчикview_count, сложенный по всем видео канала любой видимости, с анонимами и с тем, что было до журнала (и с заходами владельца). Это то же число, что суммаview_countпоGET /videos/my, и не то, чтоview_countканала вGET /channels/{id}(там только публичные видео). Поэтому приallсуммаdaily.viewsменьшеtotals.views.
Служебное
| Метод | Путь | Описание |
|---|---|---|
| GET | /health | Жив ли процесс |
| GET | /health/ready | Доступны ли БД и хранилище (503, если нет) |
| GET | /metrics | Экспозиция Prometheus |
| GET | /docs | Этот документ страницей для браузера |
| GET | /docs.md | Он же исходником в Markdown, для инструментов |
Типовой сценарий
POST /auth/register,/auth/loginили/auth/google→ сохранить обе половины пары; по истеченииexpires_in—POST /auth/refresh.GET /videos?sort=trending&limit=20→ лента; листать поnext_cursor. Карточка канала уже внутри каждого элемента.GET /videos/{id}+GET /videos/{id}/playback→ карточка и плеер,POST /videos/{id}/viewодин раз на старте,GET /videos/{id}/progress→ предложить продолжить с сохранённой позиции.GET /videos/{id}/comments,GET /videos/{id}/reaction,GET /videos/{id}/related→ обсуждение и колонка «дальше».- Во время воспроизведения —
PUT /videos/{id}/progressраз в 10 секунд. - Загрузка:
POST /videos→PUT upload_url→POST /complete(большой файл — частями через/multipart, см. «Загрузка частями»), дальше опрашиватьGET /videos/{id}, покаstatusне станетready(транскодинг идёт в фоне, уведомлений о его ходе нет).
Чего в API нет
Об этом стоит знать заранее, чтобы не искать:
- обработки картинок канала. Аватар и баннер отдаются ровно такими,
какими их загрузили: API не обрезает, не уменьшает и не перекодирует
их, превью разных размеров нет. То же со значками ссылок: размер у
них тот, что отдал сайт (обычно 16–32 px у
.ico, до 180 px уapple-touch-icon); - своего значка для ссылки. Значок выводится из адреса ссылки,
загрузить другой нельзя: у ссылок нет идентификаторов, и
linksзаменяется целым списком; - разбора жалоб. Модераторского интерфейса нет,
statusменяется вне API; - живых обновлений. Ни WebSocket, ни SSE: уведомления и статус транскодинга узнаются опросом;
- прогресса транскодинга в процентах — только
status(иfailure_reasonу владельца, когда перегон не удался); - смены пароля по старому паролю. Пароль меняется только через сброс по коду из письма (см. «Восстановление пароля»);
- телефона и SMS для кодов: коды приходят только на почту;
- истории и плейлистов для анонимов — и то и другое привязано к аккаунту.
- части аналитики. Время просмотра считается только по вошедшим
зрителям, подписчиков к конкретному видео не привязать, а просмотров по
дням, репостов и отписок нет раньше
basis.events_since. Подробности в «Аналитике» и в полеbasisответа.