Skip to main content
POST
/
v2
/
live
Initiate a new live job
curl --request POST \
  --url https://api.gladia.io/v2/live \
  --header 'Content-Type: application/json' \
  --header 'x-gladia-key: <api-key>' \
  --data '
{
  "encoding": "wav/pcm",
  "bit_depth": 16,
  "sample_rate": 16000,
  "channels": 1,
  "custom_metadata": {
    "user": "John Doe"
  },
  "model": "solaria-1",
  "endpointing": 0.05,
  "maximum_duration_without_endpointing": 5,
  "language_config": {
    "languages": [],
    "code_switching": false
  },
  "pre_processing": {
    "audio_enhancer": false,
    "speech_threshold": 0.6
  },
  "realtime_processing": {
    "custom_vocabulary": false,
    "custom_spelling": false,
    "translation": false,
    "named_entity_recognition": false,
    "sentiment_analysis": false
  },
  "post_processing": {
    "summarization": false,
    "summarization_config": {
      "type": "general"
    },
    "chapterization": false
  },
  "messages_config": {
    "receive_partial_transcripts": false,
    "receive_final_transcripts": true,
    "receive_speech_events": true,
    "receive_pre_processing_events": true,
    "receive_realtime_processing_events": true,
    "receive_post_processing_events": true,
    "receive_acknowledgments": true,
    "receive_errors": true,
    "receive_lifecycle_events": false
  },
  "callback": false,
  "callback_config": {
    "url": "https://callback.example",
    "receive_partial_transcripts": false,
    "receive_final_transcripts": true,
    "receive_speech_events": false,
    "receive_pre_processing_events": true,
    "receive_realtime_processing_events": true,
    "receive_post_processing_events": true,
    "receive_acknowledgments": false,
    "receive_errors": false,
    "receive_lifecycle_events": true
  }
}
'
{
  "id": "45463597-20b7-4af7-b3b3-f5fb778203ab",
  "created_at": "2023-12-28T09:04:17.210Z",
  "url": "wss://api.gladia.io/v2/live?token=4a39145c-2844-4557-8f34-34883f7be7d9"
}

Documentation Index

Fetch the complete documentation index at: https://docs.gladia.io/llms.txt

Use this file to discover all available pages before exploring further.

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.
  • 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

​
pre_processing
object

Specify the pre-processing configuration

​
realtime_processing
object

Specify the realtime processing configuration

​
post_processing
object

Specify the post-processing configuration

​
messages_config
object

Specify the websocket messages configuration

​
callback
boolean
default:false

If true, messages will be sent to configured url.

​
callback_config
object

Specify the callback configuration

Response

The live job has been initiated

​
id
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"