Документация API

Тело — multipart/form-data. Ответ приходит сразу, до окончания обработки: запись создаётся в статусе queued. Из видео на сервере остаётся только аудиодорожка. Лимит размера файла зависит от тарифа, для видео он выше — фактические значения возвращает GET /account.

curl -X POST https://cosmoscribe.ru/api/v1/transcriptions \
  -H "X-API-Key: $COSMIC_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -F "file=@meeting.mp3" \
  -F "language=auto" \
  -F "webhook_url=https://example.ru/hooks/cosmic"

{
  "message": "Транскрибация поставлена в очередь",
  "log_id": "9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70",
  "status": "queued"
}

Российские источники (VK Видео, RuTube, Одноклассники, Дзен, Mail.ru, Telegram, Яндекс.Диск) доступны на всех тарифах; зарубежные (YouTube, Vimeo, Twitch, SoundCloud, Dailymotion, Apple Podcasts и другие) — с тарифа «Профессионал». Прямые ссылки на файл проходят проверку хоста от подмены на внутренний адрес. Скачивание асинхронное: ответ приходит до его окончания.

curl -X POST https://cosmoscribe.ru/api/v1/transcriptions/url \
  -H "X-API-Key: $COSMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vk.com/video-1_1","language":"ru"}'

Полезно, чтобы показать пользователю, что именно будет расшифровано, и заранее убедиться, что ссылка поддерживается. Минуты не списываются.

Количество файлов за раз и суммарный размер ограничены настройками сервиса. Параметр webhook_url этот метод не принимает — уведомления по каждой записи придут на адрес по умолчанию, заданный на ключе.

Один метод на весь жизненный цикл: пока запись не готова, поля с текстом пустые, а status равен queued или processing. К тексту уже применён словарь терминов. Опрашивать метод в цикле не нужно, если настроен вебхук.

curl https://cosmoscribe.ru/api/v1/transcriptions/9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70 \
  -H "X-API-Key: $COSMIC_API_KEY"

{
  "data": {
    "id": "9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70",
    "status": "completed",
    "original_filename": "meeting.mp3",
    "language": "ru",
    "clean_text": "Добрый день. Начнём с плана на квартал…",
    "formatted_text": "[00:00] Спикер 1: Добрый день…",
    "segments": [
      {
        "start": 0.48,
        "end": 4.12,
        "text": "Добрый день. Начнём с плана на квартал.",
        "speaker": "SPEAKER_00",
        "words": [
          { "word": "Добрый", "start": 0.48, "end": 0.91 },
          { "word": "день.", "start": 0.94, "end": 1.32 }
        ]
      }
    ],
    "is_partial": false,
    "audio_duration_seconds": 1847,
    "full_duration_seconds": 1847,
    "group_id": null,
    "source_type": "upload"
  }
}

Формат json возвращает JSON с текстом и сегментами, остальные — файл на скачивание. Текстовые форматы отдаются в UTF-8 с BOM, чтобы Windows-редакторы не ломали кириллицу. Если у записи есть пословные тайм-коды, srt и vtt режутся по границам слов: карточка не длиннее 7 секунд и не шире двух строк по 42 символа, разрыв предпочитается на конце предложения. Без пословных данных реплика отдаётся одной карточкой, как раньше. Если у записи распознаны спикеры, srt получает имя в начале карточки при смене говорящего, а vtt — тег <v Имя> в каждой карточке; на записях без спикеров вывод прежний.

curl -L "https://cosmoscribe.ru/api/v1/transcriptions/9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70/export?format=srt" \
  -H "X-API-Key: $COSMIC_API_KEY" -o meeting.srt

Правка текста через API — то же действие, что редактирование в интерфейсе: сохранённый текст становится источником для экспорта и поиска.

Действие необратимо: удаляются и текст, и файл в хранилище.

Нужен, когда в ответе пришло is_partial = true. Метод дочитывает запись с того места, где остановился прошлый прогон, и склеивает сегменты. Доступен, пока исходный файл не удалён по сроку хранения тарифа.

Файл расшифровывается на лету, поддерживаются частичные запросы по Range для перемотки в плеере.

Запись должна быть готова и содержать не меньше 50 символов текста. По одной записи можно держать несколько шаблонов одновременно. Готовность отслеживается через GET /summaries/{id}: пока модель работает, статус равен queued или processing. Шаблон custom требует поля custom_instruction — текстового описания нужного разбора; формат ответа при этом остаётся тем же, а поле metadata у такого пересказа всегда пустое.

curl -X POST https://cosmoscribe.ru/api/v1/transcriptions/9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70/summaries \
  -H "X-API-Key: $COSMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"meeting"}'

curl -X POST https://cosmoscribe.ru/api/v1/transcriptions/9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70/summaries \
  -H "X-API-Key: $COSMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"custom","custom_instruction":"Выпиши все возражения клиента и как на них ответили."}'

Состав полей зависит от шаблона: задачи есть у встречи и звонков, темы — у встречи, интервью, лекции и подкаста, у хайлайтов вместо текста массив цитат с таймкодами.

{
  "id": "b4c9a1d2-77e3-4f10-8c55-1a2b3c4d5e6f",
  "transcription_log_id": "9f1c2f7e-5a44-4c0e-9b1e-2d3c4b5a6f70",
  "template": "meeting",
  "status": "completed",
  "summary_text": "Обсудили план на квартал…",
  "key_points": ["Запуск переносится на март"],
  "action_items": [
    { "task": "Прислать смету", "assignee": "Иван", "due_date": "2026-09-01", "completed": false }
  ],
  "topics": ["Планирование"],
  "language": "ru",
  "generated_at": "2026-08-25T12:44:19+00:00"
}

Единственное разрешённое изменение — состав и флаги выполнения задач. Работает только для шаблонов с задачами: встреча, звонок клиенту, звонок в поддержку, голосовая заметка.

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

Если пара с таким from уже есть, обновится только to — повторный вызов безопасен.

Первый запрос, которым стоит проверить интеграцию: если он вернул 200, ключ рабочий. Поле plan содержит те же лимиты, что видит интерфейс, — по нему удобно заранее понять допустимый размер файла и остаток минут.

curl https://cosmoscribe.ru/api/v1/account -H "X-API-Key: $COSMIC_API_KEY"

{
  "client": {
    "id": "3f2a1b0c-1111-2222-3333-444455556666",
    "name": "Продакшен",
    "status": "active",
    "rpm_limit": 60,
    "daily_limit": 5000,
    "monthly_limit": 100000
  },
  "webhook": {
    "url": "https://example.ru/hooks/cosmic",
    "secret": "8f14e45fceea167a5a36dedd4bea2543",
    "signature_header": "X-Cosmic-Signature",
    "signature_algo": "hmac-sha256(raw_body, secret), hex"
  },
  "plan": {
    "max_file_mb": 500,
    "monthly_audio_minutes": 1200
  }
}

Адрес по умолчанию работает для всех записей ключа, включая пакетную загрузку. Ротация секрета мгновенная: подписи со старым секретом перестанут совпадать, поэтому меняйте секрет и настройки приёмника вместе. То же самое можно сделать в профиле, без обращения к API.