语音性别识别 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 格式的音频 URL。V2 和 V3 仅接受上传文件,不接受音频 URL。
文件端点
POST /v1/voice-gender-recognition/api
请求标头
apiKey: YOUR_API_KEY
Content-Type: multipart/form-data
请求正文
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | 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 MB。