Skip to main content
POST
Create a speech

Authorizations

Authorization
string
header
required

Your Boson API key, sent as Authorization: Bearer $BOSON_API_KEY.

Body

input
string
required

Text to convert to speech. Up to 5,000 characters, or 50,000 with stream: true; longer input returns 400 input_too_long. May contain inline control tags, which don't count toward this limit. Must contain at least one letter or number outside control tags; input with nothing to say, such as ... or tags alone, returns 400 invalid_field_value. A <|...|> that isn't a documented control tag returns 400 invalid_field_value naming it. Long input is split at natural boundaries and synthesized in full.

Required string length: 1 - 50000
Example:

"Hello, this is a test."

model
enum<string>
default:higgs-tts-3

TTS model ID / public alias. Resolved to the served model server-side.

Available options:
higgs-tts-3
voice
string
default:default

Preset voice name or custom voice ID. Mutually exclusive with ref_audio / ref_text when explicitly provided.

response_format
enum<string>
default:mp3

Output audio format. Streaming requires pcm.

Available options:
mp3,
opus,
pcm,
wav,
aac,
flac
stream
boolean
default:false

If true, stream raw PCM chunks as they are decoded. With timestamps: true, the stream is Server-Sent Events (text/event-stream) carrying the PCM and the timestamps instead. Requires response_format to be pcm. Raises the input limit to 50,000 characters, so use it for long input.

ref_audio
string | null

Inline reference audio for one-off cloning: an http(s) URL, data URI, or base64-encoded raw audio bytes. Supported formats: AAC, WAV, MP3, FLAC, OPUS. Inline (base64 / data-URI) payloads: max 10 MB.

ref_text
string | null

Recommended transcript of ref_audio.

normalize
boolean
default:true

Expand non-standard words into spoken form before synthesis, including numbers, dates, times, currency, units, URLs, email addresses, phone numbers, abbreviations, and symbols. Enabled by default; set to false to synthesize the text exactly as written. Text with nothing to normalize is passed through unchanged. Inline tags are preserved. The old name enable_tn is no longer recognized and is ignored, so sending enable_tn: false leaves normalization on.

language
string | null

ISO 639-3 language code of the input text, for example eng (English) or cmn (Mandarin Chinese). Used for text normalization. Defaults to null, in which case normalization infers the language from the text; set it when you know the language for the most reliable results. An unsupported code returns 400 invalid_field_value, including when normalization is disabled. Only ISO 639-3 codes are accepted, in any letter case. A few alternative ISO 639-3 codes are also accepted, such as zho for Chinese and arb for Arabic. The old field name tn_language is no longer recognized and is ignored.

timestamps
boolean
default:false

Attach token timestamps: the time each token of input is spoken, and its position in input. The response becomes a JSON envelope carrying the timestamps and the audio base64-encoded in the requested response_format, instead of raw audio bytes. With stream: true, it is Server-Sent Events carrying PCM chunks and timestamp entries instead of raw PCM. Works with long input and with normalize: entries are always on input as sent. See Timestamps.

Response

Generated audio. The content type depends on response_format, and a streamed response is raw PCM. With timestamps: true, the response is application/json instead, carrying the audio base64-encoded alongside the timestamps; streamed, it is text/event-stream.

The response is of type file.