Как подключить приложение или AI-агента к Speechka?

Создайте ключ API, выполните первый запрос или подключите MCP-клиент.

Записи, расшифровки и отчёты доступны из вашего кода через REST API, а AI-агентам — через MCP-сервер. Для этого нужен ключ API или, для MCP-клиентов с OAuth, обычный вход в аккаунт. Откройте кабинет разработчика: «Интеграции → Разработчикам».

Выберите API или MCP

REST API — если вы пишете код: загрузка записей, чтение расшифровок и отчётов, вебхуки. Базовый адрес — https://speechka.ai/api/v2, все пути ниже относительно него.
MCP — если хотите спрашивать о встречах Claude, Cursor, Codex или Gemini прямо в чате: агент сам находит запись и отвечает по ней. Кода не нужно.

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

Создайте ключ с нужными правами

В кабинете разработчика в блоке «Создать ключ» задайте название — по нему вы потом поймёте, какую интеграцию отзывать.
Отметьте права. По умолчанию выбраны только чтение расшифровок и чтение отчётов — такой ключ не может ничего потратить.
Нажмите «Создать ключ» и сразу скопируйте значение вида spk_live_…: в списке останется только начало ключа.

Кабинет «Разработчикам»: форма создания ключа с названием и пятью группами прав — Отмечайте минимум прав, нужный интеграции: отдельный ключ на каждую.

Права ключа (скоупы):

read:transcripts — текст расшифровок, главы, ключевые моменты, поиск, скачивание файлов.
read:reports — готовые отчёты и история чата по записи.
write:transcribe — создание и удаление записей, отправка бота на встречу. Списывает минуты.
write:reports и write:ask — создание отчётов и вопросы по записи. Тратят токены AI.

Запрос без нужного права получает 403 с подсказкой, какого скоупа не хватает. У ключей, выпущенных раньше, встречаются общие read и write: они покрывают всю свою группу и продолжают работать.

Ключ даёт доступ ко всем вашим записям и не истекает сам. Храните его в секретах приложения, не публикуйте в репозитории и не вставляйте в код, который уходит в браузер. Утёк — отзовите и выпустите новый.

Отправьте запись и получите результат

Ключ передаётся в каждом запросе заголовком Authorization: Bearer spk_live_…. Проверить ключ можно запросом GET /v1/ping.

Отправьте файл или ссылку на запись: POST /v1/transcriptions (право write:transcribe). Ответ 202 — задача принята и обрабатывается.
Дождитесь результата: GET /v1/transcriptions/{id} отдаёт статус pending → processing → done либо failed с полем error. При done в ответе есть текст и сегменты по спикерам.
Создайте отчёт: POST /v1/transcriptions/{id}/reports с кодом шаблона; коды — GET /v1/templates. Готовые отчёты — GET …/reports.

первый запрос: файл на расшифровку

curl -s -X POST https://speechka.ai/api/v2/v1/transcriptions \
  -H "Authorization: Bearer spk_live_ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: standup-2026-09-16" \
  -F "file=@meeting.mp3" \
  -F "language=ru"

{"id": "8f14e45f-ceea-467a-9f0b-3d2c1a7b5e90", "status": "pending"}

Заголовок Idempotency-Key защищает от двойного списания при повторе: тот же ключ и тело вернут ту же задачу. Пока расшифровка не готова, создание отчёта и вопрос в чат отвечают 409.

Все ваши записи — GET /v1/transcriptions: новые первыми, следующая страница по next_cursor из ответа. Удаление — DELETE /v1/transcriptions/{id}; вместе с записью удаляются расшифровка, отчёты и история чата, вернуть их нельзя. Поиск по смыслу, чат, главы, ключевые моменты, скачивание в DOCX и PDF, запись созвонов и рилсы описаны в документации API.

Подключите AI-агента по MCP

Адрес MCP-сервера — https://speechka.ai/api/v2/mcp. Подключиться можно двумя способами.

Без ключа, по OAuth — для клиентов с поддержкой OAuth, например веб-версии Claude и Claude Code: добавьте адрес сервера в клиенте, он откроет страницу Speechka, где вы входите и нажимаете «Разрешить доступ». Агент получит права на чтение записей и отчётов и вопросы по записи.
По ключу — для остальных клиентов: создайте ключ с правами read:transcripts, read:reports и write:ask и вставьте конфиг ниже.

конфиг MCP-клиента по ключу

{
  "mcpServers": {
    "speechka": {
      "url": "https://speechka.ai/api/v2/mcp",
      "headers": { "Authorization": "Bearer spk_live_ВАШ_КЛЮЧ" }
    }
  }
}

Готовые пошаговые инструкции с вашим ключом — на страницах интеграций: Claude Desktop, Cursor, Codex, Gemini и любой MCP-клиент. Инструменты сервера: список записей, текст расшифровки, поиск по смыслу, готовый отчёт, вопрос по записи и запуск расшифровки по ссылке — последний списывает минуты.

Настройте вебхуки и обработку ошибок

В кабинете разработчика в блоке «Вебхуки» нажмите «Добавить endpoint», укажите адрес и события: «Расшифровка готова», «Ошибка расшифровки», «Отчёт готов».
Сохраните секрет подписи — он показывается один раз, при добавлении или ротации.
Проверяйте подпись каждой доставки: заголовок X-Speechka-Signature: t=<время>,v1=<подпись>, где подпись — HMAC-SHA256 от строки {t}.{тело} вашим секретом.

Ошибки приходят в едином формате с кодом и понятным сообщением:

формат ошибки

{
  "error": {
    "code": "forbidden",
    "message": "api key missing scope: write:reports (wildcard scope 'write' also works)",
    "type": "permission_error"
  }
}

401 — ключ отозван или неверен; 403 — не хватает права; 404 — чужой или несуществующий id.
402 — не хватает минут на балансе. Пополните их на странице «Минуты и оплата» — как считаются минуты.
429 — превышен лимит: 120 запросов в минуту на ключ для API и 60 для MCP, лимиты независимы. Подождите столько секунд, сколько указано в Retry-After.

Отправляя бота на встречу через API, вы отвечаете за то, чтобы участники знали о записи, — так же, как при записи из кабинета. Условия — в инструкции о записи встреч.

Как отозвать ключ и где найти полную документацию?

Нажмите «Отозвать» рядом с ключом в кабинете разработчика. Ключ перестаёт работать сразу и навсегда: интеграции на нём получат 401 со следующего запроса. Под каждым ключом видно «Использовался» с датой или «Не использовался» — так понятно, какие ключи давно не нужны.

Интерактивная документация по всем эндпоинтам — speechka.ai/api/v2/v1/docs. Она генерируется из кода, поэтому параметры и поля ответов смотрите там, а не в этой статье.