---
title: "Audio File (non-streaming)"
url: "https://dev.silma.ai/apis/silma-tts-api-2/versions/d7a27b7e-ba8b-495a-a2a3-3cdf9c2b4be3/paths/generate/post"
---
> Full API specification: https://dev.silma.ai/apis/silma-tts-api-2/versions/d7a27b7e-ba8b-495a-a2a3-3cdf9c2b4be3.md
# Audio File (non-streaming)
`POST` `/generate`
Generates the whole text and returns one finished audio file, for narration use cases (audiobooks, voice-overs, e-learning). * Same text limit (1000 characters), pause tags and billing as /stream. Responses are never cached ("enable_cache" is ignored).
## Request body (required)
Content types: `application/json`
## Responses
- `200` - The audio file.
- `400` - Bad Request
- `429` - Insufficient character credits.
- `500` - Audio generation failed.
## OpenAPI definition
```yaml
openapi: 3.1.0
info:
title: SILMA TTS v2 API
version: 2.3.1
servers:
- url: https://api.silma.ai/tts/v2
paths:
/generate:
post:
summary: Audio File (non-streaming)
description: >
Generates the whole text and returns one finished audio file, for
narration use cases (audiobooks, voice-overs, e-learning).
* Same text limit (1000 characters), pause tags and billing as /stream.
Responses are never cached ("enable_cache" is ignored).
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GenerateTTSRequest"
responses:
"200":
description: The audio file.
headers:
X-Audio-Sample-Rate:
description: Sample rate of the audio in Hz.
schema:
type: integer
X-Audio-Duration:
description: Duration of the audio in seconds.
schema:
type: number
X-Cache:
description: Always BYPASS (/generate responses are not cached).
schema:
type: string
enum:
- BYPASS
X-Billed-Characters:
description: The characters billed for this request.
schema:
type: integer
content:
audio/wav:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"429":
description: Insufficient character credits.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Audio generation failed.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
security:
- ApiKeyAuth: []
components:
schemas:
GenerateTTSRequest:
allOf:
- $ref: "#/components/schemas/StreamTTSRequest"
- type: object
properties:
response_format:
type: string
enum:
- wav
- mp3
default: wav
description: >
* The format of the returned audio file: "wav" (16-bit mono PCM)
or "mp3" (128 kbps mono).
* "enable_cache" is ignored: every /generate request is
generated.
ErrorResponse:
type: object
properties:
detail:
type: string
description: Error message details.
StreamTTSRequest:
allOf:
- $ref: "#/components/schemas/BaseTTSRequest"
- type: object
properties:
text:
maxLength: 1000
description: >
* The text to synthesize into speech (up to 1000 characters).
* To pronounce phone numbers correctly use
`92005455`
* To pronounce emails correctly use
`test@silma.ai`
* To pronounce links correctly use
`www.silma.ai`
* To insert a pause use the SSML break tag, e.g. `` or `` (max 5s per pause; a
bare `` pauses 0.5s). Only the "time" attribute is
supported.
* Break tags do not count toward the character limit or billed
characters.
BaseTTSRequest:
type: object
required:
- model_id
- text
- voice_id
properties:
model_id:
type: string
enum:
- silma-tts-v2-english
- silma-tts-v2-msa
- silma-tts-v2-ksa
description: The model id to use (English, Arabic MSA or Arabic KSA dialect).
text:
type: string
description: >
* The text to synthesize into speech.
* To pronounce phone numbers correctly use
`92005455`
* To pronounce emails correctly use
`test@silma.ai`
* To pronounce links correctly use
`www.silma.ai`
* To insert a pause use the SSML break tag, e.g. `` or `` (max 5s per pause; a bare
`` pauses 0.5s). Only the "time" attribute is supported.
* Break tags do not count toward the character limit or billed
characters.
example: أنا نموذج سِلْمَا الجديد لتحويل النص إلى كلام، أستطيع التحدث باللغة
العربية مع أو بدون تشكيل.
creativity:
type: number
format: float
default: 0.2
description: Variance in speech prosody.
speed:
type: number
format: float
default: 0.4
deprecated: true
description: |
* Deprecated. Kept for backward compatibility and behaves as before.
* Use "speech_rate" to control how fast the voice speaks.
speech_rate:
type: number
format: float
default: 1
minimum: 0.7
maximum: 1.4
description: >
* 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.
voice_id:
type: string
enum:
- james
- emma
- isabella
- oliver
- abdulaziz
- fahd
- layla
- maryam
- nouf
- noura
- omar
- reema
- yusuf
- khalid
- salwa
- saja
- sultan
- salman
- sulaiman
- salim
description: >
* 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]
user_id:
type: string
description: Optional user identifier, needed only for pronunciation overrides
and loading custom voices. Find it here
https://app.silma.ai/api-keys
custom_audio_id:
type: string
description: >
* 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_overrides:
type: boolean
description: 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_cache:
type: boolean
description: >
* 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_cache:
type: boolean
description: >
* 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
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: apiKey
```