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

Базовый URL

https://s2t.a5x.pro/api

API-ключ (`sk_live_...`): `Authorization: Bearer <token>` либо заголовок `X-API-Key`. Ключ — в личном кабинете A5X.

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

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" \
  -F "language=ru"

Режимы

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

Участники (CRM)

Элемент speakers: id (до 50), name, role, опционально department.

Поле	Тип	Описание
`client`	role	Контакт со стороны клиента.
`sales`	role	Продажи.
`manager`	role	Руководитель / ведущий менеджер.
`support`	role	Техподдержка.
`supply`	role	Сопровождение, документы.

Элемент speakers

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

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

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

Загрузка файла (multipart) или публичной ссылки (JSON). Файл — multipart; ссылка — JSON с fileUrl.

Параметры запроса
Поле	Тип	Описание
`file`*	file	Обязательно в multipart. Аудиофайл, до 256 МБ.
`fileUrl`*	string (uri)	Обязательно в JSON. Публичный URL аудио (http/https), до 4096 символов. Всегда async.
`mode`	string	Только multipart: sync (ответ сразу) или async (202 + task_id). По умолчанию sync.
`diarize`	boolean	Разделение по спикерам (поле speaker в сегментах).
`summary`	boolean	Запросить summary. При sync принудительно переводит запрос в async.
`record_id`	string	Ваш ID записи в CRM, до 30 символов.
`direction`	string	in или out — входящий/исходящий звонок.
`speakers`	JSON / array	Участники для CRM: в multipart — JSON-строка, в JSON-теле — массив объектов Speaker (до 20).
`occured_at`	string (date-time)	Реальное время звонка (ISO 8601). По умолчанию — текущее время.

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 "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":"manager"},{"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, дальше GET задачи.
400	`invalid_request_error`	Неверные параметры или файл.
401	`missing_api_key / invalid_api_key`	Нет ключа или ключ недействителен.
413	`file_too_large`	Файл больше 256 МБ.
429	`sync_backpressure`	Много sync-запросов — повторите с паузой (Retry-After).
502	`api_error`	Временный сбой распознавания — повторите позже.

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

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

Тот же API-ключ. Повторяйте запрос, пока transcription_status не станет success или error. Текст расшифровки — в transcription_result_body; статус summary — в summary_generation_status. Поддерживается If-None-Match для 304 Not Modified.

Параметры запроса
Поле	Тип	Описание
`taskId`*	string (uuid)	Идентификатор задачи из ответа 202.
`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",
  "transcription_status": "processing",
  "transcription_result_body": null,
  "transcription_error_message": null,
  "summary_generation_status": "pending",
  "occured_at": "2026-07-08T12:00:00Z"
}

Коды ответов

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

Коммуникация

GEThttps://s2t.a5x.pro/api/public/v1/communications

Получить коммуникацию по `id` или `request_record_id` — обязателен хотя бы один параметр.

Заголовок `x-api-key` с API-ключом клиента.

Параметры запроса
Поле	Тип	Описание
`id`	string (uuid)	UUID коммуникации.
`request_record_id`	string	Ваш ID записи в CRM (1–64 символа).

curl "https://s2t.a5x.pro/api/public/v1/communications?id=YOUR_COMMUNICATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

Успешный ответ (200)

{
  "client_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
  "id": "6b1d4a92-f7e3-4c58-8a2f-5e9b0d3c7a41",
  "request_record_id": "crm-48291",
  "created_at": "2026-06-14T09:12:03.218400Z",
  "occured_at": "2026-07-09T14:22:18.503200Z",
  "transcription_duration_ms": 47280,
  "direction": "in",
  "transcription_status": "success",
  "summary_generation_status": "success",
  "transcription": {
    "language": "ru",
    "text": "Добрый день, A5X Cloud, меня зовут Андрей. Звоню по вашей заявке на демо речевой аналитики — удобно сейчас пару минут? Да, слушаю. Отлично. Вы интересовались транскрибацией и виджетом для сайта. Что для команды приоритетнее? Скорее транскрибация, у нас колл-центр на двести операторов. Понял. Могу прислать расчёт по минутам и кейс из ритейла. Давайте на почту, которую оставляли. Хорошо, отправлю сегодня до шести. Спасибо, жду. До связи.",
    "audio_duration_ms": 47280,
    "segments": [
      {
        "start": 1.24,
        "text": "Добрый день, A5X Cloud, меня зовут Андрей. Звоню по вашей заявке на демо речевой аналитики — удобно сейчас пару минут?",
        "speaker": "SPEAKER_00"
      },
      { "start": 12.08, "text": "Да, слушаю.", "speaker": "SPEAKER_01" },
      {
        "start": 13.42,
        "text": "Отлично. Вы интересовались транскрибацией и виджетом для сайта. Что для команды приоритетнее?",
        "speaker": "SPEAKER_00"
      },
      {
        "start": 21.65,
        "text": "Скорее транскрибация, у нас колл-центр на двести операторов.",
        "speaker": "SPEAKER_01"
      },
      {
        "start": 27.3,
        "text": "Понял. Могу прислать расчёт по минутам и кейс из ритейла.",
        "speaker": "SPEAKER_00"
      },
      { "start": 32.14, "text": "Давайте на почту, которую оставляли.", "speaker": "SPEAKER_01" },
      {
        "start": 35.88,
        "text": "Хорошо, отправлю сегодня до шести.",
        "speaker": "SPEAKER_00"
      },
      { "start": 39.02, "text": "Спасибо, жду.", "speaker": "SPEAKER_01" },
      { "start": 41.56, "text": "До связи.", "speaker": "SPEAKER_00" }
    ]
  },
  "summary_text": "Клиент заинтересован в транскрибации для колл-центра на 200 операторов. Договорились отправить расчёт по минутам и ритейл-кейс на e-mail до 18:00.",
  "category": "sales",
  "category_label": "Продажи",
  "speakers": [
    {
      "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
      "external_id": "client_07",
      "name": "АО «Вектор Логистик»",
      "role": "client",
      "label": "SPEAKER_01"
    },
    {
      "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
      "external_id": "emp_14",
      "name": "Петров Андрей",
      "role": "sales",
      "label": "SPEAKER_00"
    }
  ],
  "summary_items": [
    {
      "id": "e1b4c8d2-6a3f-4e9b-8c1d-2f5a7b0e3d64",
      "item_type": "criteria",
      "subtype": "objection",
      "content": "Нужна оценка ROI по минутам и пилот на 200 операторов",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "a3c9e1f4-2b7d-4a8e-9c0f-1d6e8b2a4c57",
      "item_type": "criteria",
      "subtype": "offer",
      "content": "Расчёт по минутам и ритейл-кейс",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "b8d2f6a1-4e9c-4b3a-8f1e-0c7a5d9e2b14",
      "item_type": "criteria",
      "subtype": "agreement",
      "content": "Отправить материалы на e-mail до 18:00",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "f7a2d5e8-1c4b-4f6a-9d2e-0b8c3a5f7e19",
      "item_type": "next_step",
      "subtype": null,
      "content": "Отправить КП и кейс на e-mail до 18:00",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	—	Unauthorized.
404	—	Not found.

Список коммуникаций

GEThttps://s2t.a5x.pro/api/public/v1/communications/list

Список коммуникаций по спикеру. Обязателен хотя бы один из: `speaker_id`, `speaker_name`, `speaker_external_id`.

Заголовок `x-api-key` с API-ключом клиента.

Параметры запроса
Поле	Тип	Описание
`speaker_id`	string (uuid)	UUID спикера.
`speaker_name`	string	Имя спикера (1–64 символа).
`speaker_external_id`	string	Внешний ID спикера в CRM (1–64 символа).
`limit`	integer	Лимит элементов (1–100). По умолчанию 20.
`offset`	integer	Смещение для пагинации. По умолчанию 0.

По speaker_external_id

curl "https://s2t.a5x.pro/api/public/v1/communications/list?speaker_external_id=emp_14&limit=20&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

Успешный ответ (200)

{
  "items": [
    {
      "client_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
      "id": "6b1d4a92-f7e3-4c58-8a2f-5e9b0d3c7a41",
      "request_record_id": "crm-48291",
      "created_at": "2026-06-14T09:12:03.218400Z",
      "occured_at": "2026-07-09T14:22:18.503200Z",
      "transcription_duration_ms": 47280,
      "direction": "in",
      "category": "sales",
      "category_label": "Продажи",
      "transcription_status": "success",
      "summary_generation_status": "success",
      "summary_text": "Клиент заинтересован в транскрибации для колл-центра на 200 операторов. Договорились отправить расчёт по минутам и ритейл-кейс на e-mail до 18:00.",
      "speakers": [
        {
          "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
          "external_id": "client_07",
          "name": "АО «Вектор Логистик»",
          "role": "client"
        },
        {
          "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
          "external_id": "emp_14",
          "name": "Петров Андрей",
          "role": "sales"
        }
      ]
    },
    {
      "client_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
      "id": "8f2c6e41-a1d9-4b7e-9f3a-2d5c8e0b4a67",
      "request_record_id": "crm-47802",
      "created_at": "2026-06-10T11:05:22.104800Z",
      "occured_at": "2026-07-03T10:15:44.891300Z",
      "transcription_duration_ms": 28410,
      "direction": "out",
      "category": "sales",
      "category_label": "Продажи",
      "transcription_status": "success",
      "summary_generation_status": "success",
      "summary_text": "Первичный контакт: клиент оставил заявку на демо, согласован созвон на четверг в 11:00.",
      "speakers": [
        {
          "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
          "external_id": "client_07",
          "name": "АО «Вектор Логистик»",
          "role": "client"
        },
        {
          "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
          "external_id": "emp_14",
          "name": "Петров Андрей",
          "role": "sales"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "count": 2
  }
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	—	Unauthorized.

Профиль спикера

GEThttps://s2t.a5x.pro/api/public/v1/speakers/profile

Профиль спикера по `speaker_name` или `speaker_external_id` — обязателен хотя бы один параметр.

Заголовок `x-api-key` с API-ключом клиента.

Параметры запроса
Поле	Тип	Описание
`speaker_name`	string	Имя спикера (1–64 символа).
`speaker_external_id`	string	Внешний ID спикера в CRM (1–64 символа).

По speaker_external_id

curl "https://s2t.a5x.pro/api/public/v1/speakers/profile?speaker_external_id=emp_14" \
  -H "x-api-key: YOUR_API_KEY"

Успешный ответ (200)

{
  "client_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
  "speaker_id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
  "speaker_external_id": "emp_14",
  "speaker_name": "Петров Андрей",
  "speaker_role": "sales",
  "speaker_department": "Продажи",
  "speaker_created_at": "2026-03-18T08:30:00Z",
  "speaker_updated_at": "2026-07-09T14:25:41Z",
  "summary_items": [
    {
      "id": "e1b4c8d2-6a3f-4e9b-8c1d-2f5a7b0e3d64",
      "item_type": "criteria",
      "subtype": "objection",
      "content": "Нужна оценка ROI по минутам и пилот на 200 операторов",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "f7a2d5e8-1c4b-4f6a-9d2e-0b8c3a5f7e19",
      "item_type": "next_step",
      "subtype": null,
      "content": "Отправить КП и кейс на e-mail до 18:00",
      "meta": null,
      "speaker_id": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "c4e8a2b7-9d1f-4c6e-8a3b-5f0d7e1c9a28",
      "item_type": "commitment",
      "subtype": null,
      "content": "Отправить расчёт по минутам сегодня до 18:00",
      "meta": { "deadline": "2026-07-09T18:00:00Z" },
      "speaker_id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
      "created_at": "2026-07-09T14:25:41.882100Z"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	—	Unauthorized.
404	—	Not found.

Баланс

GEThttps://s2t.a5x.pro/api/public/v1/balance

Баланс клиента по API-ключу.

Заголовок `x-api-key` с API-ключом клиента.

Узнать баланс

curl "https://s2t.a5x.pro/api/public/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"

Успешный ответ (200)

{
  "balance_rub": "1234.56"
}

Коды ответов

HTTP	error.code	Ситуация
401	—	Unauthorized.

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

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

Категории коммуникаций

Категория коммуникации (category) и типичные подтипы (subtype).

Поле	Тип	Описание
`no_contact`	category	Нет живого контакта: IVR, автоответчик, недозвон, занято, сброс. Ключи: `contact_outcome`, `dial_hint`.
`sales`	category	Продажи и пресейл: новый клиент, допродажа, квалификация, демо; тип — в `deal_type`. Ключи: `deal_type`, `funnel_stage`, `offer`, `objection`, `agreement`, `competitors`, `next_touch_at`.
`renewal`	category	Продление, пересмотр условий текущего контракта, удержание, риск ухода. Ключи: `topic`, `churn_risk`, `agreement`, `next_touch_at`.
`support`	category	Сбои, настройки, доступ, обучение, типовые вопросы по API/интеграции. Ключи: `topic`, `outcome`, `urgency`, `resolution`.
`billing`	category	Счета, акты, оплата, задолженность (не баг функционала). Ключи: `topic`, `outcome`, `disputes`.
`supply`	category	Заказ, документы отгрузки, статус поставки / заказа (не доставка и не оплата). Ключи: `topic`, `order_status`, `documents`, `outcome`.
`logistics`	category	Доставка, склады, сроки, маршруты, ограничения перевозки. Ключи: `topic`, `delivery_status`, `constraints`, `urgency`, `outcome`.
`complaint`	category	Жалоба, эскалация, ультиматумы, требование компенсации или руководства. Ключи: `topic`, `severity`, `requested_resolution`, `escalation`.

Типы элементов summary

Тип элемента в массиве summary_items (item_type).

Поле	Тип	Описание
`criteria`	item_type	Факты звонка: возражения, оффер, исход и др. (см. subtype).
`next_step`	item_type	Рекомендуемые следующие шаги по итогам звонка.
`commitment`	item_type	Обещания сотрудника; дедлайн — в meta.deadline.
`memory`	item_type	Накопленные факты о клиенте между звонками (привязаны к speaker_id).