Для разработчиков и интеграторов

API транскрибации

Встройте распознавание речи в свой продукт: отправьте файл или ссылку одним POST-запросом — получите текст с таймкодами, спикерами и AI-саммари. Вебхук сам сообщит о готовности — поллинг не нужен.

Получить API-ключ Смотреть методы

Ключи выпускаются самостоятельно в профиле на тарифах «Профессионал» и «Бизнес» — без ожидания и переписки. Аутентификация — стабильный заголовок X-API-Key или Bearer, без истекающих токенов.

Так это выглядит

Один запрос — готовая расшифровка

Загрузите файл, укажите webhook_url — и получите POST с результатом, когда обработка завершится.

Запрос

curl -X POST https://cosmoscribe.ru/api/v1/transcriptions \
  -H "X-API-Key: <ваш ключ>" \
  -H "Idempotency-Key: order-1042" \
  -F "file=@meeting.mp3" \
  -F "language=auto" \
  -F "webhook_url=https://example.ru/hooks/cosmic"

Вебхук о готовности

POST https://example.ru/hooks/cosmic
X-Cosmic-Event: transcription.completed
X-Cosmic-Signature: hmac-sha256(тело, секрет)

{
  "event": "transcription.completed",
  "data": {
    "id": "01a0…",
    "status": "completed",
    "language": "ru",
    "audio_duration_seconds": 1847
  },
  "links": {
    "result": "…/api/v1/transcriptions/01a0…",
    "export": "…?format=json"
  }
}

Что умеет API

Те же возможности, что и в веб-интерфейсе, — доступные программно.

Загрузка

Файлы и ссылки

POST /transcriptions принимает аудио и видео (MP3, WAV, M4A, OGG, MP4, MOV и другие). POST /transcriptions/url — импорт по ссылке: VK Видео, RuTube, Яндекс.Диск, прямые URL и другие источники.

Качество

Диаризация и словарь

Разделение по спикерам, пользовательский словарь терминов (методы /dictionary), выбор языка или автоопределение.

Саммари и перевод

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

Экспорт

5 форматов

GET /transcriptions/{id}/export?format=… — TXT, SRT, VTT, JSON с таймкодами и сегментами или оформленный DOC для Word.

Надёжность

Вебхуки и идемпотентность

Вебхук о готовности с HMAC-SHA256-подписью в заголовке X-Cosmic-Signature и ретраями. Заголовок Idempotency-Key защищает от дублей при повторных запросах.

Безопасность

Серверы в РФ

Обработка и хранение в России, шифрование аудио в покое, IP-whitelist на ключ, лимиты запросов в минуту/день/месяц.

Основные методы

Базовый URL — https://cosmoscribe.ru/api/v1. Аутентификация — заголовок X-API-Key или Authorization: Bearer.

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

POST /transcriptions

Загрузка аудио/видео файла (поля file, language, group_id, denoise_enabled, webhook_url)
POST /transcriptions/url

Импорт по ссылке (url, language, webhook_url)
POST /transcriptions/batch

Пакетная загрузка нескольких файлов
GET /transcriptions/{id}

Статус и результат: текст, сегменты, спикеры
GET /transcriptions/{id}/export

Экспорт в txt / srt / vtt / json / doc
POST /transcriptions/{id}/resume

Докрутка усечённой записи после пополнения лимита

AI-функции

POST /transcriptions/{id}/summaries

Создать AI-саммари по одному из 10 шаблонов
GET /summaries/{id}

Получить готовое саммари
POST /transcriptions/{id}/translations

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

Служебные

GET /account

Тариф, лимиты ключа и настройки вебхука
PUT /account/webhook

Задать webhook_url по умолчанию, ротация секрета
GET/POST/DELETE /dictionary

Пользовательский словарь терминов
GET/POST /groups

Папки-группы записей

Без поллинга

Вебхуки о готовности

Передайте webhook_url при создании записи или задайте общий через PUT /account/webhook. Когда обработка завершится, мы отправим POST с результатом.

Подпись HMAC-SHA256 сырого тела в заголовке X-Cosmic-Signature — проверяйте её секретом из GET /account.
События transcription.completed и transcription.failed, идентификатор доставки в X-Cosmic-Delivery.
Ретраи с нарастающим интервалом, если ваш сервер ответил ошибкой.
Редиректы не выполняются: ответ 3xx считается ошибкой доставки — указывайте конечный URL.

Как подключиться

Три шага до первой расшифровки из вашего кода.

1

Выпустите ключ

На тарифе «Профессионал» или «Бизнес» откройте Профиль → «Безопасность» → «API-ключи» и выпустите ключ в один клик. Нужно ограничение по IP — напишите в поддержку.
2

Отправьте файл

POST /api/v1/transcriptions с файлом или POST /api/v1/transcriptions/url со ссылкой. В ответ придёт log_id со статусом queued.
3

Получите результат

Вебхуком на ваш URL или запросом GET /transcriptions/{id}. Экспортируйте в нужный формат одним GET.

Частые вопросы об API

Как получить API-ключ?

На тарифах «Профессионал» и «Бизнес» ключи выпускаются самостоятельно: Профиль → «Безопасность» → «API-ключи». Ключ показывается один раз при выпуске, храним только его отпечаток. Ограничение по списку IP-адресов настроим по запросу в поддержку.

Как тарифицируются запросы?

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

Что придёт в вебхуке?

Компактный JSON: событие, идентификатор записи, статус, язык, длительность и ссылки на полный результат и экспорт. Сам текст расшифровки заберите запросом GET /transcriptions/{id} — так вебхук остаётся лёгким, а данные не гуляют лишний раз по сети.

Как проверить подпись вебхука?

Посчитайте HMAC-SHA256 от сырого тела запроса с секретом из GET /account и сравните с заголовком X-Cosmic-Signature (hex). Секрет можно ротировать через PUT /account/webhook.

Что делает Idempotency-Key?

Если сеть оборвалась и вы повторили POST с тем же ключом, вторая запись не создастся — вернётся log_id первой. Ключи хранятся 48 часов.

Какие форматы файлов поддерживаются?

Любые аудио- и видеоформаты: MP3, WAV, M4A, AAC, OGG, OPUS, FLAC, MP4, MOV, MKV, AVI, WEBM и другие. Из видео на сервере остаётся только аудиодорожка.

Готовы встроить транскрибацию в свой продукт?

Выпустите ключ в профиле и отправьте первый запрос уже сегодня. Вопросы по интеграции и лимитам под ваш объём — в поддержку.

Выпустить ключ Тарифы

На главную