Text to speech
POST /v1/audio/speech converts plain text to audio through an enabled speech provider. Provider models keep their provider identity. Eligible keys in your account are tried first and billed by your provider. When no usable BYOK key is available, or safe BYOK retries are exhausted, RelayOn uses its keys and charges your balance at the published rate, subject to access rules and spending limits.
curl https://relayon.app/v1/audio/speech \
-H "Authorization: Bearer ro_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: speech-001" \
-d '{"model":"google/gemini-3.8-flash-tts","input":"Selamat pagi dari RelayOn.","voice":"Kore","max_output_tokens":512,"response_format":"wav"}' \
--output speech.wav| Parameter | Type | Default | Description |
|---|---|---|---|
| model | string | required | An available speech synthesis model. |
| input | string | required | Plain text. Limits and billing dimensions depend on the provider; text bytes, text tokens and audio tokens are different quantities. |
| voice | string | required | A voice ID listed in the selected model’s tts.voices. |
| language | string | model default | Use a language from tts.languages, or auto when tts.auto_language is true. |
| response_format | string | model default | Select a format from the model’s tts.formats list. Set it explicitly to match the output file. |
| style | string | optional | Separate delivery instructions where supported, up to 2,000 UTF-8 bytes. |
| max_output_tokens | integer | model maximum | Audio-token ceiling bounded by the selected model. Also limits the output portion of the reservation. |
| speed | number | 1 | Currently only normal speed (1). Unsupported controls are rejected before billing. |
No serving-mode parameter or default setting is needed. Provider TTS tries each eligible BYOK key at most once within the request deadline before eligible paid fallback. Explicit credential, permission, quota and rate-limit rejections can permit fallback; ambiguous timeouts do not, to prevent duplicate generation. Existing idempotent requests retain their recorded billing outcome even if your keys change.
The example requests WAV audio. Check the selected model’s formats, voices, capabilities and published billing dimensions before sending it. For token-metered speech, X-Usage-Input-Tokens and X-Usage-Output-Audio-Tokens report usage; X-Audio-Duration-Seconds reports duration. X-Credits-Charged reports the settled RelayOn charge, which is zero for BYOK.
Requests require a session or RelayOn API key and obey the applicable account and API-key limits. Workspace restrictions apply to requests made through that workspace. For paid requests, an estimated charge is held from your RelayOn balance before synthesis; BYOK requests do not reserve that balance. If audio is generated but settlement is delayed, the response carries X-Billing-Status: pending; settlement resumes without generating audio again. Streaming, SSML, custom voices and multiple speakers are not supported by this route.
Save the returned audio. Reuse the same Idempotency-Key and request after a connection failure. Completed requests replay saved audio when content logging and retention permit it, without another generation or charge. Read status at GET /v1/audio/speech/requests/{id} and audio at GET /v1/audio/speech/requests/{id}/audio, using the response’s X-Request-ID. Audio that was not saved, expired or was deleted returns 410 audio_not_retained. The storage retention limit is seven days by default, or less under your content settings. An uncertain outcome requires reconciliation; submitting a new key can generate and bill again.