SILMA TTS API

SILMA TTS v2 API

WebSocket Streaming

Establish a full-duplex connection for TTS.
Handshake: Upgrade request to wss://api.silma.ai/tts/v2/ws/stream.
Process:

  1. Client sends TTSRequest JSON.
  2. Server sends messages with status: started, streaming, completed, or failed.
    The started message includes cache (HIT, MISS or BYPASS, see enable_cache) and billed_characters.
get
https://api.silma.ai/tts/v2/ws/stream

Response

101

Switching Protocols to WebSocket.

get/ws/stream
 
101

WebSocket Input Streaming (LLM token stream to speech)

For voice agents: pipe your LLM’s token stream in and get one continuous, real-time-paced audio stream back.
Handshake: Upgrade request to wss://api.silma.ai/tts/v2/ws/input_stream.
Client messages (JSON):

  1. {"type":"init", ...} with the TTSRequest fields except text (model_id, voice_id, speech_rate, creativity, seed, …),
    plus optional idle_flush_ms (0-10000, default 400): when the LLM is quiet this long and no speech is pending,
    the words buffered so far are spoken without waiting for the end of the sentence (0 disables).
  2. {"type":"text","text":"<chunk>"}: send each chunk of text your LLM streams (usually one token, e.g. " can") as soon as you receive it.
    Chunks of any size are accepted (a character, a token, a sentence, or the whole answer); they are joined exactly as sent,
    so forward them unchanged, keeping their leading/trailing spaces.
  3. {"type":"flush"} to speak whatever is buffered now.
  4. {"type":"end"} when the LLM is done, or {"type":"cancel"} to stop at once (barge-in). After either, the socket accepts a new init.
    Server messages:
  • started (sample_rate, model_id, max_characters).
  • streaming: audio (base64 float32 mono PCM) and text (the segment being spoken; "" for silence).
    Text is spoken one segment at a time, released at sentence ends (or a clause for the first segment, or a length cap).
    From the first speech chunk on, audio is sent at about 1x real time and gaps are filled with silence, until end/cancel.
    Gap-filling silence messages also carry silence: "llm" (waiting for more text) or "tts" (text is being synthesized).
  • warning (warning): non-fatal, e.g. the character limit was reached.
  • completed / cancelled with billed_characters and stats (ttfa_ms, segments, underruns, tts_wait_sec, llm_wait_sec).
    Billing is once per session, for the characters actually spoken. On cancel, stop local playback yourself: audio already sent is not recalled.
  • failed (error), followed by a close (1008 invalid input, 1011 server error).
get
https://api.silma.ai/tts/v2/ws/input_stream

Response

101

Switching Protocols to WebSocket.

get/ws/input_stream
 
101

BaseTTSRequest

object
model_idstringrequired

The model id to use (English, Arabic MSA or Arabic KSA dialect).

Allowed values:silma-tts-v2-englishsilma-tts-v2-msasilma-tts-v2-ksa

textstringrequired
  • The text to synthesize into speech.
  • To pronounce phone numbers correctly use <STAG_PN>92005455</STAG_PN>
  • To pronounce emails correctly use <STAG_EMAIL>test@silma.ai</STAG_EMAIL>
  • To pronounce links correctly use <STAG_LINK>www.silma.ai</STAG_LINK>
  • To insert a pause use the SSML break tag, e.g. <break time="500ms"/> or <break time="1.5s"/> (max 5s per pause; a bare <break/> pauses 0.5s). Only the “time” attribute is supported.
  • Break tags do not count toward the character limit or billed characters.

Example:أنا نموذج سِلْمَا الجديد لتحويل النص إلى كلام، أستطيع التحدث باللغة العربية مع أو بدون تشكيل.

creativitynumber(float)

Variance in speech prosody.

Default:0.2

speednumber(float)DEPRECATED
  • Deprecated. Kept for backward compatibility and behaves as before.
  • Use “speech_rate” to control how fast the voice speaks.

Default:0.4

speech_ratenumber(float)
  • Speaking rate multiplier. 1.0 is the voice’s natural pace, 1.2 is 20% faster and 0.8 is 20% slower.
  • The voice and its pitch stay the same at every rate.

Default:1

>= 0.7<= 1.4

voice_idstringrequired
  • The ID of the pre-defined voice.
  • English voices: [james, emma, isabella, oliver]
  • Arabic voices: [abdulaziz, fahd, layla, maryam, nouf, noura, omar, reema, yusuf, khalid]
  • Legacy Arabic voices: [salwa, saja, sultan, salman, sulaiman, salim]

Allowed values:jamesemmaisabellaoliverabdulazizfahdlaylamaryamnoufnouraomarreemayusufkhalidsalwasajasultansalmansulaimansalim

user_idstring

Optional user identifier, needed only for pronunciation overrides and loading custom voices. Find it here https://app.silma.ai/api-keys

custom_audio_idstring
  • The ID representing your uploaded custom voice to be cloned.
  • This should be an ID for a voice (ex:voice_1769817467123) in the “Custom Voices” section in https://app.silma.ai/voices.
  • If you use this parameter then you should use the “user_id” parameter as well.
enable_server_pronunciation_overridesboolean

This indicates that you have added custom pronunciation overrides to your account via https://app.silma.ai/control. Enabling this feature will automatically customize the model based on your overrides.

Default:false

invalidate_user_cacheboolean
  • Pronunciation overrides and cached audio (see “enable_cache”) are cached on the server.
  • Set this to true on a single request to drop all of your cached overrides and cached audio. Overrides are then re-read from storage and the audio is generated again.
  • The UI sends this when you edit your pronunciation overrides. Otherwise, the server uses cached audio and overrides, which keeps the old pronunciation. You typically don’t need to use this unless you want to intentionally invalidate all cached audio and overrides for some reason.

Default:false

enable_cacheboolean
  • Cache the generated audio on the server and return it from the cache for identical requests, instead of generating it again.
  • Requests are identical when they call the same endpoint with the same “model_id”, “voice_id”, “text”, “speed”, “speech_rate”, “creativity”, “quality_to_inference_speed_ratio”, “custom_audio_id” and “enable_server_pronunciation_overrides”, from the same account.
  • Cached responses are billed half the characters (rounded up).
  • Cached audio is private to your account and kept for up to 30 days. Use “invalidate_user_cache” to drop it.
  • The “X-Cache” response header is “HIT” when the response came from the cache, “MISS” when it was generated, and “BYPASS” when caching was not requested.

Default:false

Example

TTSRequest

model_idstringrequired

The model id to use (English, Arabic MSA or Arabic KSA dialect).

Allowed values:silma-tts-v2-englishsilma-tts-v2-msasilma-tts-v2-ksa

textstringrequired
  • The text to synthesize into speech (up to 250 characters).
  • To pronounce phone numbers correctly use <STAG_PN>92005455</STAG_PN>
  • To pronounce emails correctly use <STAG_EMAIL>test@silma.ai</STAG_EMAIL>
  • To pronounce links correctly use <STAG_LINK>www.silma.ai</STAG_LINK>
  • To insert a pause use the SSML break tag, e.g. <break time="500ms"/> or <break time="1.5s"/> (max 5s per pause; a bare <break/> pauses 0.5s). Only the “time” attribute is supported.
  • Break tags do not count toward the character limit or billed characters.

<= 250 characters

Example:أنا نموذج سِلْمَا الجديد لتحويل النص إلى كلام، أستطيع التحدث باللغة العربية مع أو بدون تشكيل.

creativitynumber(float)

Variance in speech prosody.

Default:0.2

speednumber(float)DEPRECATED
  • Deprecated. Kept for backward compatibility and behaves as before.
  • Use “speech_rate” to control how fast the voice speaks.

Default:0.4

speech_ratenumber(float)
  • Speaking rate multiplier. 1.0 is the voice’s natural pace, 1.2 is 20% faster and 0.8 is 20% slower.
  • The voice and its pitch stay the same at every rate.

Default:1

>= 0.7<= 1.4

voice_idstringrequired
  • The ID of the pre-defined voice.
  • English voices: [james, emma, isabella, oliver]
  • Arabic voices: [abdulaziz, fahd, layla, maryam, nouf, noura, omar, reema, yusuf, khalid]
  • Legacy Arabic voices: [salwa, saja, sultan, salman, sulaiman, salim]

Allowed values:jamesemmaisabellaoliverabdulazizfahdlaylamaryamnoufnouraomarreemayusufkhalidsalwasajasultansalmansulaimansalim

user_idstring

Optional user identifier, needed only for pronunciation overrides and loading custom voices. Find it here https://app.silma.ai/api-keys

custom_audio_idstring
  • The ID representing your uploaded custom voice to be cloned.
  • This should be an ID for a voice (ex:voice_1769817467123) in the “Custom Voices” section in https://app.silma.ai/voices.
  • If you use this parameter then you should use the “user_id” parameter as well.
enable_server_pronunciation_overridesboolean

This indicates that you have added custom pronunciation overrides to your account via https://app.silma.ai/control. Enabling this feature will automatically customize the model based on your overrides.

Default:false

invalidate_user_cacheboolean
  • Pronunciation overrides and cached audio (see “enable_cache”) are cached on the server.
  • Set this to true on a single request to drop all of your cached overrides and cached audio. Overrides are then re-read from storage and the audio is generated again.
  • The UI sends this when you edit your pronunciation overrides. Otherwise, the server uses cached audio and overrides, which keeps the old pronunciation. You typically don’t need to use this unless you want to intentionally invalidate all cached audio and overrides for some reason.

Default:false

enable_cacheboolean
  • Cache the generated audio on the server and return it from the cache for identical requests, instead of generating it again.
  • Requests are identical when they call the same endpoint with the same “model_id”, “voice_id”, “text”, “speed”, “speech_rate”, “creativity”, “quality_to_inference_speed_ratio”, “custom_audio_id” and “enable_server_pronunciation_overrides”, from the same account.
  • Cached responses are billed half the characters (rounded up).
  • Cached audio is private to your account and kept for up to 30 days. Use “invalidate_user_cache” to drop it.
  • The “X-Cache” response header is “HIT” when the response came from the cache, “MISS” when it was generated, and “BYPASS” when caching was not requested.

Default:false

Example

StreamTTSRequest

model_idstringrequired

The model id to use (English, Arabic MSA or Arabic KSA dialect).

Allowed values:silma-tts-v2-englishsilma-tts-v2-msasilma-tts-v2-ksa

textstringrequired
  • The text to synthesize into speech (up to 1000 characters).
  • To pronounce phone numbers correctly use <STAG_PN>92005455</STAG_PN>
  • To pronounce emails correctly use <STAG_EMAIL>test@silma.ai</STAG_EMAIL>
  • To pronounce links correctly use <STAG_LINK>www.silma.ai</STAG_LINK>
  • To insert a pause use the SSML break tag, e.g. <break time="500ms"/> or <break time="1.5s"/> (max 5s per pause; a bare <break/> pauses 0.5s). Only the “time” attribute is supported.
  • Break tags do not count toward the character limit or billed characters.

<= 1000 characters

Example:أنا نموذج سِلْمَا الجديد لتحويل النص إلى كلام، أستطيع التحدث باللغة العربية مع أو بدون تشكيل.

creativitynumber(float)

Variance in speech prosody.

Default:0.2

speednumber(float)DEPRECATED
  • Deprecated. Kept for backward compatibility and behaves as before.
  • Use “speech_rate” to control how fast the voice speaks.

Default:0.4

speech_ratenumber(float)
  • Speaking rate multiplier. 1.0 is the voice’s natural pace, 1.2 is 20% faster and 0.8 is 20% slower.
  • The voice and its pitch stay the same at every rate.

Default:1

>= 0.7<= 1.4

voice_idstringrequired
  • The ID of the pre-defined voice.
  • English voices: [james, emma, isabella, oliver]
  • Arabic voices: [abdulaziz, fahd, layla, maryam, nouf, noura, omar, reema, yusuf, khalid]
  • Legacy Arabic voices: [salwa, saja, sultan, salman, sulaiman, salim]

Allowed values:jamesemmaisabellaoliverabdulazizfahdlaylamaryamnoufnouraomarreemayusufkhalidsalwasajasultansalmansulaimansalim

user_idstring

Optional user identifier, needed only for pronunciation overrides and loading custom voices. Find it here https://app.silma.ai/api-keys

custom_audio_idstring
  • The ID representing your uploaded custom voice to be cloned.
  • This should be an ID for a voice (ex:voice_1769817467123) in the “Custom Voices” section in https://app.silma.ai/voices.
  • If you use this parameter then you should use the “user_id” parameter as well.
enable_server_pronunciation_overridesboolean

This indicates that you have added custom pronunciation overrides to your account via https://app.silma.ai/control. Enabling this feature will automatically customize the model based on your overrides.

Default:false

invalidate_user_cacheboolean
  • Pronunciation overrides and cached audio (see “enable_cache”) are cached on the server.
  • Set this to true on a single request to drop all of your cached overrides and cached audio. Overrides are then re-read from storage and the audio is generated again.
  • The UI sends this when you edit your pronunciation overrides. Otherwise, the server uses cached audio and overrides, which keeps the old pronunciation. You typically don’t need to use this unless you want to intentionally invalidate all cached audio and overrides for some reason.

Default:false

enable_cacheboolean
  • Cache the generated audio on the server and return it from the cache for identical requests, instead of generating it again.
  • Requests are identical when they call the same endpoint with the same “model_id”, “voice_id”, “text”, “speed”, “speech_rate”, “creativity”, “quality_to_inference_speed_ratio”, “custom_audio_id” and “enable_server_pronunciation_overrides”, from the same account.
  • Cached responses are billed half the characters (rounded up).
  • Cached audio is private to your account and kept for up to 30 days. Use “invalidate_user_cache” to drop it.
  • The “X-Cache” response header is “HIT” when the response came from the cache, “MISS” when it was generated, and “BYPASS” when caching was not requested.

Default:false

Example