跳到主要内容

语音性别识别 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

请求正文​

字段类型必填说明
filefile是要分析的音频文件。

示例​

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。