Skip to content
ResponsiveVoice

Get voices by language

GET
/v2/voices/by-language/{lang}
 
curl https://texttospeech.responsivevoice.org/v2/voices/by-language/en-US -H 'X-API-Key: YOUR_API_KEY' -H 'X-API-Secret: YOUR_API_SECRET'

Returns all voices available for a specific BCP-47 language code (e.g. “en-US”, “pt-BR”, “ja-JP”). Includes both free and premium voices. Each voice includes HATEOAS _links for navigation.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
lang
required
string

BCP-47 language code (e.g. “en-US”, “fr-FR”, “zh-CN”). Case-sensitive.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Voices matching the requested language, with count and HATEOAS navigation links. Supports ETag-based conditional requests.

Media type application/json

Voices for a specific language with HATEOAS navigation

object
language
required
string
voices
required
Array<object>

User-facing voice with HATEOAS links

object
name
required
string
flag
required
string
gender
required
string
Allowed values: f m
lang
required
string
voiceIDs
required
Array<number>
deprecated
boolean
isByok
boolean
provider
string
_links
required

HATEOAS links on a voice resource

object
self
required

HATEOAS link with absolute URL

object
href
required
string
synthesize
required

HATEOAS synthesize action link

object
href
required
string
method
required
string
Allowed values: POST
body
required
object
voice
required
string
lang
string
synthesize:stream
required

HATEOAS streaming synthesize link (HTTP audio streaming)

object
href
required
string
method
required
string
Allowed values: POST
body
required
object
voice
required
string
lang
string
stream
required
boolean
accept
required
string
Allowed values: text/event-stream
premium
required
boolean
stream:websocket
required

HATEOAS WebSocket stream link

object
href
required
string
protocol
required
string
Allowed values: websocket
message
required
object
type
required
string
voice
required
string
lang
string
premium
required
boolean
count
required
number
_links
required

HATEOAS links on a by-language voice collection

object
self
required

HATEOAS link with absolute URL

object
href
required
string
allVoices
required

HATEOAS link with absolute URL

object
href
required
string
Example 
{
  "voices": [
    {
      "gender": "f",
      "_links": {
        "synthesize": {
          "method": "POST"
        },
        "synthesize:stream": {
          "method": "POST",
          "accept": "text/event-stream"
        },
        "stream:websocket": {
          "protocol": "websocket"
        }
      }
    }
  ]
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
required

Maximum requests permitted for the authenticated key per minute.

integer

Maximum requests permitted for the authenticated key per minute.

X-RateLimit-Remaining
required

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

integer

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

304

Section titled “304 ”

Not modified (ETag match)

401

Section titled “401 ”

API key required

Media type application/json

API error response

object
error
required
object
message
required
string
code
string
statusCode
required
number
errors
Example generated
{
  "error": {
    "message": "example",
    "code": "example",
    "statusCode": 1,
    "errors": "example"
  }
}

429

Section titled “429 ”

Rate limit exceeded. The body code is RATE_LIMIT_EXCEEDED (per-minute tier limit) or BURST_RATE_LIMIT_EXCEEDED (per API key + client IP burst).

Media type application/json

API error response

object
error
required
object
message
required
string
code
string
statusCode
required
number
errors
Example generated
{
  "error": {
    "message": "example",
    "code": "example",
    "statusCode": 1,
    "errors": "example"
  }
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
required

Maximum requests permitted for the authenticated key per minute.

integer

Maximum requests permitted for the authenticated key per minute.

X-RateLimit-Remaining
required

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

integer

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

Retry-After
required

Seconds to wait before retrying. Dynamic — varies with how far over the limit the request went; honor this header rather than assuming a fixed delay.

integer

Seconds to wait before retrying. Dynamic — varies with how far over the limit the request went; honor this header rather than assuming a fixed delay.