YouTubeрасшифровкируководство по API

Как массово скачивать расшифровки YouTube через API

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

SocQОбновлено 19 июля 2026 г.10 мин чтения

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

В этом руководстве показано, как получать доступный текст публичных расшифровок YouTube с помощью SocQ YouTube Transcripts API, обрабатывать несколько URL видео в рамках асинхронной задачи и готовить нормализованные результаты для поиска, суммаризации, исследований или генерации с дополнением извлеченными данными (RAG).

Короткий ответ: отправьте URL публичных видео YouTube и необязательный язык в формате BCP-47 на POST /v1/youtube/transcripts. Сохраните возвращенный task_id, опрашивайте эндпоинт задачи и читайте готовые записи из data.results.items. SocQ возвращает простой текст расшифровки и контекст видео, если доступны пригодные публичные субтитры. Если субтитров нет, новое распознавание речи не выполняется.

Может ли официальный API YouTube скачать любую публичную расшифровку?

Нет. В официальном YouTube Data API есть ресурсы субтитров, но метод скачивания предназначен для дорожек субтитров, которыми аутентифицированный пользователь вправе управлять. В текущей документации Google сказано, что captions.download требует авторизации OAuth, а у пользователя должно быть право редактировать видео. Кроме того, каждый вызов метода стоит 200 единиц квоты.

Это работает, если вы владеете каналом или управляете им. Универсального способа скачивать текст субтитров произвольных публичных видео он не дает. Требования к авторизации описаны в официальной документации Google по скачиванию субтитров.

Полезно разделять три сценария:

ТребованиеПодходящий подход
Управление субтитрами своих видеоYouTube Data API с OAuth
Получение уже доступного текста субтитров выбранных публичных видеоУправляемый эндпоинт расшифровок, например SocQ
Расшифровка аудио, когда субтитров нетОтдельный пайплайн распознавания речи (ASR)

SocQ покрывает второй сценарий. Он получает доступный текст расшифровки; он не утверждает, что расшифровка есть у каждого публичного видео, и не подменяет ее незаметно заново сгенерированным текстом ASR.

Отправка запроса на расшифровку YouTube

Эндпоинт принимает один или несколько URL публичных видео. Можно также передать предпочтительный язык, например en или zh-CN.

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.youtube.com/watch?v=arj7oStGLkU"
    ],
    "language": "en"
  }'

Отправка запускает асинхронную задачу. Сохраните возвращенный task_id; не отправляйте тот же пакет повторно только потому, что обработка не завершилась мгновенно.

Опрашивайте задачу, пока она не перейдет в конечное состояние:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

queued и running — нормальные промежуточные состояния. После успешного завершения задачи читайте data.results.items. Если страница результатов сообщает has_more: true, запросите следующую страницу с возвращенным next_cursor.

Структура ответа с расшифровкой

Нормализованная запись расшифровки имеет стабильную структуру, которую можно сохранять без разбора страницы YouTube:

{
  "id": "arj7oStGLkU",
  "platform": "youtube",
  "resource": "transcripts",
  "type": "transcript",
  "url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "text": "A plain-text transcript snapshot.",
  "language": "en",
  "available_languages": ["en"],
  "format": "plaintext",
  "transcript_source": "auto_generated",
  "author": {
    "id": "UCAuUUnT6oDeKwE6v1NGQxug",
    "username": "TED",
    "name": "TED",
    "url": "https://www.youtube.com/@TED"
  },
  "created_at": "2016-04-06T00:00:00",
  "collected_at": "2026-07-16T08:00:00Z",
  "extra": {
    "duration_seconds": 843
  }
}

Важнее всего для последующей обработки следующие поля:

  • text: выбранная расшифровка в виде простого текста.
  • language: фактически возвращенный язык, который может отличаться от предпочтительного.
  • available_languages: непустые языки расшифровки, найденные для видео.
  • transcript_source: классификация источника субтитров, если она известна.
  • id, url, title и author: контекст источника для отслеживаемости.
  • created_at и collected_at: время публикации и время сбора.
  • extra.duration_seconds: полезно для проверки качества и оценки нагрузки.

Ответ намеренно содержит простой текст. В нем нет надежных меток времени сегментов или меток говорящих. Не придумывайте точное время цитат и не преобразуйте ответ в SRT так, будто данные о времени существуют.

Получение расшифровок на нужном языке

Язык в запросе — это предпочтение, а не гарантия. Продакшен-процесс всегда должен маршрутизировать данные по возвращенному language.

Например, если вы запрашиваете en:

  1. Может быть выбрана английская дорожка.
  2. Может быть выбрана совместимая дорожка на базовом языке.
  3. В качестве резервного варианта может вернуться другая доступная дорожка.
  4. Запись может не появиться вовсе, если пригодной публичной расшифровки нет.

Сохраняйте language и available_languages вместе с каждой расшифровкой. Если точное соответствие языка обязательно, отклоняйте или проверяйте резервные результаты, а не передавайте их сразу в перевод, поиск или LLM.

Сохраняйте также transcript_source. Автоматически созданные субтитры ценны в больших объемах, но YouTube отмечает, что плохой звук, неподдерживаемые языки, долгие паузы, одновременная речь нескольких человек и несколько языков в одном видео могут помешать созданию автоматических субтитров или снизить их качество. Подробнее — в рекомендациях YouTube по устранению проблем с автоматическими субтитрами.

Массовая обработка расшифровок YouTube

Массовую обработку нужно проектировать как пайплайн данных, а не как цикл, который предполагает, что каждый URL обработается успешно.

Video URLs
   ↓
Validate and deduplicate
   ↓
Submit transcript batches
   ↓
Persist task IDs
   ↓
Poll with backoff
   ↓
Read every result page
   ↓
Validate language and source
   ↓
Store, chunk, index, or export

Придерживайтесь следующих практик:

  1. Нормализуйте URL до отправки. Приводите дублирующиеся URL просмотра, ссылки «Поделиться» и встроенные URL к одному ID видео.
  2. Делайте пакеты восстанавливаемыми. Сохраняйте каждый пакет, его входные URL, ID задачи, время отправки и конечный статус.
  3. Опрашивайте с увеличивающейся задержкой. Избегайте плотного цикла опроса. Увеличивайте задержку, пока задача остается в очереди или выполняется.
  4. Считайте частичный результат нормой. Успешная задача может содержать меньше записей, чем отправлено URL, потому что у некоторых видео нет пригодных субтитров.
  5. Проходите пагинацию до конца. Продолжайте, пока has_more не станет false.
  6. Делайте запись идемпотентной. Выполняйте upsert по ID видео и языку расшифровки, чтобы повторные попытки не создавали дубликатов.
  7. Фиксируйте время сбора. Расшифровка — это снимок; субтитры позже могут отредактировать или удалить.

Вот минимальный пример опроса на Node.js:

const headers = {
  Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
  "Content-Type": "application/json"
};

const submitted = await fetch(
  "https://api.socq.ai/v1/youtube/transcripts",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      urls: [
        "https://www.youtube.com/watch?v=arj7oStGLkU",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      ],
      language: "en"
    })
  }
).then(response => response.json());

let task;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  task = await fetch(
    `https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
    { headers }
  ).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));

if (task.data.status !== "succeeded") {
  throw new Error(`Transcript task ended with ${task.data.status}`);
}

const transcripts = task.data.results.items;

Перед использованием в продакшене добавьте проверку HTTP-статусов, ограниченное число повторных попыток, курсорную пагинацию, структурированное логирование и отмену.

Обработка отсутствующих субтитров и частичных результатов

Отсутствие результата не означает автоматически, что весь пакет завершился ошибкой. Типичные причины:

  • Автор не добавил субтитры, а автоматические субтитры недоступны.
  • Субтитры недавно опубликованного видео еще обрабатываются.
  • Язык речи не поддерживается или не был распознан.
  • Плохое качество звука, речь накладывается, или в видео звучат несколько языков.
  • Видео закрытое, удаленное, имеет ограничения или недоступно в среде сбора.
  • Запрошенного языка нет, а пригодного резервного варианта не нашлось.

Классифицируйте сбои, а не повторяйте их бесконечно:

Тип сбояРекомендуемое действие
Нет пригодных субтитровПометить как недоступное; при необходимости направить в отдельный процесс ASR
Нет запрошенного языкаПроверить available_languages или принять контролируемый резервный вариант
Временная ошибка задачи или сетиПовторить с экспоненциальной задержкой и лимитом попыток
Закрытое, удаленное или ограниченное видеоПрекратить повторы и записать причину
Пустая или подозрительная расшифровкаОтправить на карантин для проверки

Не выдавайте результат ASR за субтитры YouTube, не указав источник. Это различие важно для проверки точности и цитирования.

Безопасный экспорт данных расшифровок

Результаты в виде простого текста можно экспортировать в TXT, JSON или CSV.

Для TXT записывайте поле text и храните рядом отдельную запись с метаданными. Для JSON сохраняйте нормализованный объект целиком. Для CSV используйте одну строку на видео с полями id, url, title, language, transcript_source, text и collected_at.

Для SRT и VTT нужны сегменты с метками времени. Поскольку эндпоинт расшифровок SocQ возвращает простой текст, а не сегменты, достоверный экспорт субтитров с таймингом только из этого ответа получить нельзя.

Для архивов с поиском не храните только текст расшифровки. Сохраняйте ID видео, канонический URL, название, канал, язык, источник, время публикации и время сбора в каждой производной записи.

Подготовка расшифровок для поиска и RAG

Необработанные расшифровки обычно слишком велики и зашумлены, чтобы отправлять их в модель одним блоком. Лучше действовать так:

  1. Нормализуйте пробельные символы, не переписывая исходный текст.
  2. Выявляйте неожиданно короткий или пустой текст.
  3. Разбивайте текст на перекрывающиеся смысловые фрагменты (чанки).
  4. Прикрепляйте метаданные источника к каждому фрагменту.
  5. Создавайте эмбеддинги.
  6. Храните фрагменты в поисковом или векторном индексе.
  7. Возвращайте URL видео и метаданные расшифровки вместе с каждым ответом.

Полезная запись фрагмента выглядит так:

{
  "video_id": "arj7oStGLkU",
  "video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "language": "en",
  "transcript_source": "auto_generated",
  "chunk_index": 12,
  "text": "The transcript text for this chunk...",
  "collected_at": "2026-07-16T08:00:00Z"
}

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

Выберите нужный API YouTube до получения расшифровок

Сбор расшифровок часто является последним шагом более широкого процесса поиска:

  • Используйте YouTube Search API, чтобы находить подходящие публичные видео и фильтровать их по наличию субтитров.
  • Используйте YouTube Videos API для нормализованных метаданных видео.
  • Используйте YouTube Channel Videos API, чтобы составить перечень видео выбранного канала.
  • Используйте YouTube Transcripts API только для тех видео, текст которых вам действительно нужен.

Это сокращает лишние запросы расшифровок и привязывает итоговый датасет к явным критериям отбора.

Поддержание актуальности датасета расшифровок

У архива расшифровок должна быть явная политика обновления. Субтитры могут исправить после публикации, могут появиться новые языковые дорожки, а ранее доступное видео могут удалить или ограничить. Повторно получать все каждый день расточительно, но если считать первый ответ постоянным, в поисковом индексе может остаться устаревший или неотслеживаемый текст.

Выбирайте интервал обновления в зависимости от сценария:

  • Для разового исследовательского датасета сохраняйте время сбора и избегайте автоматических обновлений, если анализ их не требует.
  • Для архива канала с поиском чаще перепроверяйте недавние видео, потому что субтитры часто редактируют вскоре после публикации.
  • Для процессов, связанных с соблюдением требований или цитированием, перепроверяйте источник, прежде чем публиковать цитату или принимать важное решение.
  • Для долгоживущих RAG-систем храните хеш содержимого, чтобы неизменившаяся расшифровка не запускала лишнюю повторную разбивку и создание эмбеддингов.

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

Чек-лист для продакшена

Перед запуском задачи большого объема убедитесь, что:

  • Входные данные — URL публичных видео YouTube.
  • URL нормализованы и очищены от дубликатов.
  • ID задач и исходные входные данные сохраняются.
  • Опрос выполняется с задержкой и ограниченным числом повторных попыток.
  • Курсорная пагинация продолжается, пока has_more не станет false.
  • Отсутствующие результаты обрабатываются отдельно от сбоев задач.
  • Возвращенный язык проверяется.
  • Автоматически созданные субтитры помечены.
  • Каждый фрагмент или экспорт сохраняет метаданные источника.
  • Использование контента соответствует применимым правам, ожиданиям конфиденциальности и условиям платформы.

Часто задаваемые вопросы

Есть ли официальный API для расшифровок YouTube?

У YouTube есть официальный Captions API, но для скачивания дорожки субтитров нужны OAuth и право редактировать видео. Это не универсальный API расшифровок для произвольных публичных видео.

Можно ли скачать расшифровку YouTube без OAuth?

SocQ YouTube Transcripts API использует API-ключ SocQ, а не разрешение OAuth от YouTube. Он получает доступный текст расшифровки по выбранным URL публичных видео.

Может ли SocQ создать расшифровку, если у видео нет субтитров?

Нет. Эндпоинт возвращает доступный текст публичной расшифровки. Видео без пригодных субтитров может не дать результата. Если нужен резервный вариант ASR, используйте отдельный процесс распознавания речи с явным указанием источника.

Можно ли запросить конкретный язык?

Да. Можно передать необязательный язык в формате BCP-47, например en или zh-CN, но фактически возвращенный язык может отличаться. Всегда проверяйте language и available_languages.

Содержит ли ответ метки времени и метки говорящих?

Нет. Формат ответа — нормализованный простой текст без меток времени сегментов и без гарантированных меток говорящих.

Можно ли получить несколько расшифровок в одном запросе?

Да. Передайте несколько URL публичных видео в urls, сохраните ID задачи и прочитайте все страницы готовых результатов после успешного завершения асинхронной задачи.

Сколько стоит YouTube Transcripts API?

В текущей документации эндпоинта указано 0,5 кредита за нормализованный результат расшифровки. Перед оценкой продакшен-нагрузки проверьте актуальную страницу эндпоинта, так как цены могут меняться.

YOUTUBE API

Проверить сценарий на публичном URL YouTube

Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.

API для YouTube