Initiate a session

Use the returned WebSocket url to connect to the WebSocket and start sending audio chunks. Use the returned id and the GET /v2/live/:id endpoint to obtain the status and results.

Why initiate with POST instead of connecting directly to the WebSocket?

Security: Generate the WebSocket URL on your backend and keep your API key private. The init call returns a connectable URL and a session id that you can safely pass to web, iOS, or Android clients without exposing credentials in the app.
Lower infrastructure load: The secure URL is generated on your backend, the client can connect directly to Gladia’s WebSocket server without a pass-through on your side, saving your own resources.
Resilient reconnection and session continuity: If the WebSocket disconnects (which can happen on unreliable networks), the session created by the init call lets the client reconnect without losing context. Traditional flows that open a socket first typically force a brand‑new session on disconnect, dropping in‑progress state.

Authorizations

x-gladia-key

string

header

required

Your personal Gladia API key

Query Parameters

region

enum<string>

The region used to process the audio.

Available options:

us-west,

eu-west

Body

application/json

encoding

enum<string>

default:wav/pcm

The encoding format of the audio stream. Supported formats:

PCM: 8, 16, 24, and 32 bits
A-law: 8 bits
μ-law: 8 bits

Note: No need to add WAV headers to raw audio as the API supports both formats.

Available options:

wav/pcm,

wav/alaw,

wav/ulaw

bit_depth

enum<number>

default:16

The bit depth of the audio stream

Available options:

8,

16,

24,

32

sample_rate

enum<number>

default:16000

The sample rate of the audio stream

Available options:

8000,

16000,

32000,

44100,

48000

channels

integer

default:1

The number of channels of the audio stream

Required range: 1 <= x <= 8

custom_metadata

object

Custom metadata you can attach to this live transcription

Example:

{ "user": "John Doe" }

model

enum<string>

default:solaria-1

The model used to process the audio. "solaria-1" is used by default.

Available options:

solaria-1

endpointing

number

default:0.05

The endpointing duration in seconds. Endpointing is the duration of silence which will cause an utterance to be considered as finished

Required range: 0.01 <= x <= 10

maximum_duration_without_endpointing

number

default:5

The maximum duration in seconds without endpointing. If endpointing is not detected after this duration, current utterance will be considered as finished

Required range: 5 <= x <= 60

language_config

object

Specify the language configuration

Show child attributes

language_config.languages

enum<string>[]

If one language is set, it will be used for the transcription. Otherwise, language will be auto-detected by the model.

Specify the language in which it will be pronounced when sound comparison occurs. Default to transcription language.

Available options:

af,

am,

ar,

as,

az,

ba,

be,

bg,

bn,

bo,

br,

bs,

ca,

cs,

cy,

da,

de,

el,

en,

es,

et,

eu,

fa,

fi,

fo,

fr,

gl,

gu,

ha,

haw,

he,

hi,

hr,

ht,

hu,

hy,

id,

is,

it,

ja,

jw,

ka,

kk,

km,

kn,

ko,

la,

lb,

ln,

lo,

lt,

lv,

mg,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

ne,

nl,

nn,

no,

oc,

pa,

pl,

ps,

pt,

ro,

ru,

sa,

sd,

si,

sk,

sl,

sn,

so,

sq,

sr,

su,

sv,

sw,

ta,

te,

tg,

th,

tk,

tl,

tr,

tt,

uk,

ur,

uz,

vi,

yi,

yo,

zh

language_config.code_switching

boolean

default:false

If true, language will be auto-detected on each utterance. Otherwise, language will be auto-detected on first utterance and then used for the rest of the transcription. If one language is set, this option will be ignored.

pre_processing

object

Specify the pre-processing configuration

Show child attributes

pre_processing.audio_enhancer

boolean

default:false

If true, apply pre-processing to the audio stream to enhance the quality.

pre_processing.speech_threshold

number

default:0.6

Sensitivity configuration for Speech Threshold. A value close to 1 will apply stricter thresholds, making it less likely to detect background sounds as speech.

Required range: 0 <= x <= 1

realtime_processing

object

Specify the realtime processing configuration

Show child attributes

realtime_processing.custom_vocabulary

boolean

default:false

If true, enable custom vocabulary for the transcription.

realtime_processing.custom_vocabulary_config

object

Custom vocabulary configuration, if custom_vocabulary is enabled

Show child attributes

realtime_processing.custom_vocabulary_config.vocabulary

(object | string)[]

required

Specific vocabulary list to feed the transcription model with. Each item can be a string or an object with the following properties: value, intensity, pronunciations, language.

Show child attributes

realtime_processing.custom_vocabulary_config.vocabulary.value

string

required

The text used to replace in the transcription.

Example:

"Gladia"

realtime_processing.custom_vocabulary_config.vocabulary.intensity

number

The global intensity of the feature.

Required range: 0 <= x <= 1

Example:

0.5

realtime_processing.custom_vocabulary_config.vocabulary.pronunciations

string[]

The pronunciations used in the transcription.

realtime_processing.custom_vocabulary_config.vocabulary.language

enum<string>

Specify the language in which it will be pronounced when sound comparison occurs. Default to transcription language.

Available options:

af,

am,

ar,

as,

az,

ba,

be,

bg,

bn,

bo,

br,

bs,

ca,

cs,

cy,

da,

de,

el,

en,

es,

et,

eu,

fa,

fi,

fo,

fr,

gl,

gu,

ha,

haw,

he,

hi,

hr,

ht,

hu,

hy,

id,

is,

it,

ja,

jw,

ka,

kk,

km,

kn,

ko,

la,

lb,

ln,

lo,

lt,

lv,

mg,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

ne,

nl,

nn,

no,

oc,

pa,

pl,

ps,

pt,

ro,

ru,

sa,

sd,

si,

sk,

sl,

sn,

so,

sq,

sr,

su,

sv,

sw,

ta,

te,

tg,

th,

tk,

tl,

tr,

tt,

uk,

ur,

uz,

vi,

yi,

yo,

zh

Example:

"en"

Example:

[
  "Westeros",
  { "value": "Stark" },
  {
    "value": "Night's Watch",
    "pronunciations": ["Nightz Watch"],
    "intensity": 0.4,
    "language": "en"
  }
]

realtime_processing.custom_vocabulary_config.default_intensity

number

Default intensity for the custom vocabulary

Required range: 0 <= x <= 1

Example:

0.5

realtime_processing.custom_spelling

boolean

default:false

If true, enable custom spelling for the transcription.

realtime_processing.custom_spelling_config

object

Custom spelling configuration, if custom_spelling is enabled

Show child attributes

realtime_processing.custom_spelling_config.spelling_dictionary

object

required

The list of spelling applied on the audio transcription

Show child attributes

realtime_processing.custom_spelling_config.spelling_dictionary.{key}

string[]

Example:

{
  "Gettleman": ["gettleman"],
  "SQL": ["Sequel"]
}

realtime_processing.translation

boolean

default:false

If true, enable translation for the transcription

realtime_processing.translation_config

object

Translation configuration, if translation is enabled

Show child attributes

realtime_processing.translation_config.target_languages

enum<string>[]

required

Target language in iso639-1 format you want the transcription translated to

Minimum array length: 1

Target language in iso639-1 format you want the transcription translated to

Available options:

af,

am,

ar,

as,

az,

ba,

be,

bg,

bn,

bo,

br,

bs,

ca,

cs,

cy,

da,

de,

el,

en,

es,

et,

eu,

fa,

fi,

fo,

fr,

gl,

gu,

ha,

haw,

he,

hi,

hr,

ht,

hu,

hy,

id,

is,

it,

ja,

jw,

ka,

kk,

km,

kn,

ko,

la,

lb,

ln,

lo,

lt,

lv,

mg,

mi,

mk,

ml,

mn,

mr,

ms,

mt,

my,

ne,

nl,

nn,

no,

oc,

pa,

pl,

ps,

pt,

ro,

ru,

sa,

sd,

si,

sk,

sl,

sn,

so,

sq,

sr,

su,

sv,

sw,

ta,

te,

tg,

th,

tk,

tl,

tr,

tt,

uk,

ur,

uz,

vi,

wo,

yi,

yo,

zh

Example:

["en"]

realtime_processing.translation_config.model

enum<string>

default:base

Model you want the translation model to use to translate

Available options:

base,

enhanced

realtime_processing.translation_config.match_original_utterances

boolean

default:true

Align translated utterances with the original ones

realtime_processing.translation_config.lipsync

boolean

default:true

Whether to apply lipsync to the translated transcription.

realtime_processing.translation_config.context_adaptation

boolean

default:true

Enables or disables context-aware translation features that allow the model to adapt translations based on provided context.

realtime_processing.translation_config.context

string

Context information to improve translation accuracy

realtime_processing.translation_config.informal

boolean

default:false

Forces the translation to use informal language forms when available in the target language.

realtime_processing.named_entity_recognition

boolean

default:false

If true, enable named entity recognition for the transcription.

realtime_processing.sentiment_analysis

boolean

default:false

If true, enable sentiment analysis for the transcription.

post_processing

object

Specify the post-processing configuration

Show child attributes

post_processing.summarization

boolean

default:false

If true, generates summarization for the whole transcription.

post_processing.summarization_config

object

Summarization configuration, if summarization is enabled

Show child attributes

post_processing.summarization_config.type

enum<string>

default:general

The type of summarization to apply

Available options:

general,

bullet_points,

concise

post_processing.chapterization

boolean

default:false

If true, generates chapters for the whole transcription.

messages_config

object

Specify the websocket messages configuration

Show child attributes

messages_config.receive_partial_transcripts

boolean

default:false

If true, partial transcript will be sent to websocket.

messages_config.receive_final_transcripts

boolean

default:true

If true, final transcript will be sent to websocket.

messages_config.receive_speech_events

boolean

default:true

If true, begin and end speech events will be sent to websocket.

messages_config.receive_pre_processing_events

boolean

default:true

If true, pre-processing events will be sent to websocket.

messages_config.receive_realtime_processing_events

boolean

default:true

If true, realtime processing events will be sent to websocket.

messages_config.receive_post_processing_events

boolean

default:true

If true, post-processing events will be sent to websocket.

messages_config.receive_acknowledgments

boolean

default:true

If true, acknowledgments will be sent to websocket.

messages_config.receive_errors

boolean

default:true

If true, errors will be sent to websocket.

messages_config.receive_lifecycle_events

boolean

default:false

If true, lifecycle events will be sent to websocket.

callback

boolean

default:false

If true, messages will be sent to configured url.

callback_config

object

Specify the callback configuration

Show child attributes

callback_config.url

string<uri>

URL on which we will do a POST request with configured messages

Example:

"https://callback.example"

callback_config.receive_partial_transcripts

boolean

default:false

If true, partial transcript will be sent to the defined callback.

callback_config.receive_final_transcripts

boolean

default:true

If true, final transcript will be sent to the defined callback.

callback_config.receive_speech_events

boolean

default:false

If true, begin and end speech events will be sent to the defined callback.

callback_config.receive_pre_processing_events

boolean

default:true

If true, pre-processing events will be sent to the defined callback.

callback_config.receive_realtime_processing_events

boolean

default:true

If true, realtime processing events will be sent to the defined callback.

callback_config.receive_post_processing_events

boolean

default:true

If true, post-processing events will be sent to the defined callback.

callback_config.receive_acknowledgments

boolean

default:false

If true, acknowledgments will be sent to the defined callback.

callback_config.receive_errors

boolean

default:false

If true, errors will be sent to the defined callback.

callback_config.receive_lifecycle_events

boolean

default:true

If true, lifecycle events will be sent to the defined callback.

Response

The live job has been initiated

string<uuid>

required

Id of the job

Example:

"45463597-20b7-4af7-b3b3-f5fb778203ab"

created_at

string<date-time>

required

Creation date

Example:

"2023-12-28T09:04:17.210Z"

url

string<uri>

required

The websocket url to connect to for sending audio data. The url will contain the temporary token to authenticate the session.

Example:

"wss://api.gladia.io/v2/live?token=4a39145c-2844-4557-8f34-34883f7be7d9"

API Documentation

Live endpoints

Pre-recorded endpoints

Transcription (deprecated)

Initiate a session

Authorizations

Query Parameters

Body

Response