Get shared voices
Retrieves the shared voices built into a TTS model, optionally filtered by gender, age, accent, use case and style. All given filters must match. For the voices you have cloned yourself, see `GET /v1/voices` instead.
Retrieves the shared voices built into a TTS model, optionally filtered by gender, age, accent, use case and style. All given filters must match. For the voices you have cloned yourself, see GET /v1/voices instead.
Headers
AuthorizationRequiredBearer <SONIOX_API_KEY>Query parameters
modelRequiredstringId of the TTS model whose voices to return.
64genderstringOnly return voices of this gender.
agestringOnly return voices of this age.
accentstringOnly return voices with this accent.
40use_casearray<string>Only return voices tagged with every listed use case. Repeat the parameter to pass several values, or separate them with commas.
stylearray<string>Only return voices tagged with every listed style. Repeat the parameter to pass several values, or separate them with commas.
limitintegerMaximum number of voices to return.
100Minimum: 1Maximum: 200cursorstringPagination cursor for the next page of results. Pass the same filters alongside it; the cursor points into the filtered list, not the whole catalogue.
Response
200
List of shared voices matching the filters.
voicesRequiredarray<object>List of voices matching the filters.
next_page_cursorstringA pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available.
Errors
List of shared voices matching the filters.
{
"voices": [
{
"id": "Maya",
"description": "A steady, clear voice with a natural presence and measured delivery that feels confident, warm, and easy to listen to.",
"gender": "female",
"age": "middle_aged",
"accent": "british",
"use_case": [
"conversational"
],
"style": [
"smooth",
"confident",
"neutral"
]
},
{
"id": "Victoria",
"description": "A poised female voice with a refined British accent, smooth pacing, and a lightly textured tone that feels elegant, confident, and composed.",
"gender": "female",
"age": "middle_aged",
"accent": "british",
"use_case": [
"educational",
"narration",
"conversational"
],
"style": [
"formal",
"bright",
"confident",
"neutral",
"calm"
]
}
],
"next_page_cursor": "cursor_or_null"
}Invalid request.
Error types:
invalid_request: Themodelparameter is missing, or a filter or pagination value is invalid (unknowngenderorage, a value longer than 40 characters, more than 10use_case/stylevalues, orlimitoutside 1-200). Inspectvalidation_errors.invalid_cursor: Thecursorparameter is invalid. Omitcursorto start pagination from the beginning.
{
"status_code": 400,
"error_type": "invalid_request",
"message": "Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values.",
"validation_errors": [
{
"error_type": "enum",
"location": "query.gender",
"message": "Input should be 'male', 'female' or 'neutral'"
}
],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
"more_info": "https://soniox.com/docs/api-reference/errors#invalid-request"
}Authentication error.
{
"status_code": 401,
"error_type": "unauthenticated",
"message": "Incorrect API key provided. You can get an API key at https://console.soniox.com",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
"more_info": "https://soniox.com/docs/api-reference/errors#unauthenticated"
}TTS model not found.
Error types:
invalid_request: No TTS model with this id exists. List the available models withGET /v1/tts-modelsand retry with one of their ids.
{
"status_code": 404,
"error_type": "invalid_request",
"message": "TTS model 'tts-rt-v0' not found.",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
"more_info": "https://soniox.com/docs/api-reference/errors#invalid-request"
}Rate / capacity limit exceeded.
Error types:
limit_exceeded: The caller hit a per-minute request rate limit for model listing. Themessagedescribes which limit was hit.
{
"status_code": 429,
"error_type": "limit_exceeded",
"message": "Requests per minute limit for model listing has been exceeded for your organization.",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
"more_info": "https://soniox.com/docs/api-reference/errors#limit-exceeded"
}Internal server error.
{
"status_code": 500,
"error_type": "internal_error",
"message": "The server encountered an error. Please try again. If the issue persists contact support@soniox.com.",
"validation_errors": [],
"request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
"more_info": "https://soniox.com/docs/api-reference/errors#internal-error"
}