Голоса и спикеры

Три разных вещи, которые легко перепутать:

• Спикер записи это номер голоса внутри одной записи: segments[].speaker = 0, 1, 2… В следующей записи тот же человек может оказаться под другим номером.
• Голос проекта это постоянный номер человека во всех записях проекта: #100, #101… Появляется при включённой опции «Узнавать по голосу».
• Имя это то, как вы назвали голос проекта: «Азимбек (менеджер)». Имя не обязательно: безымянный голос тоже узнаётся.

Как голоса получают номера

Когда запись обработана с включённой опцией «Узнавать по голосу»:

1. Для каждого спикера записи считается голосовой отпечаток.
2. Отпечаток сравнивается с голосами проекта. Совпал: спикер получает номер этого голоса, статус matched.
3. Не совпал, а речи у спикера 10 секунд и больше: регистрируется новый голос проекта со следующим номером, статус new.
4. Речи меньше 10 секунд: статус unknown, номера нет. Отпечаток с нескольких секунд ненадёжен, и мы не заводим по нему голос.

Связь спикеров записи с голосами проекта лежит в voices:

"voices": [
  {"label": "SPEAKER_1", "speaker": 0, "voice_id": 100, "name": null, "status": "new"},
  {"label": "SPEAKER_2", "speaker": 1, "voice_id": 101, "name": "Азимбек", "status": "matched", "score": 0.97}
]

speaker это номер из segments[].speaker, voice_id номер голоса проекта, speaker_id его идентификатор для API спикеров.

Сколько голос живёт

Не каждый услышанный голос стоит хранить вечно, поэтому у голоса есть вид, и он виден в kind:

Вид	Что это	Сколько живёт
candidate	Голос, услышанный один раз	30 дней с последней встречи, потом исчезает
recurring	Услышан в трёх записях и более	Хранится, пока его не удалят
named	Голос, которому дали имя	Хранится, пока его не удалят

Кандидат, который встретился ещё раз, обновляет last_seen_at и отсчёт начинается заново; на третьей записи он становится повторяющимся, и срок с него снимается. Имя снимает срок сразу: назвали голос — он остаётся. Поэтому голос сотрудника лучше назвать в первый же раз, а не ждать третьей записи.

expires_at говорит, когда голос исчезнет, у recurring и named он пустой.

Дать имя

Вкладка «Спикеры» кабинета показывает все голоса проекта: именованные и «Голос #100», узнанные автоматически. Кнопка «Дать имя» превращает номер в имя. Через API: PATCH /v1/speakers/{id} с {"name": "…"}.

Отметить фрагменты как одного человека

Иногда разделение по спикерам ошибается: один человек попадает в два номера, или наоборот. В результате записи есть режим «Отметить фрагменты одного человека»: выберите реплики, которые точно принадлежат одному человеку, и укажите, кто это: существующий голос или новое имя. Из выбранных реплик считается отпечаток и добавляется этому голосу. Чем больше речи выбрано, тем надёжнее; кабинет предупредит, если меньше 10 секунд.

Через API: POST /v1/speakers/{id}/enroll с {"job_id": "…", "segment_indexes": [3, 5, 8]}. Достаточно указать номера реплик: отпечаток считается на нашей стороне из хранимой записи. Самих отпечатков в ответе нет — это биометрия и сотни чисел на голос, работать с ними напрямую незачем.

Загрузить образец голоса

На вкладке «Спикеры» можно загрузить короткую запись одного человека (например, 20–30 секунд речи менеджера) и сразу привязать её к голосу. Запись распознаётся как обычная задача, то есть тратит баланс наравне с остальными.

Голос это биометрические данные

Добавляйте голоса только с согласия людей. Удаление голоса удаляет все его отпечатки: DELETE /v1/speakers/{id}. У голоса не больше 10 отпечатков, у проекта не больше 500 голосов.