Документация для разработчиков публикуется на английском. Боковое меню переведено на выбранный язык.

Справочник API

Base URL: https://api.subdownload.com · Auth: Authorization: Bearer sk_live_xxx

Эндпоинты

GET /v1/verify free

Проверка валидности API-ключа. Возвращает сведения о токене и пользователе. Не списывает кредиты.

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

Ответ 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

Получить транскрипт / субтитры для видео YouTube. Принимает ID видео или любой корректный YouTube-URL (watch, youtu.be, shorts).

Параметры

Имя	Тип	Обязательно	Описание
`video_id`	string	ОБЯЗАТЕЛЬНО	ID видео из 11 символов или полный YouTube-URL. Алиас: `video_url`.
`lang`	string	опционально	Предпочтительные коды языков через запятую (например, `en,zh,ja`).

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

Ответ 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

Ошибки

400 отсутствует video_id · 404 нет субтитров · 402 кредиты закончились

GET /v1/youtube/search 1 credit

Поиск видео или каналов YouTube по ключевому запросу.

Параметры

Имя	Тип	Обязательно	Описание
`q`	string	ОБЯЗАТЕЛЬНО	Поисковый запрос (1–200 символов).
`type`	string	опционально	`video` (по умолчанию) или `channel`.
`limit`	integer	опционально	1–50 результатов (по умолчанию 20).

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

Преобразует любую ссылку на канал (@handle, URL, UC… ID) в каноничные данные о канале.

Параметры

Имя	Тип	Обязательно	Описание
`input`	string	ОБЯЗАТЕЛЬНО	@handle, URL канала, URL видео или UC… ID.

GET /v1/youtube/channel/search 1 credit

Поиск видео внутри конкретного канала.

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	ОБЯЗАТЕЛЬНО	@handle, URL или UC… ID (алиас: `channel_id`).
`q`	string	ОБЯЗАТЕЛЬНО	Поисковый запрос.
`limit`	integer	опционально	1–50 (по умолчанию 30).

GET /v1/youtube/channel/latest free

Получить ~15 последних видео канала через RSS. Быстро и бесплатно.

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	ОБЯЗАТЕЛЬНО	@handle, URL или UC… ID (алиас: `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

Постраничный список всех загрузок канала (~100 на страницу).

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	первая страница	@handle, URL или UC… ID (алиас: `channel_id`).
`continuation`	string	следующие страницы	Токен, возвращённый предыдущим вызовом.

Примечание: указывайте либо channel, либо continuation, но не оба.

GET /v1/youtube/playlist/videos 1 credit/page

Постраничный список видео плейлиста YouTube.

Параметры

Имя	Тип	Обязательно	Описание
`playlist`	string	первая страница	URL или ID плейлиста (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	следующие страницы	Токен из предыдущего ответа.

ИИ-транскрибация (ASR)

Запустите Whisper для видео без субтитров. Асинхронно: POST создаёт задачу, затем опрашивайте GET до status=done. 5 кредитов, списываются только при успешном завершении — повторный запуск ASR по тому же видео бесплатен.

POST /v1/youtube/asr 5 кредитов при done

Запускает асинхронную ИИ-транскрибацию Whisper. Возвращает task_id и подсказки по ETA, чтобы задать ритм опроса.

Тело (JSON)

Имя	Тип	Обязательно	Описание
`video_url`	string	ОБЯЗАТЕЛЬНО	URL YouTube (watch / youtu.be / shorts / embed).
`lang`	string	опционально	Подсказка языка (`en`, `ru`…). Опустите для авто-определения.

Запрос

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

Ответ 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

Соблюдайте next_poll_after_seconds между опросами. При попадании в кэш сразу возвращается status=done с вложенными segments.

GET /v1/youtube/asr/{task_id} бесплатно

Опрос задачи ASR. Бесплатно — кредиты и квота токена не расходуются. Доступ только у создателя.

Статусы: queued · downloading · transcribing · done · failed · cancelled. Segments финальны только при status=done.

Library (пользовательское хранилище)

Пер-пользовательское хранилище сохранённых транскриптов и ИИ-саммари. Чтения бесплатны; записи расходуют 1 единицу квоты токена. Кредиты пользователя не списываются.

GET /v1/library бесплатно

Список элементов, сохранённых пользователем в Library (транскрипты + саммари).

Параметры

Имя	Тип	Обязательно	Описание
`favorite`	string	опционально	`1` или `true` — только избранное.
`q`	string	опционально	Совпадение по подстроке title/author.
`tag`	string	опционально	Фильтр по тегу.
`limit`	integer	опционально	1–100 (по умолчанию 20).
`offset`	integer	опционально	Смещение пагинации.

GET /v1/library/{id} бесплатно

Метаданные одного элемента Library. Используйте has_asr / has_summary, чтобы выбрать следующий content-эндпоинт.

GET /v1/library/{id}/transcript бесплатно

Возвращает ASR segments и склеенный текст. 404, если нет завершённого ASR.

GET /v1/library/{id}/summary бесплатно

Возвращает сохранённый текст саммари. Используйте ?locale=, чтобы выбрать из сохранённых локалей (по умолчанию Accept-Language, затем en). 404, если для (video_id, locale) нет саммари.

POST /v1/library бесплатно (1 единица квоты токена)

kind=asr помечает сохранённый транскрипт (segments уже в таблице ASR). kind=summary загружает готовый текст саммари в таблицу summaries и ставит has_summary=true. Upsert по (video_id, locale).

Тело (JSON)

Имя	Тип	Обязательно	Описание
`video_id`	string	ОБЯЗАТЕЛЬНО	ID видео YouTube.
`kind`	string	ОБЯЗАТЕЛЬНО	`asr` или `summary`.
`title / author / thumbnail / video_url / language / tag`	string	опционально	Метаданные для отображения / фильтрации.
`locale`	string	режим summary	Локаль саммари (по умолчанию `Accept-Language`, затем `en`).
`text`	string	при kind=summary	Текст саммари для сохранения.
`model`	string	опционально	Идентификатор LLM (например, `claude-opus-4`).

DELETE /v1/library/{id} бесплатно

Soft-delete элемента Library. Повторный POST /v1/library для того же видео восстановит строку, а не создаст дубликат.

Официальные SDK

Интегрируйтесь быстрее через официальные библиотеки клиентов:

Язык	Репозиторий
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Полный исходный код: github.com/SubDownload/api-sdk

→ Оплата, лимиты и коды ошибок — в разделе Поддержка и оплата.

Документация для разработчиков публикуется на английском. Боковое меню переведено на выбранный язык.

Справочник API

Base URL: https://api.subdownload.com · Auth: Authorization: Bearer sk_live_xxx

Эндпоинты

GET /v1/verify free

Проверка валидности API-ключа. Возвращает сведения о токене и пользователе. Не списывает кредиты.

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

Ответ 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

Получить транскрипт / субтитры для видео YouTube. Принимает ID видео или любой корректный YouTube-URL (watch, youtu.be, shorts).

Параметры

Имя	Тип	Обязательно	Описание
`video_id`	string	ОБЯЗАТЕЛЬНО	ID видео из 11 символов или полный YouTube-URL. Алиас: `video_url`.
`lang`	string	опционально	Предпочтительные коды языков через запятую (например, `en,zh,ja`).

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

Ответ 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

Ошибки

400 отсутствует video_id · 404 нет субтитров · 402 кредиты закончились

GET /v1/youtube/search 1 credit

Поиск видео или каналов YouTube по ключевому запросу.

Параметры

Имя	Тип	Обязательно	Описание
`q`	string	ОБЯЗАТЕЛЬНО	Поисковый запрос (1–200 символов).
`type`	string	опционально	`video` (по умолчанию) или `channel`.
`limit`	integer	опционально	1–50 результатов (по умолчанию 20).

Запрос

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

Преобразует любую ссылку на канал (@handle, URL, UC… ID) в каноничные данные о канале.

Параметры

Имя	Тип	Обязательно	Описание
`input`	string	ОБЯЗАТЕЛЬНО	@handle, URL канала, URL видео или UC… ID.

GET /v1/youtube/channel/search 1 credit

Поиск видео внутри конкретного канала.

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	ОБЯЗАТЕЛЬНО	@handle, URL или UC… ID (алиас: `channel_id`).
`q`	string	ОБЯЗАТЕЛЬНО	Поисковый запрос.
`limit`	integer	опционально	1–50 (по умолчанию 30).

GET /v1/youtube/channel/latest free

Получить ~15 последних видео канала через RSS. Быстро и бесплатно.

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	ОБЯЗАТЕЛЬНО	@handle, URL или UC… ID (алиас: `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

Постраничный список всех загрузок канала (~100 на страницу).

Параметры

Имя	Тип	Обязательно	Описание
`channel`	string	первая страница	@handle, URL или UC… ID (алиас: `channel_id`).
`continuation`	string	следующие страницы	Токен, возвращённый предыдущим вызовом.

Примечание: указывайте либо channel, либо continuation, но не оба.

GET /v1/youtube/playlist/videos 1 credit/page

Постраничный список видео плейлиста YouTube.

Параметры

Имя	Тип	Обязательно	Описание
`playlist`	string	первая страница	URL или ID плейлиста (`PL…`, `UU…`, `LL…`, `FL…`, `OL…`).
`continuation`	string	следующие страницы	Токен из предыдущего ответа.

ИИ-транскрибация (ASR)

POST /v1/youtube/asr 5 кредитов при done

Запускает асинхронную ИИ-транскрибацию Whisper. Возвращает task_id и подсказки по ETA, чтобы задать ритм опроса.

Тело (JSON)

Имя	Тип	Обязательно	Описание
`video_url`	string	ОБЯЗАТЕЛЬНО	URL YouTube (watch / youtu.be / shorts / embed).
`lang`	string	опционально	Подсказка языка (`en`, `ru`…). Опустите для авто-определения.

Запрос

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

Ответ 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

Соблюдайте next_poll_after_seconds между опросами. При попадании в кэш сразу возвращается status=done с вложенными segments.

GET /v1/youtube/asr/{task_id} бесплатно

Опрос задачи ASR. Бесплатно — кредиты и квота токена не расходуются. Доступ только у создателя.

Статусы: queued · downloading · transcribing · done · failed · cancelled. Segments финальны только при status=done.

Library (пользовательское хранилище)

GET /v1/library бесплатно

Список элементов, сохранённых пользователем в Library (транскрипты + саммари).

Параметры

Имя	Тип	Обязательно	Описание
`favorite`	string	опционально	`1` или `true` — только избранное.
`q`	string	опционально	Совпадение по подстроке title/author.
`tag`	string	опционально	Фильтр по тегу.
`limit`	integer	опционально	1–100 (по умолчанию 20).
`offset`	integer	опционально	Смещение пагинации.

GET /v1/library/{id} бесплатно

Метаданные одного элемента Library. Используйте has_asr / has_summary, чтобы выбрать следующий content-эндпоинт.

GET /v1/library/{id}/transcript бесплатно

Возвращает ASR segments и склеенный текст. 404, если нет завершённого ASR.

GET /v1/library/{id}/summary бесплатно

POST /v1/library бесплатно (1 единица квоты токена)

Тело (JSON)

Имя	Тип	Обязательно	Описание
`video_id`	string	ОБЯЗАТЕЛЬНО	ID видео YouTube.
`kind`	string	ОБЯЗАТЕЛЬНО	`asr` или `summary`.
`title / author / thumbnail / video_url / language / tag`	string	опционально	Метаданные для отображения / фильтрации.
`locale`	string	режим summary	Локаль саммари (по умолчанию `Accept-Language`, затем `en`).
`text`	string	при kind=summary	Текст саммари для сохранения.
`model`	string	опционально	Идентификатор LLM (например, `claude-opus-4`).

DELETE /v1/library/{id} бесплатно

Soft-delete элемента Library. Повторный POST /v1/library для того же видео восстановит строку, а не создаст дубликат.

Официальные SDK

Интегрируйтесь быстрее через официальные библиотеки клиентов:

Язык	Репозиторий
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ Полный исходный код: github.com/SubDownload/api-sdk

→ Оплата, лимиты и коды ошибок — в разделе Поддержка и оплата.