Synthesize text to speech (POST)

POST

/v2/text/synthesize

Code sample: cURL

curl -X POST https://texttospeech.responsivevoice.org/v2/text/synthesize \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","voice":"US English Female"}' \
  --output speech.mp3

• Production

Converts text to speech audio via JSON request body. To enable real-time streaming, set the Accept: text/event-stream header — audio is streamed progressively as it is synthesized (HTTP audio streaming). Streaming requires a premium engine (gwn, msv, or oai) with BYOK credentials configured. Without the streaming header, returns complete audio as a single binary response. POST responses are not CDN-cached (Cache-Control: public, max-age=86400 only).

Authorizations

• apiKeyHeader
• apiSecretHeader

Request Body ^required

Media type application/json

Text-to-speech synthesis request

object

text

required

string

voice

string

lang

string

engine

Available TTS service backends

string

Allowed values: g1 g2 g3 g5 gwn msv oai

name

string

gender

Voice gender classification

string

Allowed values: male female

pitch

number

<= 2

rate

number

<= 2

volume

number

<= 1

format

Supported audio output formats

string

Allowed values: mp3 ogg wav

Responses

200

Audio binary data (non-streaming) or an HTTP audio stream (when Accept: text/event-stream is set). Includes RV-Cached header, X-Streaming header for streaming responses, and RV-Prosody-Applied listing knobs the server applied upstream.

Media type audio/mpeg

string format: binary

Headers

RV-Prosody-Applied

required

Comma-separated subset of {pitch, rate, volume} the server applied upstream for this call.

string

Comma-separated subset of {pitch, rate, volume} the server applied upstream for this call.

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.

204

No content — returned when volume=0 was requested; the server skips upstream synthesis entirely.

Headers

RV-Prosody-Applied

required

Always “volume” for 204 responses.

string

Always “volume” for 204 responses.

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.

400

Invalid synthesis request — missing required fields, invalid JSON, or parameter validation failure

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

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

No provider available for the requested engine, or no streaming provider for streaming requests

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

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

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.

502

Upstream TTS provider returned an error during synthesis

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