YouTube через API и MCP: 83 действия, три Google-скоупа и как загружать файлы

Обзор

YouTube — не один API, а три под общим брендом: Data API v3 отвечает за канал, видео, плейлисты, комментарии и трансляции; Analytics API считает просмотры, удержание и деньги; Reporting API формирует массовые CSV-отчёты по расписанию. У всех трёх — общая авторизация через Google OAuth, но, как выяснилось при подключении, не общие права доступа.

Mira разбирает эту связку целиком — 83 действия, включая загрузку файлов multipart-запросом, — и отдаёт их в Claude через MCP. Ниже — что доступно на практике, где авторизация Google устроена не так, как ожидаешь, и как устроена загрузка видео и картинок, ради которой обычно и заводят интеграцию с YouTube.

Что доступно владельцу канала

Итого 83, из них 50 меняют данные — деньги YouTube не берёт напрямую (квота API не тратит рубли), но изменение, удаление и публикация видны снаружи или необратимы, и барьер записи одинаков что для платного, что для «просто заметного».

Ловушки, которые стоит знать заранее

Аналитика недоступна на обычном чтении — и это не баг

Казалось бы естественным: подключил канал на чтение — получил и видео, и статистику. У YouTube не так. Скоупы yt-analytics.readonly и yt-analytics-monetary.readonly — своё, отдельное пространство доступа, не входящее ни в youtube.readonly, ни даже в полный youtube. Источник, подключённый в режиме «только чтение», физически не сможет вызвать ни один метод Analytics или Reporting API — не потому что мы это запретили, а потому что в его токене нет нужного скоупа вовсе.

Единственный способ получить отчётность — подключить источник с правом записи, даже если писать вы ничего не планируете. Мы прямо называем это в подсказке при подключении: без этого человек десять минут перечитывает сообщение об ошибке 403, пытаясь понять, какое право на запись ему не хватает, хотя вопрос вообще не про запись.

Загрузка видео — не JSON-запрос, а два куска в одном теле

videos.insert, captions.insert, thumbnails.set, watermarks.set, channelBanners.insert, а также добавление и замена картинки плейлиста — семь действий, и все требуют не обычное тело с полями, а multipart/related: один HTTP-запрос с ДВУМЯ частями — JSON-метаданные ресурса (заголовок видео, описание, теги) и сами байты файла. Формат старше JSON API и почти нигде, кроме загрузки в Google, не встречается.

Модель не умеет передать байты файла напрямую — в её распоряжении только текст. Поэтому содержимое называется ссылкой (file_url, инструмент сам скачивает — с проверкой, что ссылка не ведёт в служебную сеть) или строкой base64 (file_base64, когда файл уже под рукой). У самого видео свой, увеличенный предел размера: общий лимит на файл в Mira — 25 МБ, для videos_insert — 500 МБ, потому что короткий ролик в 25 МБ почти никогда не помещается.

part — обязательный параметр почти везде, и про него легко забыть

Возврат данных в Data API устроен не как «отдай мне видео», а как «отдай мне ЧАСТИ видео» — snippet, status, contentDetails, statistics запрашиваются отдельно, и не названная часть просто не появится в ответе, без предупреждения. То же самое при изменении: обновить видео без part=snippet в запросе — значит не тронуть заголовок, даже если он передан в теле.

Разумное умолчание подставляется само: для списка видео это snippet,contentDetails,statistics, для канала — snippet,contentDetails,statistics. Не пришлось бы объяснять модели устройство параметра part, чтобы получить простой список видео.

Идентификатор ресурса — почти всегда параметр запроса, а не часть адреса

В отличие от многих REST API, DELETE /videos/{id} у YouTube не существует. Удаление видео — это DELETE /videos?id=VIDEO_ID, то есть идентификатор в query-строке, а не в пути. Из 83 действий путь как часть адреса использует лишь шестёрка: скачивание файла субтитров и вся работа с задачами массовой отчётности (Reporting API нумерует задачи и отчёты как вложенные ресурсы — /jobs/{id}/reports/{id}).

У одного из двух путевых параметров — буквальные слэши внутри значения

Скачивание готового отчёта (media.download) адресуется строкой вида jobs/<id>/reports/<id> — и Google прямо просит не кодировать в ней «/»: они не разделяют разные параметры, они часть ОДНОГО идентификатора ресурса. Обычная защита от обхода адреса (кодировать каждый спецсимвол) здесь ломает сам запрос — закодированный %2F адресует несуществующий ресурс. Это ровно тот редкий случай, ради которого в общем помощнике Mira для сборки адресов есть настройка «этому полю разрешено содержать буквальный слэш» — как у номера счёта в API Точка Банка.

Квота считается не запросами, а «единицами», и стоимость разная

10 000 единиц в день на проект в Google Cloud — это не 10 000 вызовов. Простое чтение стоит 1 единицу, search.list — 100, а любая запись — от 50. Опрос ленты поиска в цикле «на всякий случай» способен исчерпать дневную квоту меньше чем за сотню вызовов, и Google ответит на это своим отказом 403, не нашим.

Как это выглядит через MCP

MCP — открытый протокол, по которому Claude подключается к внешним данным и действиям. Вместо написания клиента для трёх разных Google API вы подключаете YouTube в кабинете Mira одной авторизацией и спрашиваете обычными словами.

Какие видео у меня получили больше всего просмотров за последний месяц?

Claude вызывает отчёт YouTube Analytics с нужными метриками и диапазоном дат — при условии, что канал подключён с правом записи: без него, как описано выше, у токена нет скоупа аналитики.

Есть новые комментарии, требующие модерации?

Список цепочек комментариев приходит с состоянием модерации по каждой, а не общим счётчиком.

Ответь на этот комментарий от имени канала: "..."

Публикация ответа — действие под барьером записи: источник должен быть подключён с разрешением, и подтверждение спрашивается явно, потому что ответ увидят все зрители видео.

Что защищено от случайного действия

Барьер записи выведен из той же таблицы, что описывает адреса и параметры — разойтись им негде: разрешение на запись хранится в том же месте, что метод и путь, а не отдельным списком, который можно забыть обновить. Источник без права записи физически не отправит POST, PUT или DELETE — запрос обрывается раньше похода к Google.

Что это даёт на практике

Автору канала. Не нужно открывать YouTube Studio, чтобы узнать, какие видео растут, а какие комментарии ждут ответа, — можно спросить прямо в чате.

Медиа-команде. Планирование трансляций, модерация комментариев и обновление плейлистов — одним доступом, без переключения между вкладками Studio.

Разработчику. Готовый клиент вместо разбора трёх разных Discovery-документов Google: приведённые ошибки, известные пределы квоты, разведённые уровни доступа между чтением и аналитикой.

Как подключить

1. В Mira: проект → источники → YouTube → «Подключить».
2. Авторизоваться через Google и выбрать канал.
3. Если нужна аналитика и отчётность — отметить «Разрешить запись» уже на этом шаге: добавить её позже можно только повторной авторизацией.

Дальше YouTube доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте с поддержкой протокола.