Text-to-Speech

POST

audio

speech

curl https://gateway.bud.studio/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-tts-deployment",
    "input": "Hello, this is a test of text-to-speech."
  }' \
  --output speech.mp3

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

# `voice` is optional on Bud: leave it out to use the deployment's voice.
with client.audio.speech.with_streaming_response.create(
    model="my-tts-deployment",
    input="Hello, this is a test of text-to-speech.",
    voice=None,
) as response:
    response.stream_to_file("speech.mp3")

HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-audio-format: mp3

<binary audio>

HTTP/1.1 200 OK
Content-Type: audio/pcm
x-audio-format: linear16
x-sample-rate: 24000
x-bud-config-warning: `speed` is not applied by elevenlabs model eleven_v3 and was ignored
x-bud-config-warning-count: 1

<binary audio>

curl https://gateway.bud.studio/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-tts-deployment",
    "input": "Hello, this is a test of text-to-speech."
  }' \
  --output speech.mp3

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

# `voice` is optional on Bud: leave it out to use the deployment's voice.
with client.audio.speech.with_streaming_response.create(
    model="my-tts-deployment",
    input="Hello, this is a test of text-to-speech.",
    voice=None,
) as response:
    response.stream_to_file("speech.mp3")

HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-audio-format: mp3

<binary audio>

HTTP/1.1 200 OK
Content-Type: audio/pcm
x-audio-format: linear16
x-sample-rate: 24000
x-bud-config-warning: `speed` is not applied by elevenlabs model eleven_v3 and was ignored
x-bud-config-warning-count: 1

<binary audio>

The request and response follow OpenAI’s audio/speech API, so OpenAI SDKs work unchanged. The model is the name of your text-to-speech deployment, and the deployment decides which provider and voice model synthesize the audio.

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer authentication header
Content-Type	string	Yes	`application/json`

Body

Parameter	Type	Required	Description
model	string	Yes	Name of a text-to-speech deployment. A deployment that does not synthesize speech (a transcription deployment, for example) returns `404`.
input	string	Yes	Text to speak, up to 4096 characters. It must contain at least one letter or digit: blank input, or input made only of punctuation, symbols or emoji, is refused with `400`.
voice	string	No	A voice ID from the deployment’s provider — for example an ElevenLabs voice ID, a Deepgram `aura-2-…` voice, or `alloy` on an OpenAI deployment. Leave it out to use the deployment’s voice; see Which voice is used.
response_format	string	No	`mp3`, `opus`, `aac`, `flac`, `wav` or `pcm`. Default: `mp3`. Which of these a deployment can produce depends on its provider; see Output formats.
speed	number	No	Speaking rate, `0.25` to `4.0`. Default: `1.0`. A model that has no speed control ignores it and says so in `x-bud-config-warning`.
instructions	string	No	Accepted for compatibility with OpenAI’s SDKs, but not applied. A non-empty value adds an `x-bud-config-warning`.
stream_format	string	No	Only `audio` (one response body) is supported. `sse` is refused with `400`.
deployment settings		No	`language`, `emotion`, `stability` and the other fields in Deployment settings override the deployment’s value for this request.

Which voice is used

Checked in this order; the first one that applies wins.

Source	When
The request’s `voice`	Whenever it is set.
The deployment’s default voice	Set in the deployment’s audio settings.
The deployment’s voice description	Gender, age, accent and timbre from the audio settings, matched against the voices the provider account can use.
The provider’s default voice	When nothing above names or describes a voice.

If none of these gives a voice, the request is refused with 400 and param: "voice". Voice IDs are specific to each provider. An ID from one provider — alloy on an ElevenLabs deployment, for example — is refused with a 400 that names the voice and says how to fix it.

Output formats

`response_format`	`Content-Type`	Notes
`mp3`	`audio/mpeg`	The default.
`opus`	`audio/opus`
`aac`	`audio/aac`
`flac`	`audio/flac`
`wav`	`audio/wav`	PCM audio in a WAV container, playable as is.
`pcm`	`audio/pcm`	Raw 16-bit little-endian mono samples with no header. The sample rate is in the `x-sample-rate` response header.

Not every provider produces every format. When the deployment’s provider cannot produce the format you asked for, the request is refused with 400 and param: "response_format", and the message lists the formats that deployment can return. For example, ElevenLabs deployments return mp3, opus, wav and pcm. If a provider returns a different container from the one requested, the audio is served as returned: Content-Type and x-audio-format describe what you actually received, and an x-bud-config-warning says what changed.

Response headers

Header	Description
Content-Type	The audio’s media type; see Output formats.
x-audio-format	The format of the returned audio. Raw PCM is reported as `linear16`.
x-sample-rate	Sample rate in Hz. Sent with `pcm` output only.
x-bud-config-warning	A request or deployment setting that could not be applied. Repeated once per warning; the request still succeeds.
x-bud-config-warning-count	How many `x-bud-config-warning` headers were sent, so a client can tell “no warnings” from “a proxy removed them”.

Deployment settings

Everything on a deployment’s Settings → Audio page is a default for every request to that deployment. The page shows only the settings the deployment’s provider and model support. A saved setting that the provider cannot apply is skipped with an x-bud-config-warning, and the request still succeeds. A request can override most of them for itself, using the field in the last column. The rest are operational settings that only the deployment controls. See Overriding settings per request.

Setting	What it does	Request field
Default voice	The voice used when the request has no `voice`.	`voice`
Default language	The language the text is spoken in, converted to the provider’s own language code.	`language`
Emotion, Intensity	An emotion to speak with (for example `happy`, `calm`) and how strongly: a number from 0.0 to 1.0, or `low`, `medium` or `high`. On providers that support emotions.	`emotion`, `emotion_intensity`
Delivery style	A speaking style (for example `whispered`, `newscast`), on providers that have styles.	`delivery_style`
Gender, Age, Locale, Accent, Timbre hint	Describe a voice instead of naming one. Used when neither the request nor Default voice names a voice, to pick a matching voice from the provider account’s own voices. Offered only when the provider lists the account’s voices.	`voice` (a named voice wins)
Sample rate	Sample rate of `pcm` output, in Hz: 8000, 16000, 22050, 24000, 44100 or 48000. Reported in `x-sample-rate`. Other formats use the provider’s rate.	`sample_rate`
Pitch, Volume	Absolute pitch and loudness adjustments, in the provider’s own range.	`pitch`, `volume`
Rate change, Pitch change	Relative changes, −50 % to +50 %.	`rate_percentage`, `pitch_percentage`
Stability, Similarity boost, Style amount, Speaker boost	Voice settings in the ElevenLabs style: consistency, closeness to the reference voice, style exaggeration (each 0 to 1), and speaker similarity boost (true/false).	`stability`, `similarity_boost`, `style`, `use_speaker_boost`
Latency tier	The provider’s latency-for-quality trade-off (ElevenLabs’ `optimize_streaming_latency`). `eleven_v3` does not support it and answers with a warning.	deployment only
Prefer the streaming endpoint	Synthesize over the provider’s WebSocket endpoint where it has one (Deepgram).	deployment only
Replacements	Word → replacement pairs applied to `input` before synthesis, matching whole words only, for example to spell out how a name is pronounced.	`pronunciations`

speed has no saved default: the request’s value, or the provider’s own default, is used.

Overriding settings per request

The fields in the table above are Bud additions to OpenAI’s request. All of them are optional, and a request that leaves them out gets the deployment’s settings, so plain OpenAI clients work unchanged. Each field applies to its own request only:

curl https://gateway.bud.studio/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-tts-deployment",
    "input": "Welcome back!",
    "emotion": "happy",
    "emotion_intensity": "high",
    "stability": 0.3,
    "pronunciations": [{ "word": "Bud", "pronunciation": "bʌd" }]
  }' \
  --output speech.mp3

With an OpenAI SDK, pass them through the SDK’s extra-fields option, for example extra_body={"stability": 0.3} in Python.

A value that is out of range or not in the vocabulary is refused with 400 naming the field. Examples: stability above 1, an unknown emotion, or a sample_rate not in the list above.
A field the deployment’s provider cannot use is skipped with an x-bud-config-warning, as a saved setting would be.
pronunciations add to the deployment’s list. On the same word, the request’s entry wins.
A field nothing recognises, such as a misspelling, is ignored and named in an x-bud-config-warning.

Errors

Errors use OpenAI’s error format; param names the field at fault when there is one.

400

{
  "error": {
    "message": "elevenlabs cannot produce aac audio; `response_format` must be one of mp3, opus, wav, pcm",
    "type": "invalid_request_error",
    "param": "response_format",
    "code": null
  }
}

Status	When
`400`	A missing or invalid field; a format or voice the provider cannot use; the provider refused the request (the provider’s own message is included).
`401`	Missing or invalid API key. `code` is `missing_auth_header` or `unauthorized`.
`404`	`model` is not a deployment you can use, or does not support text-to-speech.
`500`	The deployment is misconfigured, for example it has no provider credential.
`502`	The provider failed, or returned audio that could not be packaged.
`504`	Synthesis took longer than the deployment’s request timeout.

Supported providers

Any text-to-speech deployment works with this endpoint. The model catalog currently offers text-to-speech models from ElevenLabs, Deepgram, Cartesia, OpenAI, Azure, Amazon Polly, Google Cloud Text-to-Speech and Speechmatics.

curl https://gateway.bud.studio/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-tts-deployment",
    "input": "Hello, this is a test of text-to-speech."
  }' \
  --output speech.mp3

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

# `voice` is optional on Bud: leave it out to use the deployment's voice.
with client.audio.speech.with_streaming_response.create(
    model="my-tts-deployment",
    input="Hello, this is a test of text-to-speech.",
    voice=None,
) as response:
    response.stream_to_file("speech.mp3")

HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-audio-format: mp3

<binary audio>

HTTP/1.1 200 OK
Content-Type: audio/pcm
x-audio-format: linear16
x-sample-rate: 24000
x-bud-config-warning: `speed` is not applied by elevenlabs model eleven_v3 and was ignored
x-bud-config-warning-count: 1

<binary audio>

Introduction

Gateway APIs

Python SDK & CLI

Headers

Body

Which voice is used

Output formats

Response headers

Deployment settings

Overriding settings per request

Errors

Supported providers

​Headers

​Body

​Which voice is used

​Output formats

​Response headers

​Deployment settings

​Overriding settings per request

​Errors

​Supported providers

Headers

Body

Which voice is used

Output formats

Response headers

Deployment settings

Overriding settings per request

Errors

Supported providers