Text-to-speech API

Synthesize speech from a string with the OpenAI-compatible speech endpoint, including streaming and audio formats.

POST /v1/audio/speech follows the OpenAI speech shape. If you already call OpenAI for text to speech, change the base URL and the model.

model takes a text-to-speech model id from Models.

Synthesize speech

curl https://api.sprag.ai/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -d '{
    "model": "chorus",
    "input": "The quarterly numbers are in and they look good.",
    "voice": "marin",
    "response_format": "mp3"
  }' \
  --output out.mp3

The response body is the audio itself, not JSON.

Request fields

Field	Required	Type	Notes
`model`	Yes	string	A text-to-speech model id, such as `chorus`.
`input`	Yes	string	The text to speak.
`voice`	No	string	A preset id, or the id of a voice your organization created.
`instructions`	No	string	Style guidance on how the voice reads. Accepted for voices whose model supports it.
`response_format`	No	string	`mp3`, `opus`, `flac`, `wav`, or `pcm`.
`speed`	No	number	Speaking rate multiplier, `0.25` to `4.0`.
`language`	No	string	Output language. See languages.
`stream_format`	No	string	`sse` or `audio`. Omit to receive the whole clip at once.
`ref_audio`	No	string	Inline `data:` URL of reference audio, for cloning.
`ref_text`	No	string	Transcript of that reference audio.
`temperature`	No	number	Sampling temperature, `0` to `2`.
`top_p`	No	number	Nucleus sampling probability mass, `0` to `1`.
`top_k`	No	integer	Number of top candidates sampled from, `0` or greater.

Set response_format to the container the player or store on your side expects. Omit speed for the voice's natural rate, and omit temperature, top_p, and top_k for the model's default sampling.

Voices

GET /v1/audio/voices takes a model query parameter and lists its presets, followed by the voices your organization created.

curl "https://api.sprag.ai/v1/audio/voices?model=chorus" \
  -H "Authorization: Bearer $SPRAG_API_KEY"

To design or clone a voice, see Voices.

Streaming

Set stream_format to start playback before generation finishes.

`stream_format`	Delivery
omitted	One buffered response after generation finishes.
`audio`	Raw chunked audio as it is generated.
`sse`	`speech.audio.delta` and `speech.audio.done` events.

Streaming is available with pcm and wav. Use pcm when the bytes feed another pipeline and wav when the far end requires a container. Audio formats covers the choice in full.

To speak many utterances over one connection, such as each sentence of a voice agent's reply, see Text to speech over a WebSocket.

Rate limits

Rate limits apply per organization. Rate limits has the headers and retry guidance.

Errors

Status	Meaning
`400`	Validation error: an unknown `voice`, a field the voice's model does not accept, or a value outside an enum.
`401`	Missing, invalid, or expired credentials.
`402`	Out of credit. Also sent with the code `payment_overdue` when a plan invoice is unpaid. Also sent while billing for a new account is being set up; retry the request after a moment.
`403`	Not a member of the requested organization.
`404`	No model by that name.
`413`	Request too large.
`429`	Rate limit exceeded.