API определения пола по голосу
Определяет вероятный пол говорящего по загруженной аудиозаписи или URL аудиофайла.
Базовый URL
https://api.genderrecognition.com
Выберите конечную точку
| Вариант | Метод и путь | Для чего подходит |
|---|---|---|
| Стандартный анализ файла | POST /v1/voice-gender-recognition/api | Загрузка файла со стандартной обработкой. |
| Стандартный анализ URL | POST /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 МБ.