Источники и параметры

Отправьте ссылку на видео или загрузите свой файл. API работает с YouTube, X, TikTok, Instagram, Facebook, Bluesky и другими платформами из таблицы ниже. Нужна публичная запись по одной из поддерживаемых ссылок.

В теле POST /v1/transcriptions можно задать source, diarize и language: откуда взять текст, нужно ли определять говорящих и какой язык использовать. Все три поля необязательны.

Какие ссылки можно отправить

Ссылку передавайте в url. Платформу API определит по адресу. Если указываете platform вручную, проверьте, что значение соответствует ссылке.

Платформа	Подходящие ссылки
YouTube (`youtube`)	Ссылки на видео в форматах из следующей таблицы.
X (`x`)	Посты с видео на `x.com` и `twitter.com`: например, `https://x.com/user/status/1234567890`.
TikTok (`tiktok`)	Посты с видео на `tiktok.com` и короткие ссылки `vm.tiktok.com`, `vt.tiktok.com`, `www.tiktok.com/t/`.
Instagram (`instagram`)	Reels и видеопосты на `instagram.com` с путями `/reel/`, `/reels/`, `/p/`, `/tv/`. Подходят и ссылки на Reels и посты с именем пользователя перед этим путём.
Facebook (`facebook`)	Видео и Reels на `facebook.com`, в том числе ссылки watch. Подходят короткие ссылки `fb.watch`, `/share/v/` и `/share/r/`.
Bluesky (`bluesky`)	Посты с видео на `bsky.app`: например, `https://bsky.app/profile/user.example/post/3l3w4b5c6d7e2`.
Twitch (`twitch`)	Записи завершённых трансляций (VOD): `twitch.tv/videos/<id>` или `/<channel>/v/<id>`; вместо `v` допускается `video`. Клипы: `clips.twitch.tv/<slug>`, `twitch.tv/<channel>/clip/<slug>` и `/clip/<slug>`. Допустимые хосты: `twitch.tv`, `www`, `m`, `go` и `clips.twitch.tv`.
Dailymotion (`dailymotion`)	Видео по ссылкам `dailymotion.com/video/<id>`, `/embed/video/<id>` или `dai.ly/<id>`. После ID может идти `_title`. Подходят также `www.dailymotion.com` и `touch.dailymotion.com`.
Pinterest (`pinterest`)	Видеопины на `pinterest.com` и `www.pinterest.com`: `/pin/<id>/` или `/pin/<slug>--<id>/`. Берём первый видеоблок, загруженный на сам Pinterest. Видео со сторонних сайтов, изображения, доски, `pin.it` и региональные домены не подходят.
LinkedIn (`linkedin`)	Публичные видеопосты на `linkedin.com` и `www.linkedin.com`: `/posts/<slug>-<activity-id>-<four-character-suffix>` или `/feed/update/urn:li:activity:<id>/`. Ссылки на профили, Learning, мероприятия и короткие ссылки `lnkd.in` не подходят.
Snapchat Spotlight (`snapchat`)	Ролики Spotlight на `snapchat.com` и `www.snapchat.com` с путём `/spotlight/<id>`. Истории и профили не подходят.

Для пяти дополнительных платформ — Twitch, Dailymotion, Pinterest, LinkedIn и Snapchat Spotlight — обязательны HTTPS, отсутствие логина и пароля в URL и стандартный порт. Ссылка должна вести на отдельную публичную запись. Не подходят закрытые посты, контент с обязательным входом, прямые трансляции и записи, которые ещё обрабатываются, а также профили, ленты и подборки. Cookie аккаунта мы не передаём. Параметры времени в URL не обрезают запись.

У клипов Twitch и Snapchat Spotlight поле media_id может содержать строку, из которой нельзя извлечь ID по правилам URL. Храните media_id как есть и не пытайтесь вычислить его по ссылке.

На X, TikTok, Instagram, Facebook и Bluesky тоже нужны публичные посты. Если в посте несколько видео, расшифруем только первое. Профили, истории, страницы прямых трансляций и посты TikTok с фотографиями не подходят. Если для просмотра нужен вход, задача завершится с login_required; если у видео нет звуковой дорожки — с no_audio. В обоих случаях минуты не спишем.

Из YouTube, X, TikTok, Bluesky, Dailymotion и LinkedIn можно получить субтитры, если у видео есть подходящая дорожка на языке оригинала. Instagram, Facebook, Twitch, Pinterest и Snapchat работают только через распознавание речи: принимают auto и stt, но не captions. Цена за минуту одинакова для всех платформ и загруженных файлов; считаем её по фактической длительности записи.

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

Источник субтитров	Какие дорожки используем и какие метки возвращаем
YouTube и X	Дорожки, которые уже есть у видео. Пословные временные метки доступны только у автоматических субтитров YouTube.
TikTok	Субтитры TikTok в VTT или SRT, если они доступны. Временные метки только для сегментов.
Bluesky	Дорожки самого видео на поддерживаемом доверенном PDS. Произвольные серверы федерации, видео из цитируемых постов и со сторонних сайтов не подходят. Временные метки только для сегментов.
Dailymotion	Прямые ссылки на SRT, не плейлисты субтитров. Временные метки только для сегментов. Дорожки, распознанные как en-auto/fr-auto, получают `auto_generated`.
LinkedIn	Доступные VTT-дорожки публичного видео, загруженного в сам LinkedIn, не в LinkedIn Learning. Временные метки только для сегментов.

Форматы ссылок на YouTube

Передайте в url полную ссылку на ролик. Поле platform можно не передавать или указать в нём youtube. API принимает следующие форматы, в том числе с www. и без:

Формат ссылки	Пример
Страница просмотра	`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
Короткая ссылка	`https://youtu.be/dQw4w9WgXcQ`
Shorts	`https://www.youtube.com/shorts/dQw4w9WgXcQ`
Встроенный плеер	`https://www.youtube.com/embed/dQw4w9WgXcQ`
Ссылка вида /live/	`https://www.youtube.com/live/dQw4w9WgXcQ`
Мобильная версия и YouTube Music	`https://m.youtube.com/watch?v=dQw4w9WgXcQ`, `https://music.youtube.com/watch?v=dQw4w9WgXcQ`

Параметры t, list, si и другие дополнительные параметры не учитываем. Разные форматы ссылки на один ролик API распознаёт как одно видео. Передавать только ID из 11 символов нельзя: нужна полная ссылка. Для страницы канала, плейлиста без конкретного видео или неподдерживаемой ссылки API вернёт 422 invalid_url. При неизвестном platform вернётся 422 unsupported_platform со списком supported_platforms.

Доступны публичные ролики и ролики с доступом по ссылке. Закрытое видео даст media_private, возрастное ограничение — age_restricted, а текущая трансляция — live_stream. Если у вас есть свой файл, загрузите его напрямую.

Параметр source

Поле source задаёт способ получения текста: взять субтитры или распознать речь из аудио.

Значение	Что делает API
`auto` (по умолчанию)	Сначала ищет подходящие субтитры на языке оригинала в YouTube, X, TikTok, Bluesky, Dailymotion или LinkedIn. Если их нет, распознаёт речь с помощью ИИ.
`captions` (только субтитры)	Берёт субтитры на платформах с их поддержкой. Не скачивает аудио и не запускает распознавание речи. Если подходящей дорожки нет, задача завершается с `no_captions` без списания минут. Ошибка загрузки содержимого субтитров даёт `fetch_failed`. Для остальных платформ этот режим возвращает `422 invalid_request`.
`stt`	Сразу распознаёт речь из аудио с помощью ИИ.

Для загруженного файла всегда используем распознавание речи. Можно передать source=auto или source=stt; с captions API вернёт 422 invalid_request.

Язык дорожки должен совпадать с language. При language=auto нужен язык оригинала видео. Для YouTube подходят субтитры, которые загрузил автор или создал сам YouTube на этом языке; автоматический перевод не используем.

Сначала выбираем субтитры автора, затем дорожки неизвестного происхождения и только потом автоматические. Неизвестное происхождение не означает, что дорожку загрузил автор. У X используем доступные VTT-дорожки: даже в автоматических субтитрах есть временные метки сегментов, но нет пословных.

Режим auto переходит на STT, если содержимое субтитров недоступно или не поддаётся разбору. Сбои маршрутизации, хранилища и ошибки в коде не вызывают такой переход. При stt API вообще не обращается к субтитрам.

Параметр diarize

Включите diarize, если нужно различать участников разговора. По умолчанию поле равно false.

Определение говорящих работает только при распознавании речи. Поэтому diarize: true с source=auto сразу запускает STT, без проверки субтитров.
Сочетание source: "captions" и diarize: true вернёт 422 invalid_request.
Участники получают метки Speaker 1, Speaker 2 и так далее. Список находится в transcript.speakers, метка сегмента — в его поле speaker. В text и srt перед репликой будет Speaker 1: , в vtt — тег <v Speaker 1>.

{ "platform": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ", "source": "stt", "diarize": true }

Параметр language

Оставьте language=auto или укажите двухбуквенный код ISO 639-1: например, en, de или es. По умолчанию используется auto.

При работе с субтитрами language выбирает язык дорожки. С auto берём язык оригинала видео.
При распознавании речи передаём этот код провайдеру как подсказку. С auto провайдер сам определяет язык; каждый сегмент получает своё поле language.

В поле language самой транскрибации API указывает основной язык записи.

Что будет в транскрипте

Проверьте transcript_source, чтобы узнать источник текста. Возможные значения: youtube_captions, x_captions, tiktok_captions, bluesky_captions, dailymotion_captions, linkedin_captions и speech_to_text. У субтитров есть ещё caption_kind: manual, auto_generated или null. Последнее означает неизвестное происхождение — не подписывайте такую дорожку как загруженную автором.

	`youtube_captions`, `caption_kind` `manual`	`youtube_captions`, `caption_kind` `auto_generated`	`speech_to_text`
Сегменты	По одному на каждый фрагмент субтитров	По одному на каждый фрагмент субтитров	Новый сегмент при смене говорящего или языка, в конце предложения либо при достижении 15 секунд
Пословные временные метки с `include=words`	Недоступны: `words` равно `null`	Есть начало слова; концом считается начало следующего	Начало и конец каждого слова, а также `confidence`
Определение говорящих	Недоступно	Недоступно	Доступно с `diarize=true`
Язык	Совпадает с языком дорожки	Совпадает с языком дорожки	Указан для каждого сегмента

Текст YouTube сохраняем без изменений, в том числе пометки вроде [Music]. Для распознавания речи запись должна длиться не больше 5 часов, иначе задача завершится с media_too_long.

У субтитров X (x_captions), TikTok, Bluesky, Dailymotion и LinkedIn есть только метки сегментов. Даже для автоматических дорожек запрос с include=words вернёт words: null в каждом сегменте. Меток говорящих тоже нет. Для пословных временных меток используйте source: "stt"; для определения говорящих добавьте diarize: true к auto или stt.

Сколько это стоит

За каждую начатую минуту записи списываем один кредит. Получение субтитров и распознавание речи стоят одинаково: source влияет на способ получения текста, а не на цену. Подробности — в разделе «Тарифы и лимиты».