Speech API — транскрибация и расшифровка аудио

Базовый URL

https://s2t.a5x.pro/api

Передайте API-ключ (sk_live_...) в заголовке Authorization: Bearer <token>. Ключ создаётся в личном кабинете A5X. Невалидный ключ → 401 invalid_api_key; клиент на паузе → 403 client_inactive.

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

curl -X POST "https://s2t.a5x.pro/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/recording.mp3" \
  -F "mode=async"

Режимы

sync — результат сразу в ответе 200 (только multipart).
async — ответ 202 с task_id и communication_id; статус и результат — через GET задачи или webhook. Режим по умолчанию.
JSON с fileUrl всегда обрабатывается асинхронно.
При summary=true или слишком большом файле запрос автоматически уходит в async.
Если summary не указан, а speakers непустой — summary считается true.

Участники разговора

Массив speakers помогает связать расшифровку и summary с вашими участниками. Поля: id (до 50 символов), name, role; опционально department. Допустимые role: client, sales, support, employee, unknown. Любое другое значение приводится к employee; пустая роль — к unknown. Порядок элементов в массиве и role не задают раскладку стереоканалов — см. channel_speakers. Привязка меток SPEAKER_* к участникам выполняется при summary (голос и содержание диалога).

Поле	Тип	Описание
`client`	role	Сторона клиента / контакта.
`sales`	role	Продажи.
`support`	role	Техподдержка.
`employee`	role	Сотрудник (общая роль); также значение по умолчанию для неизвестных ролей.
`unknown`	role	Роль ещё не определена; пустой role приводится к unknown.

Элемент speakers

{
  "id": "emp_01",
  "name": "Иван Иванов",
  "role": "sales",
  "department": "sales"
}

Расшифровка аудио

POSThttps://s2t.a5x.pro/api/v1/audio/transcriptions

Отправьте аудиофайл (multipart/form-data, поле file) или публичную ссылку на файл (JSON, поле fileUrl). В sync-режиме ответ приходит сразу; в async — task_id (опрос статуса) и communication_id.

Параметры запроса

Поле	Тип	Описание
`file`*	file	Аудиофайл (до 1024 МБ). Обязателен для multipart.
`fileUrl`*	string (uri)	Публичный URL аудио (http/https, до 4096 символов). Обязателен для JSON. Такой запрос всегда async.
`mode`	string	Только multipart: `sync` (ответ сразу) или `async` (202 + `task_id` + `communication_id`). По умолчанию `async`.
`diarize`	boolean	Разделять речь по спикерам.
`channel_speakers`	boolean	Стерео/многоканальный файл: `true` (по умолчанию) — сохранить каналы; канал 1 (левый) → `SPEAKER_00`, канал 2 (правый) → `SPEAKER_01`. `false` — свести в mono до ASR. Порядок и role в `speakers` на раскладку каналов не влияют; `direction` тоже.
`timestamp_detail`	string	Детализация таймкодов: `segment` (по умолчанию) или `word`.
`language`	string	Язык: `ru` или `en`.
`summary`	boolean	Запросить аналитику. При `mode=sync` запрос уходит в async.
`user_summary`	string	Промпт пользовательского отчёта (до 64000 символов).
`record_id`	string	Ваш идентификатор записи во внешней системе, до 30 символов.
`direction`	string	Направление звонка: `in` (входящий) или `out` (исходящий).
`speakers`	JSON / array	Участники разговора. В multipart — JSON-строка; в JSON-теле — массив объектов Speaker. role: client \| sales \| support \| employee \| unknown (иное → employee). Не задаёт, кто в левом/правом канале — см. `channel_speakers` и раздел «Участники разговора».
`occured_at`	string (date-time)	Фактическое время звонка в ISO 8601. Если не указано — текущее время сервера.
`webhook_url`	string (uri)	URL (http/https, до 4096 символов) для POST-уведомлений по событиям обработки запроса.

Примеры запросов

curl -X POST "https://s2t.a5x.pro/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/call.mp3" \
  -F "mode=async" \
  -F "diarize=true" \
  -F "channel_speakers=true" \
  -F "summary=true" \
  -F "record_id=deal-78421" \
  -F "direction=in" \
  -F "occured_at=2026-07-08T12:00:00Z" \
  -F 'speakers=[{"id":"emp_01","name":"Иван","role":"sales"},{"id":"c_99","name":"Клиент","role":"client"}]'

Примеры ответов

{
  "language": "ru",
  "text": "Алло, здравствуйте. Добрый день, это Мария из поддержки.",
  "audio_duration_ms": 40600,
  "segments": [
    {
      "start": 0.12,
      "end": 1.45,
      "text": "Алло, здравствуйте.",
      "speaker": "SPEAKER_00",
      "words": [
        { "word": "Алло,", "start": 0.12 },
        { "word": "здравствуйте.", "start": 0.58 }
      ]
    },
    {
      "start": 1.62,
      "end": 4.1,
      "text": "Добрый день, это Мария из поддержки.",
      "speaker": "SPEAKER_01"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
200	—	Готово: JSON с текстом и сегментами.
202	—	Задача принята: в теле `task_id` и `communication_id`; опрос `GET /tasks/{task_id}`.
400	`invalid_request_error`	Неверные параметры или файл.
401	`missing_api_key / invalid_api_key`	Нет ключа или ключ недействителен.
403	`client_inactive`	Клиент неактивен (пауза). Транскрибация недоступна, пока не пополнят баланс или не активируют аккаунт.
413	`file_too_large`	Файл больше 1024 МБ.
429	`sync_backpressure`	Превышение квоты. Слишком много запросов — повторите позже (смотрите Retry-After).
502	`api_error`	Временный сбой распознавания — повторите позже.

Статус задачи (async)

GEThttps://s2t.a5x.pro/api/v1/audio/transcriptions/tasks/{taskId}

Опрос async-задачи тем же API-ключом. В {taskId} — id задачи из ответа 202 (task_id). Повторяйте запрос, пока transcription_status не станет success или error. Можно передать If-None-Match для ответа 304.

Параметры запроса

Поле	Тип	Описание
`taskId`*	string (uuid)	Идентификатор ASR-задачи из ответа 202 (`task_id`).
`If-None-Match`	header	ETag из предыдущего ответа: если статус не изменился, вернётся 304.

Опрос задачи

curl "https://s2t.a5x.pro/api/v1/audio/transcriptions/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Примеры ответов

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "communication_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "transcription_status": "processing",
  "transcription_result_body": null,
  "transcription_error_message": null,
  "occured_at": "2026-07-08T12:00:00Z"
}

Коды ответов

HTTP	error.code	Ситуация
200	—	Текущее состояние задачи (заголовки ETag, Cache-Control).
304	—	Статус не изменился (If-None-Match).
401	`invalid_api_key`	Не авторизован.
403	`client_inactive`	Клиент неактивен.
404	—	Задача не найдена.

Webhooks

URL для уведомлений задаётся в кабинете в разделе Настройки → Система. На него приходит POST по завершении обработки.

Ответьте HTTP 2xx в течение ~15 секунд. Иначе уведомление будет отправлено повторно.
Повторы при ошибке или таймауте: через 15 с → 1 мин → 5 мин → 15 мин → 1 ч → 4 ч. После исчерпания попыток доставка прекращается.
Редиректы не поддерживаются. URL — http или https.
Проверяйте подпись X-Webhook-Signature: секрет — hex(SHA-256 вашего API-ключа), подпись — HMAC-SHA256 от сырого тела запроса.

Уведомления

Событие	Поля	Описание
`transcription.completed`	`event`, `task_id`, `communication_id`	ASR готов. Статус задачи: `GET /v1/audio/transcriptions/tasks/{task_id}`; коммуникация — Public API.
`summary.completed`	`event`, `task_id`, `communication_id`	Готов summary по коммуникации.
`qc.completed`	`event`, `task_id`, `communication_id`	Готова оценка контроля качества.
`memory.completed`	`event`, `task_id`, `communication_id`	Извлечена память по спикерам.
`kb.completed`	`event`, `document_id`, `space_id`	Документ базы знаний проиндексирован.
`kb.failed`	`event`, `document_id`, `space_id`, `error_code`	Индексация документа KB завершилась ошибкой.

POST /hooks/transcription HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: a5x-webhook
X-Webhook-Signature-Alg: hmac-sha256
X-Webhook-Signature: sha256=<hex>

{"event":"transcription.completed","task_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7","communication_id":"11111111-2222-3333-4444-555555555555"}

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

{
  "error": {
    "message": "Не передан обязательный параметр: file.",
    "type": "invalid_request_error",
    "code": "missing_file",
    "param": "file"
  }
}