Speech (Text-to-Speech) API Usage Guide

Turn text into spoken audio. Send a JSON body, receive the audio file itself — one request, one audio object, no polling and no URL to fetch afterwards.

Voices are chosen in two ways: by name (female, male, or a voice id from the voicing document), or by description — a voice_descriptor saying the gender, tone, expressiveness and pace you want, which the service maps to one of its voices.

#Quickstart

curl https://api.radienthq.com/v1/tools/speech \
  -H "Authorization: Bearer $RADIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from Radient."}' \
  --output speech.mp3

speech.mp3 is a playable MP3 — that is the default format. The default voice is female and the default model is eleven_multilingual_v2.

The response headers tell you what you got:

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Radient-Speech-Map: 1.0

#Request body

An example with the two most useful overrides:

curl https://api.radienthq.com/v1/tools/speech \
  -H "Authorization: Bearer $RADIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Bonjour.", "model": "eleven_flash_v2_5", "language_code": "fr", "voice": "male"}' \
  --output bonjour.mp3

#Voice control

Instead of naming a voice, describe the one you want and let the service map the description onto its voice pool:

curl https://api.radienthq.com/v1/tools/speech \
  -H "Authorization: Bearer $RADIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hi.", "voice_descriptor": {"gender": "male", "tone": "calm", "expressiveness": "low"}}' \
  --output hi.mp3

The descriptor vocabulary and its mapping notes are published as a public JSON document — no key required:

curl https://api.radienthq.com/v1/tools/speech/voicing

It lists the descriptor fields and their defaults, the tone vocabulary, and, for each serving voice, which fields are honoured, emulated or ignored. If your product depends on a specific mapping, read map_version / descriptor_version from this document and record them — the mapping can evolve, and every descriptor call reports the version it used.

A descriptor request reports the mapping in the response headers:

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Radient-Speech-Map: 1.0
X-Radient-Speech-Voice: m-warm
X-Radient-Speech-Applied: gender,tone,expressiveness,pace,language,accent,instructions

#Response

A successful call returns 200 OK with the audio file as the body and Content-Type: audio/mpeg. Additional diagnostic headers may be present; only those above are part of the documented contract. Audio is returned in one response (never a chunked stream) and the platform will not read more than 25 MiB from the voice service — a request that would exceed that fails rather than returning a truncated clip.

#What you were charged

The audio response reports its charge as X-Radient-Cost-* headers — the same cost object other surfaces carry in the body, rendered as headers because this body is the audio itself. From a live call:

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Radient-Cost-Version: 1
X-Radient-Cost-Amount-Usd: 0.001
X-Radient-Cost-Basis: billed
X-Radient-Cost-Unit: char
X-Radient-Cost-Units: 25
X-Radient-Cost-Usage-Record-Id: 6acabfcf80f7de3d24c98268
X-Radient-Cost-Provider: elevenlabs
X-Radient-Cost-Model: eleven_flash_v2_5
X-Radient-Cost-Price-Version: speech-rates@2026-09-30

X-Radient-Cost-Amount-Usd is what the call charged, deducted from your balance — the shortest round-trip decimal, never exponent notation. X-Radient-Cost-Units is the billed character count, X-Radient-Cost-Usage-Record-Id joins the charge to the usage and ledger surfaces, and Provider, Model and Price-Version are omitted when they do not apply.

#Pricing

Speech is metered per character of input:

A maximum-size request on the default model (10,000 characters) costs $0.80, and the cheapest model costs $0.10 for the same text. The charge is written to your Radient Pass balance when the call settles; calls that fail are not charged. See Radient Pass for balances and top-ups.

#Errors

Real bodies (trimmed where they name an internal service; … marks the trim):

{"error":"[bad_request] Invalid request parameters: Key: 'SpeechRequest.Input' Error:Field validation for 'Input' failed on the 'required' tag"}

{"code":"speech_rejected","error":"Unsupported speech model \"nope\" for provider \"…\". Supported: eleven_flash_v2_5, eleven_multilingual_v2."}

{"code":"speech_rejected","error":"Response format \"opus\" is not available with provider \"…\"; only \"mp3\" is."}

{"code":"speech_rejected","error":"voice_descriptor.gender cannot be \"auto\": the hub has no agent context to classify; resolve it client-side and send \"female\" or \"male\""}

{"error":"missing Authorization header"}

{"error":"insufficient credits"}

A 400 caused by a rejected model or format costs nothing — the request never reaches synthesis.

#Tips

• mp3 is the format with the widest playback support, and today it is the only one the default voice serves.
• Keep requests under the 10,000-character limit; chunk longer scripts client-side and concatenate the audio yourself.
• Cache clips you regenerate often — identical input costs the same every time.
• Pick the cheapest model that meets your quality bar: eleven_flash_v2_5 is half the default's price, gpt-4o-mini-tts an eighth.

For the full endpoint list, see the API Reference.