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

> Какие ссылки принимает API, когда использует субтитры и как включить распознавание речи, определение говорящих и нужный язык.

Canonical: https://transcript1.com/ru/docs/sources-and-options
Language: ru
Last updated: 2026-10-20

Отправьте ссылку на видео или загрузите свой файл. 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](https://transcript1.com/ru/features/rasshifrovka-twitch-vod) (`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](https://transcript1.com/ru/features/rasshifrovka-video-dailymotion) (`dailymotion`) | Видео по ссылкам `dailymotion.com/video/<id>`, `/embed/video/<id>` или `dai.ly/<id>`. После ID может идти `_title`. Подходят также `www.dailymotion.com` и `touch.dailymotion.com`. |
| [Pinterest](https://transcript1.com/ru/features/rasshifrovka-video-pinterest) (`pinterest`) | Видеопины на `pinterest.com` и `www.pinterest.com`: `/pin/<id>/` или `/pin/<slug>--<id>/`. Берём первый видеоблок, загруженный на сам Pinterest. Видео со сторонних сайтов, изображения, доски, `pin.it` и региональные домены не подходят. |
| [LinkedIn](https://transcript1.com/ru/features/rasshifrovka-video-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](https://transcript1.com/ru/features/transkript-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`. Если у вас есть свой файл, [загрузите его напрямую](https://transcript1.com/ru/docs/uploads).

## Параметр 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>`.

```json
{ "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` влияет на способ получения текста, а не на цену. Подробности — в разделе [«Тарифы и лимиты»](https://transcript1.com/ru/docs/billing-and-limits).