Synthesise speech
POST /projects/:projectid/audio/speech
Turns text into spoken audio. The successful response contains audio bytes, not a JSON object or a download URL.
Authentication and request
Use a project key with speech.synthesize in Authorization, without Bearer. Replace :projectid with the key's project ID and send Content-Type: application/json.
| Field | Type | Required | Behaviour |
|---|---|---|---|
input | String | Yes | Non-empty text, at most 2,000 characters. Split longer scripts into separate requests. |
voice | String | No | A supported voice ID below. Defaults to af_heart. |
format | String | No | mp3 (default), wav, opus, or flac. |
speed | Number | No | From 0.5 to 2, inclusive. Defaults to 1. |
There is no model-tier selection. The available voices are English voices.
Available voices
Use the exact ID, not a display name:
| Accent / voice group | IDs |
|---|---|
American, af_ | af_alloy, af_aoede, af_bella, af_heart, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky |
American, am_ | am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck, am_santa |
British, bf_ | bf_alice, bf_emma, bf_isabella, bf_lily |
British, bm_ | bm_daniel, bm_fable, bm_george, bm_lewis |
Example
Using the Quickstart variables:
curl --fail --silent --show-error --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"input":"Your report is ready to download.","voice":"bf_emma","format":"mp3","speed":1}' \
--output "./report-ready.mp3" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/audio/speech"
Choose an output filename that will not overwrite something you need. Do not add --include when saving audio: it would mix HTTP headers into the audio file. To inspect headers, use your HTTP client or save them separately.
Response
200 OK contains the generated clip. Response headers include:
Content-Type: the audio MIME type, such asaudio/mpegfor MP3.Content-Length: the byte length of the clip.X-Audio-Duration-Seconds: the audio duration in seconds when available.Cache-Control: no-store.
The response is a complete audio clip, not chat SSE. No Library file is created automatically. If you want to retain the clip in your project, upload it to the Library.
Errors
- 400: missing/empty/overlong text, unknown voice or format, or speed outside the allowed range. JSON uses
BAD_REQUESTwith a message. - 401: missing or invalid project credential.
- 403: missing
speech.synthesize. - 429: request-rate limit reached.
- 502: speech generation failed, returned as
UPSTREAM_FAILURE.
Check the HTTP status before playing or storing a response as audio: errors can be JSON or plain text. For longer scripts, split at natural sentence boundaries and preserve clip order in your application.