Skip to navigation
API ReferenceVoices

List Voices

Lists the voices available to the caller - the shared voice catalog plus the cloned voices they can reach, whichever member or service-account key created them. A clone filed under a project is listed only for a caller who can reach that project; a clone no project filed is shared with the whole workspace and is listed for everyone in it. By default the full catalogue is returned in one response. Pagination is opt-in: pass limit (and then cursor from the previous response) to page through the list while has_more is true. Max page size is 200. Narrow the list with the type and locale filters.

A page can come back with fewer than limit voices, and a short page - an empty one included - is not the end of the list. Keep following next_cursor while has_more is true.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. 'Bearer sk_...'.

Headers

Speechify-VersionstringOptional

Query parameters

cursorstringOptional
Opaque pagination cursor from a previous response.
limitintegerOptional1-200Defaults to 50

Max items per page (default 50, max 200).

typeenumOptional

Filter by voice type: personal (the workspace's cloned voices) or shared (the public catalogue). Omit to return both.

Allowed values:
localestringOptional

Filter to voices whose locale matches this BCP-47 language range, prefix-matched: en matches en-US and en-GB; en-US matches only en-US. Case-insensitive. Omit to return all locales.

genderenumOptional
Filter by voice gender. Omit to return all genders.
Allowed values:
modelstringOptional

Filter to voices that support this model (as listed in each voice's models[]), e.g. simba-3.2. Omit to return voices for all models.

project_idstringOptional

Filter cloned voices by workspace project: omit for every voice you can reach, pass the literal shared for the clones no project filed, or a proj_... id for the clones filed under that project. The shared catalog carries no project and is returned either way.

A clone is filed under a project when a project-pinned key created it. A clone with no project is shared with the whole workspace rather than sitting in a Default project, so the literal here is shared, never default - passing default is a 400. Returns 404 project_not_found for a malformed id and for any project outside your reach: a project-pinned key reaches only its pinned project, and a member holding project grants reaches only the granted ones. That 404 is the same in every case and does not reveal whether such a project exists. shared is always inside your reach.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

  • it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

RateLimit-LimitintegerOptional

Request-rate budget: the maximum number of requests in the current window (the bucket capacity). The IETF-draft un-prefixed name; the legacy alias X-RateLimit-Limit carries the same value. Rides every response.

RateLimit-RemainingintegerOptional

Request-rate budget: requests left in the current window. Legacy alias: X-RateLimit-Remaining.

RateLimit-ResetintegerOptional

Request-rate budget: integer delta-seconds until the window fully refills (same unit as Retry-After). Legacy alias: X-RateLimit-Reset.

Response

The voice catalogue (or a page of it when limit is set).

next_cursorstring or null

Opaque keyset cursor for the next page. Pass back as the cursor request parameter. null when the caller has reached the end of the list (has_more is also false in that case).

has_moreboolean
True when more rows exist beyond this page.
voiceslist of objects

Errors

400
Bad Request Error

The request was malformed or failed validation. The response body is the standard Error envelope; for validation failures error.fields enumerates the offending fields as a path -> message map (code = validation_failed).

HeaderSpeechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

  • it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

errorobject
request_idstringOptional

Server-side request identifier. Echoes the Speechify-Request-Id response header. Stable across the request's lifetime, written to structured logs, and useful when reporting issues.

401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error