Gender by Voice API

Detect likely speaker gender from uploaded audio or from an audio URL.

Base URL

https://api.genderrecognition.com

Choose an endpoint

Option	Method and path	Best for
Standard file analysis	POST /v1/voice-gender-recognition/api	Simple file uploads using the standard analysis behavior.
Standard URL analysis	POST /v1/voice-gender-recognition/api/url	An audio file available at a public URL.
V2 whole-clip analysis	POST /v1/voice-gender-recognition/api/v2	Speech-aware analysis when the recording has one speaker.
V3 speaker-aware analysis	POST /v1/voice-gender-recognition/api/v3	Calls, interviews, and other multi-speaker recordings.

The standard URL endpoint accepts a JSON URL. V2 and V3 accept uploaded files only; they do not accept audio URLs.

File endpoint

POST /v1/voice-gender-recognition/api

Headers

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

Body

Field	Type	Required	Description
file	file	Yes	Audio file to analyze.

Example

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

Versioned file endpoints

The standard file endpoint above remains available for existing integrations. V2 and V3 are additional file-analysis options. They accept one audio file in the multipart file field, check for speech, and can return unknown when there is not enough usable speech instead of always guessing male or female.

V2: Whole-clip analysis

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

V2 checks for human speech, then classifies the full recording with the ECAPA-TDNN voice model. It is intended for recordings with one speaker. If there are multiple speakers, their voices are analyzed together; use V3 when you need a speaker-aware result.

Each successful V2 request consumes 1 API request.

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

Example response when speech is detected:

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

When no human speech is detected, V2 still returns a successful response, with gender set to 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: Speaker-aware analysis

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

V3 detects speech and uses speaker diarization to classify one selected speaker, making it suitable for calls, interviews, and other multi-speaker recordings. It selects the first speaker unless that speaker talks for less than 2 seconds; in that case, it selects the speaker with the most speaking time. If the selected speaker has less than 1 second of speech, the result is unknown. V3 takes longer than V2 and makes a paid Deepgram request when speech is detected.

Each successful V3 request consumes 2 API requests.

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

Example response when a speaker is classified:

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

When speech is missing or too short for the selected speaker, V3 returns a successful response with gender set to 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
}

For both versions, confidence is a whole-number percentage from 0 to 100, and remainingRequests reflects the account balance after the request charge. Unknown is a successful prediction result, not an API error. The endpoint uses the same API key header, multipart field name, upload size limit, and common authentication and file-validation errors as the V1 file endpoint.

URL endpoint

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

Headers

apiKey: YOUR_API_KEY
Content-Type: application/json

Body

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

Response

File requests return the prediction, confidence as a percentage, and updated quota metadata.

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

URL requests return the prediction and quota metadata. Slow first requests may also include an info message.

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

Error cases

Missing API key

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

Invalid API key

{
  "error": "Invalid API key"
}

Missing file

{
  "error": "No file uploaded"
}

Invalid file type

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

Invalid URL request

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

Missing JSON content type

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

Unsupported JSON content type

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

Quota exceeded

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

Notes

• File requests use multipart form data.
• URL requests use JSON.
• Audio uploads use the file field and must be 10 MB or smaller.