РуководстваТранскрибация YouTube

Транскрибация YouTube и Instagram

Передайте нам URL — мы скачаем аудио, расшифруем и структурируем результат. Промежуточные файлы можно не трогать.

Поддерживаемые источники

Видео YouTube — youtube.com/watch?v=…, youtu.be/…, m.youtube.com/watch?v=…
YouTube Shorts — youtube.com/shorts/…
Instagram Reels и публикации в ленте — instagram.com/reel/…, instagram.com/p/… (только публичные)
Прямые ссылки на медиа — любой общедоступный MP3, MP4, M4A, WAV и подобные форматы

Базовый запрос

Отправьте POST с URL на /v1/transcriptions. В ответ придёт 202 и объект транскрипции в статусе queued — тип источника определяется автоматически.

request.shbash

curl -X POST https://api.quillhub.ai/v1/transcriptions \
  -H "Authorization: Bearer $QAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "structure": true
  }'

202 Acceptedjson

{
  "id": "trs_8f2c91a0b3e4",
  "status": "queued",
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "created_at": "2026-04-23T10:14:02Z"
}

Этапы обработки

Шаг 1

Скачивание

Читаем метаданные, проверяем длительность и вытягиваем аудиодорожку из YouTube или Instagram. Прямые ссылки проходят потоком.

Шаг 2

Расшифровка

Аудио уходит в наш движок распознавания с опциональной диаризацией спикеров. Язык определяется автоматически, если не указан явно.

Шаг 3

Структурирование

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

Опрос статуса

Запрашивайте транскрипцию по id. Пока она обрабатывается, status равен processing, а progress — число от 0 до 1. Если не хотите опрашивать, задайте webhook_url в запросе на создание.

poll.shbash

curl https://api.quillhub.ai/v1/transcriptions/trs_8f2c91a0b3e4 \
  -H "Authorization: Bearer $QAI_KEY"

200 OKjson

{
  "id": "trs_8f2c91a0b3e4",
  "status": "processing",
  "progress": 0.42,
  "source": { "type": "youtube", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
  "duration_seconds": 1843,
  "created_at": "2026-04-23T10:14:02Z"
}

Параметры запроса

Поле	Тип	По умолчанию	Описание
`language`	string	auto	Код ISO-639-1 (en, ru, es…). Опустите для автоопределения. Явный язык помогает на коротких и шумных записях.
`speaker_recognition`	boolean	false	Помечает, кто что сказал. Хорошо работает на подкастах и интервью. Увеличивает время обработки на ~10–15%.
`structure`	boolean	true	Добавляет result.structured с заголовком, саммари, оглавлением, абзацами, хайлайтами и терминами.
`webhook_url`	string	—	HTTPS-эндпоинт, куда мы отправим готовую транскрипцию POST-запросом. Про подпись — в разделе Webhooks.
`metadata`	object	—	До 16 пар ключ/значение, которые вернутся в объекте транскрипции. Удобно для связки с вашими записями.

Обработка ошибок

Часть источников недоступна для скачивания. В таком случае транскрипция переходит в status: "failed" с машинно-читаемым error.code, по которому удобно ветвить логику.

Типичные причины отказа. Приватные и скрытые видео, удалённые загрузки, контент только для подписчиков и геоблокированные в нашем регионе видео возвращают source_unavailable. Источники длиннее ~10 часов отклоняются ещё на этапе probe с кодом duration_too_long — до того, как начнётся тарифицируемая обработка.

failed.jsonjson

{
  "id": "trs_8f2c91a0b3e4",
  "status": "failed",
  "error": {
    "code": "source_unavailable",
    "message": "The video is private, deleted, or geoblocked in our region."
  }
}

Особенности Instagram

Поддерживаются только публичные Reels и видео из ленты. Stories, Highlights и всё за логином или у приватного аккаунта отдадут source_unavailable — авторизованные сессии мы не проксируем.

← Назад

Аутентификация

Webhooks