Перейти к основному содержимому

API определения пола по голосу

Определяет вероятный пол говорящего по загруженной аудиозаписи или URL аудиофайла.

Базовый URL​

https://api.genderrecognition.com

Выберите конечную точку​

ВариантМетод и путьДля чего подходит
Стандартный анализ файлаPOST /v1/voice-gender-recognition/apiЗагрузка файла со стандартной обработкой.
Стандартный анализ URLPOST /v1/voice-gender-recognition/api/urlАудиофайл, доступный по общедоступному URL.
V2: анализ всей записиPOST /v1/voice-gender-recognition/api/v2Анализ с обнаружением речи для записи с одним говорящим.
V3: анализ говорящегоPOST /v1/voice-gender-recognition/api/v3Звонки, интервью и другие записи с несколькими участниками.

Стандартная конечная точка URL принимает аудиоссылку в формате JSON. V2 и V3 принимают только загруженные файлы, а не аудиоссылки.

Конечная точка для файлов​

POST /v1/voice-gender-recognition/api

Заголовки​

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

Тело запроса​

ПолеТипОбязательноОписание
fileфайлДаАудиофайл для анализа.

Пример​

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

Версии конечной точки для файлов​

Стандартная конечная точка для файлов выше остаётся доступна для существующих интеграций. V2 и V3 предлагают дополнительные варианты анализа файлов. Они принимают один аудиофайл в multipart-поле file, обнаруживают речь и могут вернуть unknown, если пригодной речи недостаточно, вместо того чтобы всегда угадывать мужской или женский голос.

V2: анализ всей записи​

POST /v1/voice-gender-recognition/api/v2

V2 сначала проверяет наличие человеческой речи, затем классифицирует всю запись с помощью голосовой модели ECAPA-TDNN. Этот вариант подходит для записей с одним говорящим. Если говорят несколько человек, их голоса анализируются вместе; для результата по отдельному говорящему используйте V3.

Каждый успешный вызов V2 расходует 1 запрос API.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v2" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

Пример ответа при определённом поле:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 119
}

Если человеческая речь не обнаружена, V2 всё равно возвращает успешный ответ, где gender задан как unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "No clear speech was detected in the audio, so the gender could not be determined.",
"remainingRequests": 119
}

V3: анализ говорящего​

POST /v1/voice-gender-recognition/api/v3

V3 обнаруживает речь и использует диаризацию, чтобы классифицировать одного выбранного говорящего. Вариант подходит для звонков, интервью и других записей с несколькими участниками. Сначала выбирается первый говорящий; если он говорит менее 2 секунд, выбирается тот, кто говорил дольше всех. Если у выбранного говорящего менее 1 секунды речи, результатом будет unknown. V3 работает медленнее V2 и при обнаружении речи выполняет платный запрос к Deepgram.

Каждый успешный вызов V3 расходует 2 запроса API.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v3" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

Пример ответа при определённом поле:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 118
}

Если речь не обнаружена или её недостаточно у выбранного говорящего, V3 возвращает успешный ответ, где gender задан как unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "Not enough clear speech from a single speaker was detected in the audio, so the gender could not be determined.",
"remainingRequests": 118
}

В обеих версиях confidence — целое число в процентах от 0 до 100, а remainingRequests показывает остаток после списания. Результат unknown считается успешным, а не ошибкой API. Для обеих версий действуют те же API-ключ, multipart-поле, ограничение размера файла и типовые ошибки аутентификации и проверки файла, что и для стандартной конечной точки.

Конечная точка для URL​

POST /v1/voice-gender-recognition/api/url

Заголовки​

apiKey: YOUR_API_KEY
Content-Type: application/json

Тело запроса​

{
"url": "https://example.com/audio.wav"
}

Ответ​

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

{
"success": true,
"gender": "male",
"confidence": 97,
"remainingRequests": 2999
}

Для запросов с URL возвращаются прогноз и данные о квоте. Если первый запрос выполняется медленно, в ответе также может быть сообщение info.

{
"success": true,
"gender": "male",
"remainingRequests": 2999
}

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

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

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

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

{
"error": "Invalid API key"
}

Отсутствует файл​

{
"error": "No file uploaded"
}

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

{
"error": "Invalid file type. Only audio formats are allowed"
}

Недопустимый URL-запрос​

{
"error": "A valid http or https URL is required"
}

Не указан тип содержимого JSON​

{
"error": "Content-Type header is required. Please set Content-Type: application/json"
}

Неподдерживаемый тип содержимого JSON​

{
"error": "Content-Type must be application/json"
}

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

{
"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."
}
}

Примечания​

  • Для запросов с файлами используется формат multipart.
  • Для запросов с URL используется JSON.
  • Передавайте аудио в поле file; размер файла не должен превышать 10 МБ.