Skip to main content

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.

FieldTypeRequiredBehaviour
inputStringYesNon-empty text, at most 2,000 characters. Split longer scripts into separate requests.
voiceStringNoA supported voice ID below. Defaults to af_heart.
formatStringNomp3 (default), wav, opus, or flac.
speedNumberNoFrom 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 groupIDs
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 as audio/mpeg for 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_REQUEST with 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.