Skip to content
ResponsiveVoice

Get voice by name

GET
/v2/voices/{name}
 
curl https://texttospeech.responsivevoice.org/v2/voices/UK%20English%20Female -H 'X-API-Key: YOUR_API_KEY' -H 'X-API-Secret: YOUR_API_SECRET'

Returns a specific voice by its exact name (e.g. “UK English Female”). The response includes HATEOAS _links with a self link, a synthesize link for generating audio with this voice, and a stream link for real-time streaming synthesis.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
name
required
string

Exact voice name (e.g. “UK English Female”, “US English Male”). URL-encode spaces as %20.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Voice details with HATEOAS navigation links (self, synthesize, stream). Supports ETag-based conditional requests.

Media type application/json

Single voice detail with HATEOAS navigation

object
voice
required

User-facing voice definition

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 detail response

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
collection
required

HATEOAS link with absolute URL

object
href
required
string
byLanguage
required

HATEOAS link with absolute URL

object
href
required
string
Example 
{
  "voice": {
    "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 — the resource has not changed since the last request (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"
  }
}

404

Section titled “404 ”

No voice found with the given name

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.