Sarj AI Developer API Settings API
The settings API from Sarj AI Developer API — 7 operation(s) for settings.
OpenAPI Specification
openapi: 3.2.0
info:
title: Sarj.ai Voice Settings API
version: 1.0.0
tags:
- name: settings
paths:
/v1/settings/voices:
get:
tags:
- settings
summary: Get Voices
operationId: settingsGetVoices
parameters:
- name: language
in: query
required: true
schema:
$ref: '#/components/schemas/Language'
description: Language code (en or ar)
description: Language code (en or ar)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TTSVoice'
title: Response Settingsgetvoices
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- settings
summary: Create Voice
operationId: settingsCreateVoice
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertTTSVoice'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TTSVoice'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/voices/list:
post:
tags:
- settings
summary: List Voices
operationId: settingsListVoices
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListVoicesRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListVoicesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/voices/{voice_id}:
get:
tags:
- settings
summary: Get Voice
operationId: settingsGetVoice
parameters:
- name: voice_id
in: path
required: true
schema:
type: string
title: Voice Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TTSVoice'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- settings
summary: Update Voice
operationId: settingsUpdateVoice
parameters:
- name: voice_id
in: path
required: true
schema:
type: string
title: Voice Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTTSVoice'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TTSVoice'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/voices/{voice_id}/preview:
post:
tags:
- settings
summary: Preview Voice
operationId: settingsPreviewVoice
parameters:
- name: voice_id
in: path
required: true
schema:
type: string
title: Voice Id
responses:
'200':
description: TTS audio preview
content:
audio/mpeg:
schema:
type: string
format: binary
audio/wav:
schema:
type: string
format: binary
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/global-prompt/config:
get:
tags:
- settings
summary: Get Global Prompt Config
operationId: settingsGetGlobalPromptConfig
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalPromptConfig'
put:
tags:
- settings
summary: Save Global Prompt Config
operationId: settingsSaveGlobalPromptConfig
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalPromptConfig'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalPromptConfig'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/global:
get:
tags:
- settings
summary: Get Global Settings
operationId: settingsGetGlobalSettings
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalSettingsData'
put:
tags:
- settings
summary: Update Global Settings
operationId: settingsUpdateGlobalSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGlobalSettingsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalSettingsData'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/settings/scenario-generation/models:
get:
tags:
- settings
summary: Get Scenario Generation Models
operationId: settingsGetScenarioGenerationModels
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScenarioGenerationModelsResponse'
components:
schemas:
STTProviderScope:
properties:
type:
type: string
const: provider_specific
title: Type
default: provider_specific
provider:
type: string
const: stt
title: Provider
default: stt
model:
$ref: '#/components/schemas/STTProvider'
type: object
required:
- model
title: STTProviderScope
OpenAITTSModels:
type: string
enum:
- gpt-4o-mini-tts
- tts-1
- tts-1-hd
title: OpenAITTSModels
HamsaTTSDialect:
type: string
enum:
- pls
- egy
- syr
- irq
- jor
- leb
- ksa
- uae
- bah
- qat
- msa
title: HamsaTTSDialect
SarjF5TTSSettings:
properties:
provider:
type: string
const: sarj_f5
title: Provider
voice:
$ref: '#/components/schemas/SarjF5TTSVoice'
default: Male
type: object
required:
- provider
title: SarjF5TTSSettings
DisableSTTFallback:
properties:
type:
type: string
const: disable
title: Type
default: disable
type: object
title: DisableSTTFallback
UpdateGlobalSettingsRequest:
properties:
data:
additionalProperties:
$ref: '#/components/schemas/GlobalSettings'
propertyNames:
$ref: '#/components/schemas/Language'
type: object
title: Data
scenario_generation:
$ref: '#/components/schemas/ScenarioGenerationConfig'
max_call_duration_seconds:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Max Call Duration Seconds
type: object
required:
- data
- scenario_generation
title: UpdateGlobalSettingsRequest
BackChannelConfig:
properties:
type:
type: string
const: freq
title: Type
default: freq
value:
type: number
maximum: 1.0
exclusiveMinimum: 0.0
title: Value
default: 0.6
whitelist:
items:
type: string
type: array
title: Whitelist
type: object
title: BackChannelConfig
ListVoicesResponse:
properties:
voices:
items:
$ref: '#/components/schemas/TTSVoice'
type: array
title: Voices
cursor:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Cursor
prev_cursor:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Prev Cursor
type: object
required:
- voices
title: ListVoicesResponse
VariableInfo:
properties:
description:
type: string
title: Description
label:
type: string
title: Label
type: object
required:
- description
- label
title: VariableInfo
SarjCustomSTTSettings:
properties:
provider:
type: string
const: sarj_custom
title: Provider
type: object
required:
- provider
title: SarjCustomSTTSettings
AWSTTSSettings:
properties:
provider:
type: string
const: aws
title: Provider
region:
type: string
enum:
- eu-central-1
- us-east-1
title: Region
default: eu-central-1
type: object
required:
- provider
title: AWSTTSSettings
SarjEouTurnDetection:
properties:
type:
type: string
const: sarj_eou
title: Type
default: sarj_eou
threshold:
type: number
maximum: 1.0
minimum: 0.0
title: Threshold
default: 0.5
prediction_timeout:
type: string
format: duration
title: Prediction Timeout
default: PT0.5S
min_endpointing_delay:
type: string
format: duration
title: Min Endpointing Delay
default: PT0.5S
max_endpointing_delay:
type: string
format: duration
title: Max Endpointing Delay
default: PT3S
targeted_stt_providers:
items:
$ref: '#/components/schemas/STTProvider'
type: array
title: Targeted Stt Providers
type: object
title: SarjEouTurnDetection
TTSVoice:
properties:
id:
type: string
title: Id
display_name:
type: string
title: Display Name
provider:
type: string
title: Provider
language:
$ref: '#/components/schemas/Language'
gender:
$ref: '#/components/schemas/Gender'
tts_settings:
anyOf:
- $ref: '#/components/schemas/ElevenLabsTTSSettings'
- $ref: '#/components/schemas/AzureTTSSettings'
- $ref: '#/components/schemas/OpenAITTSSettings'
- $ref: '#/components/schemas/AWSTTSSettings'
- $ref: '#/components/schemas/GroqTTSSettings'
- $ref: '#/components/schemas/HamsaTTSSettings'
- $ref: '#/components/schemas/CartesiaTTSSettings'
- $ref: '#/components/schemas/DeepgramTTSSettings'
- $ref: '#/components/schemas/SarjF5TTSSettings'
- $ref: '#/components/schemas/SarjOmniTTSSettings'
title: Tts Settings
is_active:
type: boolean
title: Is Active
default: true
vibe:
type: string
title: Vibe
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- display_name
- provider
- language
- gender
- tts_settings
- vibe
- created_at
- updated_at
title: TTSVoice
OpenAILLMSettings:
properties:
provider:
type: string
const: openai
title: Provider
region:
type: string
const: default
title: Region
default: default
model:
$ref: '#/components/schemas/OpenAIModel'
type: object
required:
- provider
- model
title: OpenAILLMSettings
LLMProviderScope:
properties:
type:
type: string
const: provider_specific
title: Type
default: provider_specific
provider:
type: string
const: llm
title: Provider
default: llm
model:
$ref: '#/components/schemas/LLMProvider'
type: object
required:
- model
title: LLMProviderScope
BackChannelMixConfig:
properties:
type:
type: string
const: mix
title: Type
default: mix
value:
type: number
maximum: 1.0
exclusiveMinimum: 0.0
title: Value
default: 0.6
word_probability:
type: number
maximum: 1.0
minimum: 0.0
title: Word Probability
default: 0.7
whitelist:
items:
type: string
type: array
title: Whitelist
sounds:
items:
$ref: '#/components/schemas/BackchannelAudioConfig'
type: array
minItems: 1
title: Sounds
type: object
required:
- sounds
title: BackChannelMixConfig
GeminiLLMSettings:
properties:
provider:
type: string
const: gemini
title: Provider
region:
type: string
enum:
- us-central1
- me-central2
- us-east1
- europe-west1
- europe-west3
title: Region
default: europe-west3
model:
type: string
enum:
- flash
- pro
- flash-lite-3.1
title: Model
default: flash
type: object
required:
- provider
title: GeminiLLMSettings
GroqSTTSettings:
properties:
provider:
type: string
const: groq
title: Provider
model:
$ref: '#/components/schemas/GroqSTTModels'
type: object
required:
- provider
- model
title: GroqSTTSettings
OpenAISTTSettings:
properties:
provider:
type: string
const: openai
title: Provider
model:
type: string
enum:
- gpt-4o-transcribe
- gpt-4o-mini-transcribe
title: Model
region:
type: string
const: default
title: Region
default: default
type: object
required:
- provider
- model
title: OpenAISTTSettings
ElevenLabsSTTModel:
type: string
enum:
- scribe_v1
- scribe_v2
- scribe_v2_realtime
title: ElevenLabsSTTModel
AWSSTTSettings:
properties:
provider:
type: string
const: aws
title: Provider
region:
type: string
enum:
- eu-central-1
- us-east-1
title: Region
default: eu-central-1
type: object
required:
- provider
title: AWSSTTSettings
AzureSTTSettings:
properties:
provider:
type: string
const: azure
title: Provider
region:
type: string
enum:
- eastus
- germanywestcentral
title: Region
default: eastus
type: object
required:
- provider
title: AzureSTTSettings
CerebrasLLMModel:
type: string
enum:
- llama-3.1-8b-instruct
title: CerebrasLLMModel
BackChannelWordConfig:
properties:
type:
type: string
const: word
title: Type
default: word
value:
type: number
maximum: 1.0
exclusiveMinimum: 0.0
title: Value
default: 0.6
whitelist:
items:
type: string
type: array
title: Whitelist
type: object
title: BackChannelWordConfig
OpenAITTSVoices:
type: string
enum:
- alloy
- ash
- ballad
- coral
- echo
- fable
- onyx
- nova
- sage
- shimmer
title: OpenAITTSVoices
UpsertTTSVoice:
properties:
display_name:
type: string
title: Display Name
vibe:
type: string
minLength: 1
title: Vibe
tts_settings:
anyOf:
- $ref: '#/components/schemas/ElevenLabsTTSSettings'
- $ref: '#/components/schemas/AzureTTSSettings'
- $ref: '#/components/schemas/OpenAITTSSettings'
- $ref: '#/components/schemas/AWSTTSSettings'
- $ref: '#/components/schemas/GroqTTSSettings'
- $ref: '#/components/schemas/HamsaTTSSettings'
- $ref: '#/components/schemas/CartesiaTTSSettings'
- $ref: '#/components/schemas/DeepgramTTSSettings'
- $ref: '#/components/schemas/SarjF5TTSSettings'
- $ref: '#/components/schemas/SarjOmniTTSSettings'
title: Tts Settings
gender:
$ref: '#/components/schemas/Gender'
language:
$ref: '#/components/schemas/Language'
is_active:
type: boolean
title: Is Active
default: true
type: object
required:
- display_name
- vibe
- tts_settings
- gender
- language
title: UpsertTTSVoice
OpenAITTSSettings:
properties:
provider:
type: string
const: openai
title: Provider
model:
$ref: '#/components/schemas/OpenAITTSModels'
default: gpt-4o-mini-tts
voice:
$ref: '#/components/schemas/OpenAITTSVoices'
default: ash
speed:
type: number
maximum: 4.0
minimum: 0.2
title: Speed
description: Speech speed (0.2-4.0)
default: 1.0
instructions:
anyOf:
- type: string
- type: 'null'
title: Instructions
type: object
required:
- provider
title: OpenAITTSSettings
DeepgramTTSModel:
type: string
enum:
- aura-2
title: DeepgramTTSModel
TTSProvider:
type: string
enum:
- groq
- 11labs
- azure
- openai
- aws
- hamsa
- cartesia
- deepgram
- sarj_f5
- sarj_omni
title: TTSProvider
GroqLLMModel:
type: string
enum:
- llama-3.1-405b-reasoning
- llama-3.1-8b-instant
- llama-3.3-70b-versatile
- llama3-groq-70b-8192-tool-use-preview
- llama3-groq-8b-8192-tool-use-preview
- llama-guard-3-8b
- llama3-70b-8192
- llama3-8b-8192
- mixtral-8x7b-32768
- gemma-7b-it
- gemma2-9b-it
- meta-llama/llama-4-scout-17b-16e-instruct
- meta-llama/llama-4-maverick-17b-128e-instruct
- openai/gpt-oss-20b
- openai/gpt-oss-120b
- qwen/qwen3-32b
title: GroqLLMModel
CartesiaTTSSettings:
properties:
provider:
type: string
const: cartesia
title: Provider
model:
$ref: '#/components/schemas/CartesiaModels'
default: sonic-3
voice:
type: string
title: Voice
default: f257d7af-eb60-4ef0-8815-b78701006c2c
speed:
type: number
maximum: 1.5
minimum: 0.6
title: Speed
description: Speech speed (0.6-1.5)
default: 1.0
emotion:
anyOf:
- type: string
- type: 'null'
title: Emotion
type: object
required:
- provider
title: CartesiaTTSSettings
DisableBackChanneling:
properties:
type:
type: string
const: disable
title: Type
default: disable
type: object
title: DisableBackChanneling
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
PromptSection:
properties:
name:
type: string
title: Name
language:
anyOf:
- $ref: '#/components/schemas/Language'
- type: 'null'
content:
type: string
title: Content
scope:
anyOf:
- $ref: '#/components/schemas/GeneralScope'
- $ref: '#/components/schemas/TTSProviderScope'
- $ref: '#/components/schemas/STTProviderScope'
- $ref: '#/components/schemas/LLMProviderScope'
- $ref: '#/components/schemas/UseCaseScope'
title: Scope
order:
type: integer
title: Order
type: object
required:
- name
- language
- content
- scope
- order
title: PromptSection
GlobalPromptConfig:
properties:
updated_at:
type: string
title: Updated At
updated_by:
type: string
title: Updated By
available_variables:
additionalProperties:
$ref: '#/components/schemas/VariableInfo'
type: object
title: Available Variables
sections:
items:
$ref: '#/components/schemas/PromptSection'
type: array
title: Sections
type: object
required:
- updated_at
- updated_by
- available_variables
- sections
title: GlobalPromptConfig
UseCaseScope:
properties:
type:
type: string
const: use_case
title: Type
default: use_case
value:
type: string
title: Value
type: object
required:
- value
title: UseCaseScope
HamsaTTSSettings:
properties:
provider:
type: string
const: hamsa
title: Provider
speaker:
$ref: '#/components/schemas/HamsaTTSSpeaker'
default: Hiba
dialect:
$ref: '#/components/schemas/HamsaTTSDialect'
default: ksa
type: object
required:
- provider
title: HamsaTTSSettings
LiveKitTurnDetection:
properties:
type:
type: string
const: livekit_v1_mini
title: Type
default: livekit_v1_mini
unlikely_threshold:
anyOf:
- type: number
maximum: 1.0
minimum: 0.0
- type: 'null'
title: Unlikely Threshold
min_endpointing_delay:
type: string
format: duration
title: Min Endpointing Delay
default: PT0.3S
max_endpointing_delay:
type: string
format: duration
title: Max Endpointing Delay
default: PT2.5S
type: object
title: LiveKitTurnDetection
GoogleSTTSettings:
properties:
provider:
type: string
const: google
title: Provider
model:
type: string
enum:
- long
- short
- telephony
- chirp_2
- chirp_3
title: Model
region:
type: string
enum:
- us
- eu
title: Region
type: object
required:
- provider
- model
- region
title: GoogleSTTSettings
OrpheusArabicVoice:
type: string
enum:
- fahad
- sultan
- lulwa
- noura
- aisha
- abdullah
title: OrpheusArabicVoice
STTFallbackConfig:
properties:
type:
type: string
const: enable
title: Type
default: enable
models:
items:
anyOf:
- $ref: '#/components/schemas/GoogleSTTSettings'
- $ref: '#/components/schemas/AzureSTTSettings'
- $ref: '#/components/schemas/AWSSTTSettings'
- $ref: '#/components/schemas/GroqSTTSettings'
- $ref: '#/components/schemas/OpenAISTTSettings'
- $ref: '#/components/schemas/ElevenLabsSTTSettings'
- $ref: '#/components/schemas/SpeechmaticsSTTSettings'
- $ref: '#/components/schemas/DeepgramSTTSettings'
type: array
maxItems: 2
title: Models
type: object
title: STTFallbackConfig
CerebrasLLMSettings:
properties:
provider:
type: string
const: cerebras
title: Provider
default: cerebras
model:
$ref: '#/components/schemas/CerebrasLLMModel'
type: object
required:
- model
title: CerebrasLLMSettings
UpdateTTSVoice:
properties:
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
gender:
anyOf:
- $ref: '#/components/schemas/Gender'
- type: 'null'
is_active:
anyOf:
- type: boolean
- type: 'null'
title: Is Active
vibe:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Vibe
type: object
title: UpdateTTSVoice
ElevenLabsSTTSettings:
properties:
provider:
type: string
const: elevenlabs
title: Provider
model:
$ref: '#/components/schemas/ElevenLabsSTTModel'
default: scribe_v1
region:
$ref: '#/components/schemas/ElevenLabsRegion'
default: eu
type: object
required:
- provider
title: ElevenLabsSTTSettings
ElevenLabsModels:
type: string
enum:
- eleven_multilingual_v2
- eleven_flash_v2_5
- eleven_turbo_v2_5
title: ElevenLabsModels
SarjF5TTSVoice:
type: string
enum:
- Male
- Female
title: SarjF5TTSVoice
ListVoicesRequest:
properties:
cursor:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Cursor
limit:
type: integer
maximum: 100.0
minimum: 1.0
title: Limit
default: 10
is_active:
anyOf:
- type: boolean
- type: 'null'
title: Is Active
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
language:
anyOf:
- $ref: '#/components/schemas/Language'
- type: 'null'
gender:
anyOf:
- type: string
- type: 'null'
title: Gender
type: object
title: ListVoicesRequest
SarjGroqSTTSettings:
properties:
provider:
type: string
const: sarj_groq
title: Provider
type: object
required:
- provider
title: SarjGroqSTTSettings
SarjOmniTTSVoice:
type: string
enum:
- ars_male
- ars_fares
- ars_female_expressive
title: SarjOmniTTSVoice
BackchannelAudioConfig:
properties:
sound_id:
$ref: '#/components/schemas/SoundId'
volume:
type: number
maximum: 1.0
minimum: 0.0
title: Volume
default: 1.0
probability:
type: number
maximum: 1.0
minimum: 0.0
title: Probability
default: 1.0
type: object
required:
- sound_id
title: BackchannelAudioConfig
ElevenLabsRegion:
type: string
enum:
- us
- eu
title: ElevenLabsRegion
TimeoutSettings:
properties:
type:
type: string
const: enabled
title: Type
default: enabled
duration:
anyOf:
- type: string
format: duration
- type: integer
title: Duration
default: 15
max_retries:
type: integer
title: Max Retries
default: 5
type: object
title: TimeoutSettings
GlobalSettings:
properties:
models:
$ref: '#/components/schemas/GlobalModelConfig'
back_channel:
anyOf:
- $ref: '#/components/schemas/BackChannelConfig'
- $ref: '#/components/schemas/BackChannelWordConfig'
- $ref: '#/components/schemas/BackChannelSoundConfig'
- $ref: '#/components/schemas/BackChannelMixConfig'
- $ref: '#/components/schemas/DisableBackChanneling'
title: Back Channel
allow_interruptions:
type: boolean
title: Allow Interruptions
timeout:
anyOf:
- $ref: '#/components/schemas/TimeoutSettings'
- $ref: '#/components/schemas/DisableTimeoutSettings'
title: Timeout
agent_name:
type: string
title: Agent Name
default: ''
turn_detection:
anyOf:
- $ref: '#/components/schemas/DisableTurnDetection'
- $ref: '#/components/schemas/SarjEouTurnDetection'
- $ref: '#/components/schemas/LiveKitTurnDetection'
title: Turn Detection
max_duration_end_call_message:
anyOf:
- type: string
- type: 'null'
title: Max Duration End Call Message
type: object
required:
- models
- back_channel
- allow_interruptions
- timeout
title: GlobalSettings
SoundId:
type: string
enum:
- keyboard_typing
title: SoundId
DeepgramTTSSettings:
properties:
provider:
type: string
const: deepgram
title: Provider
model:
$ref: '#/components/schemas/DeepgramTTSModel'
default: aura-2
voice:
type: string
title: Voice
type: object
required:
- provider
- voice
title: DeepgramTTSSettings
AzureOpenAIModel:
type: string
enum:
- gpt-4.1
title: AzureOpenAIModel
CartesiaModels:
type: string
enum:
- sonic-3
- sonic-2
- sonic
title: CartesiaModels
GlobalSettingsData:
properties:
data:
additionalProperties:
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sarj-ai-developer-api/refs/heads/main/openapi/sarj-ai-developer-api-settings-api-openapi.yml