API Слова

Быстрый старт

1. Получите ключ

   Создайте ключ в Профиле, в разделе «API и MCP», и сохраните его на сервере — например, в переменной окружения SLOWO_API_KEY.

2. Отправьте запись

   Для каждой новой записи создайте UUID и сохраните его до отправки: с ним повтор запроса безопасен.

   cURLPythonNode.js

   Отправка записи · cURLСкопировать

   REQUEST_ID=$(uuidgen)
   curl https://slowo.io/api/v1/transcriptions \
     -H "Authorization: Bearer $SLOWO_API_KEY" \
     -H "Idempotency-Key: $REQUEST_ID" \
     -F "file=@call.mp3" \
     -F "external_id=call-42"

3. Получите текст

   Ответ 202 содержит id записи. Запрашивайте её, пока статус не станет ready или failed, — или включите уведомления.

   Статус и текстСкопировать

   curl https://slowo.io/api/v1/transcriptions/$TRANSCRIPTION_ID \
     -H "Authorization: Bearer $SLOWO_API_KEY"

   Ответ для готовой записиСкопировать

   {
     "transcription": {
       "id": "5b1f0c2e-8d4a-4c3b-9f7e-2a6d1e0b9c84",
       "channel": "api",
       "external_id": "call-42",
       "title": "call",
       "status": "ready",
       "language": "auto",
       "duration_seconds": 31,
       "charged_seconds": 31,
       "error": null,
       "text": "Добрый день! Хочу перенести доставку на пятницу.\n\nЗдравствуйте! Пятница свободна, курьер приедет с десяти до двух.",
       "segments": [
         { "id": "segment-1", "speaker_id": "speaker_0", "start": 2.1, "end": 5.8,
           "text": "Добрый день! Хочу перенести доставку на пятницу." },
         { "id": "segment-2", "speaker_id": "speaker_1", "start": 6.3, "end": 11.4,
           "text": "Здравствуйте! Пятница свободна, курьер приедет с десяти до двух." }
       ],
       "speakers": { "speaker_0": "Спикер 1", "speaker_1": "Спикер 2" }
     }
   }

Ключи и доступ

Передавайте ключ в каждом запросе в заголовке Authorization: Bearer …. Ключ с полным доступом отправляет, читает, экспортирует и удаляет записи. Ключ только для чтения получает список, статус, текст, экспорт и расход времени.

Ключ видит только записи, отправленные через API и MCP. Записи с сайта и из Telegram ему недоступны.

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

Отправка записи

Отправьте файл в поле file формы multipart. Необязательные поля: language (auto, ru или en; по умолчанию auto) и external_id — ваш идентификатор до 200 символов, например номер звонка. Он вернётся в ответах и уведомлениях.

Вместо файла можно передать JSON с audio_url — прямой публичной HTTPS-ссылкой на файл, путь которой заканчивается расширением медиафайла. Подписанные параметры допустимы; переадресации, логин в адресе и внутренние адреса — нет. Запрос может длиться до 15 минут: поставьте клиенту такой таймаут и не меняйте ссылку при повторе.

curl https://slowo.io/api/v1/transcriptions \
  -H "Authorization: Bearer $SLOWO_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/calls/call-42.mp3", "external_id": "call-42"}'

Подходят аудио MP3, M4A, WAV, AAC, OGG, OPUS, FLAC, AMR и WMA, а также видео MP4, MOV, WEBM, MKV и 3GP. Файл — до 1 ГБ, запись — до 4 ч. Записи аккаунта распознаются по очереди, по одной.

Статус и результат

Готовая запись содержит text — весь текст, segments — реплики с speaker_id, start и end в секундах — и speakers — имена участников. Если распознать не удалось, причину объясняет error.code, а время не списывается.

Уведомления

Укажите адрес в Профиле, в разделе «API и MCP». Мы отправим POST-запрос при событиях transcription.completed и transcription.failed. В событии — id записи, статус и ваш external_id; текст получите запросом с ключом.

Проверяйте подпись до разбора JSON. Заголовок Slowo-Signature имеет вид t=TIMESTAMP,v1=HEX, где v1 — HMAC-SHA256 строки TIMESTAMP + "." + тело запроса с вашим секретом в качестве ключа. Сравнивайте подписи за постоянное время и отклоняйте запросы старше пяти минут.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, signature, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature ?? "");
  if (!match) return false;
  const [, timestamp, hex] = match;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(hex, "hex"));
}

Уведомление может прийти повторно: отсеивайте дубли по Slowo-Event-Id и отвечайте коротким ответом 2xx — до 64 КиБ, без переадресации. Если сервер не ответил за 10 секунд или ответил иначе, мы попробуем снова — всего до 10 попыток: первая пауза 30 секунд, дальше она удваивается, но не превышает часа. Недоставленные уведомления видны в «API и MCP», там их можно отправить снова.

Экспорт

Готовую запись можно скачать в формате txt, docx, pdf или srt. Экспорт не списывает время.

curl -o call.srt "https://slowo.io/api/v1/transcriptions/$TRANSCRIPTION_ID/export?format=srt" \
  -H "Authorization: Bearer $SLOWO_API_KEY"

Повторы и ошибки

Каждая отправка требует заголовок Idempotency-Key — UUID, который вы создаёте и сохраняете до запроса. Если ответ потерялся, повторите запрос с тем же UUID и теми же данными: вы получите ту же запись без второго списания. Для новой записи нужен новый UUID.

Повтор работает 24 часа. Позже, до 30 дней с первой отправки, тот же UUID вернёт 409 IDEMPOTENCY_EXPIRED, для удалённой записи — 410 RESOURCE_DELETED, а с другими данными — 409 IDEMPOTENCY_CONFLICT. Через 30 дней ключ забывается.

Ошибки приходят в одном формате. Опирайтесь на code, а request_id (он же в заголовке X-Request-Id) пришлите в поддержку.

{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "…", "request_id": "…" } }

Оплата и лимиты

Сайт, API и MCP используют один баланс и одни пакеты. Время списывается один раз — по измеренной длительности и только за распознанную запись. Запись должна целиком помещаться в доступное время, иначе она завершится ошибкой INSUFFICIENT_BALANCE — частичного текста API не возвращает. Пополнение баланса не перезапускает такую запись: отправьте её снова с новым UUID.

GET /usage показывает доступное и зарезервированное время, число распознанных записей и списанное за них время — всего и отдельно для API и MCP, а также лимиты аккаунта: запросы в минуту, очередь, размер и длительность файла.

Данные и версии

Записи API хранятся в вашем аккаунте и видны в «Записях». Запрос DELETE /transcriptions/{id} удаляет файл и текст; во время распознавания удалить запись нельзя. Для учёта остаются только сведения о расходе времени, повторах и уведомлениях. Подробнее — в политике конфиденциальности и оферте.

Версия API — в адресе: /v1. Игнорируйте незнакомые поля в ответах и обрабатывайте незнакомые коды ошибок как общую ошибку.

Справочник

Точные схемы запросов и ответов — в спецификации OpenAPI: openapi.json.