API проверки личности говорящего

Сравните эталонную и проверяемую аудиозаписи, чтобы получить заключение о совпадении говорящего, оценку сходства и метаданные обоих файлов.

Базовый URL

https://api.genderrecognition.com

Конечная точка

POST /v1/speaker-verification/api

Заголовки

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

Тело запроса

Поле	Тип	Обязательно	Описание
reference	файл	Да	Запись известного говорящего для сравнения.
candidate	файл	Да	Запись, которую нужно сравнить с эталонной.

Пример

curl -X POST "https://api.genderrecognition.com/v1/speaker-verification/api" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@audio.wav"

Ответ

{
  "success": true,
  "same_speaker": true,
  "similarity": 87,
  "threshold": 70,
  "reference_audio": {
    "duration": 4.8,
    "sample_rate": 16000
  },
  "candidate_audio": {
    "duration": 5.1,
    "sample_rate": 16000
  },
  "remainingRequests": 119
}

Поля ответа

Поле	Тип	Описание
success	boolean	true, если обе записи обработаны успешно.
same_speaker	boolean	true, если similarity не ниже threshold, то есть записи отнесены к одному говорящему.
similarity	integer	Степень сходства голосов от 0 до 100. Чем выше значение, тем больше сходство.
threshold	integer	Порог сходства от 0 до 100 для значения same_speaker. Если similarity не ниже порога, голоса считаются совпавшими.
reference_audio.duration	number	Длительность эталонной записи в секундах после декодирования для сравнения.
reference_audio.sample_rate	number	Частота дискретизации эталонной записи (Гц) после декодирования перед сравнением.
candidate_audio.duration	number	Длительность проверяемой записи в секундах после декодирования для сравнения.
candidate_audio.sample_rate	number	Частота дискретизации проверяемой записи (Гц) после декодирования перед сравнением.
remainingRequests	integer	Количество запросов API после списания за этот успешный запрос.

similarity и threshold — целые значения в процентах, а не исходные оценки.

Возможные ошибки

Отсутствует ключ API

{ "error": "API key is required" }

Недействительный ключ API

{ "error": "Invalid API key" }

Отсутствуют файлы

{ "error": "Both reference and candidate files are required" }

Файл слишком велик

{ "error": "File too large" }

Неожиданное поле

Возвращается, если файл передан в поле с именем, отличным от reference или candidate (например, в поле file или вместе с дополнительным файлом):

{ "error": "Unexpected field" }

Недопустимый формат файла

{
  "error": "Invalid file type. Allowed formats: WAV, MP3, FLAC, MP4, OGG, AIFF"
}

Не удалось преобразовать аудио

Возвращается, если расширение файла допустимо, но ffmpeg не может его преобразовать (например, если файл повреждён или не читается):

{ "error": "Audio conversion failed: <details>" }

Квота исчерпана

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Ошибка обработки

{ "error": "Speaker verification failed" }

Примечания

• Сервер принимает многие распространённые аудиоформаты, включая WAV, MP3, M4A, FLAC, OGG, WebM, AAC, Opus, WMA, AMR, 3GP, AIFF, AU и другие, а файлы не в формате WAV преобразует перед анализом.
• Передавайте файлы в полях reference и candidate; размер каждого файла не должен превышать 10 МБ.
• Эталонная и проверяемая записи обрабатываются независимо, поэтому они могут отличаться длительностью, частотой дискретизации и форматом.
• Запрос списывается только после успешного завершения проверки.