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": 8,
  "sample_rate": 8000,
  "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_vocabulary_config": {
      "vocabulary": [
        "Westeros",
        {
          "value": "Stark"
        },
        {
          "value": "Night'\''s Watch",
          "pronunciations": [
            "Nightz Watch"
          ],
          "intensity": 0.4,
          "language": "en"
        }
      ],
      "default_intensity": 0.5
    },
    "custom_spelling": false,
    "custom_spelling_config": {
      "spelling_dictionary": {
        "Gettleman": [
          "gettleman"
        ],
        "SQL": [
          "Sequel"
        ]
      }
    },
    "translation": false,
    "translation_config": {
      "target_languages": [
        "en"
      ],
      "model": "base",
      "match_original_utterances": true,
      "lipsync": true,
      "context_adaptation": true,
      "context": "<string>",
      "informal": 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"
}
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"