Initiate a session

POST /v2/live

Creates a live session with its options and returns the WebSocket URL to stream its audio to.

Authentication: your API key in the x-gladia-key header (Authentication).

Example

curl -X POST https://eu1.api.gladia.io/v2/live \
  -H "x-gladia-key: $GLADIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "encoding": "wav/pcm",
    "sample_rate": 16000,
    "bit_depth": 16,
    "channels": 1,
    "model": "solaria-3",
    "language_config": {
      "languages": [
        "en"
      ]
    },
    "messages_config": {
      "receive_partial_transcripts": true
    }
  }'

import os

import requests

API_URL = os.environ.get("GLADIA_API_URL", "https://eu1.api.gladia.io")
response = requests.post(
    f"{API_URL}/v2/live",
    headers={"x-gladia-key": os.environ["GLADIA_API_KEY"]},
    json={
        "encoding": "wav/pcm",
        "sample_rate": 16000,
        "bit_depth": 16,
        "channels": 1,
        "model": "solaria-3",
        "language_config": {
            "languages": [
                "en"
            ]
        },
        "messages_config": {
            "receive_partial_transcripts": True
        }
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const API_URL = process.env.GLADIA_API_URL ?? "https://eu1.api.gladia.io";
const response = await fetch(`${API_URL}/v2/live`, {
  method: "POST",
  headers: {
    "x-gladia-key": process.env.GLADIA_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "encoding": "wav/pcm",
    "sample_rate": 16000,
    "bit_depth": 16,
    "channels": 1,
    "model": "solaria-3",
    "language_config": {
      "languages": [
        "en"
      ]
    },
    "messages_config": {
      "receive_partial_transcripts": true
    }
  }),
});
if (!response.ok) {
  throw new Error(`${response.status} ${await response.text()}`);
}
console.log(await response.json());

Try it

API address API key (kept in this tab only) region (query)

Body

Parameters

region string · query

Where the audio is processed. Every endpoint processes it in its own region (eu1: Europe, us1: United States); a region the endpoint does not serve finds no model and the session is refused.

one of: eu, us, eu-west, us-west

Body

encoding string

Encoding of the audio you send.

default: "wav/pcm" · one of: wav/pcm, wav/alaw, wav/ulaw
bit_depth integer

Bit depth of the audio. wav/alaw and wav/ulaw are 8-bit.

default: 16 · one of: 8, 16, 24, 32
sample_rate integer

Sample rate of the audio, in Hz.

default: 16000 · one of: 8000, 16000, 32000, 44100, 48000
channels integer

Number of interleaved audio channels. Each channel is transcribed on its own: put each speaker of a call on their own channel to know who said what without diarization.

default: 1 · 1 to 8
custom_metadata object

Any JSON object, kept with the session: returned by GET /v2/live/{id}, sent to your callback, and a filter of GET /v2/live.
model string

The model, by name, optionally with a latency profile (solaria-3-fast), or a latency profile alone (fast). Omitted: the default model of your account.

one of: solaria-3, solaria-1, trantoria-1, solaria-3-fast, solaria-3-medium, solaria-3-balanced, solaria-3-precise, solaria-1-fast, solaria-1-medium, solaria-1-balanced, solaria-1-precise, trantoria-1-fast, trantoria-1-medium, trantoria-1-balanced, trantoria-1-precise, fast, medium, balanced, precise
endpointing number

Silence, in seconds, that ends an utterance and produces its final transcript. Short values give faster finals and may cut sentences at hesitations.

default: 0.64 · 0.01 to 10
maximum_duration_without_endpointing number

Longest utterance, in seconds: a final is forced after this much speech without a pause. Omitted: no limit.

5 to 60
language_config object

The languages to expect.
2 fields
- languages array of string
  
  The languages that may be spoken (ISO 639-1 codes). Empty: the language is detected. One or more codes: the session is transcribed in the first one, unless code_switching.
- code_switching boolean
  
  Detect the language as the conversation goes, among languages when given: for speakers who switch languages.
  
  default: false
realtime_processing object

Processing applied to each final transcript, during the session.
8 fields
- custom_vocabulary boolean
  
  Bias the transcription toward the words of custom_vocabulary_config.
  
  default: false
- custom_vocabulary_config object
  
  The words to favour. Required with custom_vocabulary.
  
  default: null
  2 fields
  - vocabulary array of string or object required
    
    Words or phrases, as strings or as objects with their own options.
    
    3 fields
    
    value string required
    
    The word or phrase.
    
    intensity number
    
    How strongly it is favoured, from 0 to 1.
    
    default: null · 0 to 1
    
    pronunciations array of string
    
    Other ways it may be pronounced, written as they sound.
    
    default: null
  - default_intensity number
    
    How strongly the words are favoured, from 0 to 1, when an entry sets none.
    
    default: null · 0 to 1
- custom_spelling boolean
  
  Rewrite words as custom_spelling_config says.
  
  default: false
- custom_spelling_config object
  
  The spellings to apply. Required with custom_spelling.
  
  default: null
  1 fields
  - spelling_dictionary object required
    
    The spelling to write (key) for each variant heard (values): {"Gladia": ["gladya", "glad ia"]}. Whole words, case-insensitive.
- translation boolean
  
  Translate each final transcript into the target languages.
  
  default: false
- translation_config object
  
  The target languages. Required with translation.
  
  default: null
  1 fields
  - target_languages array of string required
    
    The languages to translate into (ISO 639-1 codes).
    
    at least 1 item(s)
- named_entity_recognition boolean
  
  The same as the top-level named_entity_recognition: true.
  
  default: false
- sentiment_analysis boolean
  
  The sentiment (positive, neutral, negative) and emotion of each final, in a sentiment_analysis message after it.
  
  default: false
messages_config object

The messages sent on the WebSocket.
9 fields
- receive_partial_transcripts boolean
  
  Partial transcripts, updated while the utterance is spoken.
  
  default: false
- receive_final_transcripts boolean
  
  The final transcript of each utterance.
  
  default: true
- receive_speech_events boolean
  
  speech_start and speech_end.
  
  default: true
- receive_pre_processing_events boolean
  
  Pre-processing messages.
  
  default: true
- receive_realtime_processing_events boolean
  
  Messages of the realtime processing: translation, named_entity_recognition, sentiment_analysis.
  
  default: true
- receive_post_processing_events boolean
  
  post_transcript and post_final_transcript, at the end.
  
  default: true
- receive_acknowledgments boolean
  
  audio_chunk and stop_recording acknowledgments.
  
  default: true
- receive_errors boolean
  
  error messages.
  
  default: true
- receive_lifecycle_events boolean
  
  start_recording, end_recording and end_session.
  
  default: false
callback boolean

Also send the session's messages to callback_config.url, by HTTP POST.

default: false
callback_config object

Where and which messages the callback receives. Required with callback.

default: null
10 fields
- url string required
  
  The HTTPS URL that receives the messages, one POST each.
  
  uri
- receive_partial_transcripts boolean
  
  Partial transcripts.
  
  default: false
- receive_final_transcripts boolean
  
  Final transcripts.
  
  default: true
- receive_speech_events boolean
  
  speech_start and speech_end.
  
  default: false
- receive_pre_processing_events boolean
  
  Pre-processing messages.
  
  default: true
- receive_realtime_processing_events boolean
  
  Messages of the realtime processing.
  
  default: true
- receive_post_processing_events boolean
  
  post_transcript and post_final_transcript.
  
  default: true
- receive_acknowledgments boolean
  
  Acknowledgments.
  
  default: false
- receive_errors boolean
  
  error messages.
  
  default: false
- receive_lifecycle_events boolean
  
  start_session, start_recording, end_recording and end_session.
  
  default: true
profile string

Latency profile: fast gives the earliest transcripts, precise the most accurate ones. The same as a profile in model.

default: null · one of: fast, medium, balanced, precise
diarization boolean

Speaker labels on single-channel audio: each utterance and word gets a speaker number.

default: false
diarization_config object

Diarization options.
2 fields
- number_of_speakers integer
  
  Expected number of speakers, when you know it.
  
  at least 1
- max_speakers integer
  
  Highest number of speakers to tell apart.
  
  at least 1
punctuation boolean

Punctuation and casing of the transcripts. On unless false.

default: true
end_of_turn boolean or object

End-of-turn detection for voice agents: an end_of_turn message when the speaker has finished their turn, judged from how they speak and not from silence alone. true uses the defaults (GET /v2/live/defaults), an object overrides some of them. Off when omitted.

default: false
7 fields
- threshold number
  
  End-of-turn probability, between 0 and 1 (excluded), above which the turn ends.
  
  default: null · 0 to 1
- silence_ms integer
  
  Silence, in milliseconds, before a turn is evaluated.
  
  default: null · 0 to 10000
- stop_s number
  
  Silence, in seconds, that ends the turn whatever the probability.
  
  default: null · 0 to 60
- emit_scores boolean
  
  Also send an end_of_turn_score message for each evaluation, to calibrate threshold.
  
  default: null
- window_s number
  
  Audio, in seconds, an evaluation reads before the silence (at most 8).
  
  default: null · 0 to 8
- speech_dbfs number
  
  Level, in dBFS, under which audio counts as silence.
  
  default: null · -100 to 0
- reeval_ms integer
  
  Interval, in milliseconds, between two evaluations of the same silence.
  
  default: null · 0 to 10000
numerals boolean or object

Spoken numbers, amounts and clock times written with digits in the final transcripts ("one thousand three hundred fifty five dollars" becomes "$1,355", "at nine fifteen" "at 9:15"); text_raw keeps the words. Where the turn router runs (the default; not with turn_router: false), it guides them: phone numbers are also written in their country's format ("06 12 34 56 78") and dates the language's way ("March 12, 2026"). true uses the countries of the language spoken, an object sets the country.

default: false
1 fields
- region string
  
  The country whose phone numbers and dates the transcripts are written in: an ISO 3166-1 alpha-2 code in capitals (CH, CA). Omitted: the countries where the language is spoken.
  
  default: null
named_entity_recognition boolean or object

Named entities (people, places, organizations, dates, amounts…) tagged in the final transcripts, and a named_entity_recognition message after each final. true tags every type.

default: false
2 fields
- entities string or array of string or object
  
  Which types: a preset (pii, pci, phi, contact, financial, name, location, date…), a list of types and presets, or {"enable": [...], "disable": [...]}.
  2 fields
  - enable array of string
  - disable array of string
- threshold number
  
  Confidence, from 0 to 1, under which an entity is ignored.
  
  default: 0.5 · 0 to 1
pii boolean or object

Personal data (names, phone numbers, emails, card numbers…) redacted in the final transcripts, and a pii message after each final. With redaction on, no partial transcript is sent.

default: false
6 fields
- entities string or array of string or object
  
  Which types to redact: a preset (pii, the default; pci, phi, contact, financial…), a list of types and presets, or {"enable": [...], "disable": [...]}.
  
  default: "pii"
  2 fields
  - enable array of string
  - disable array of string
- mode string
  
  marker replaces the data with an element (<pii:phone_number id="1"/>), mask with mask characters inside the element, tag keeps the text inside the element.
  
  default: "marker" · one of: marker, mask, tag
- threshold number
  
  Confidence, from 0 to 1, under which a span is not redacted.
  
  default: 0.5 · 0 to 1
- mask_character string
  
  The character of mask mode.
  
  default: "*"
- coreference string
  
  How mentions of the same entity get the same id: heuristics (the default), exact (same text only) or off.
  
  default: "heuristics" · one of: heuristics, exact, off
- return_entities boolean
  
  Also return the redacted text in the pii message (text).
  
  default: false
turn_router boolean or object

The number hold: an utterance stays open while a number, an amount or an address is still being dictated, so it is not cut at each pause. On by default where the model supports it; false turns it off.
1 fields
- hold boolean
  
  The number hold.

Responses

201 The session is created.

id string required

Identifier of the session (a time-ordered UUID).
created_at string required

Creation date (ISO 8601, UTC).
url string required

WebSocket URL to stream the audio to. It carries a single-use token: connect within 60 seconds. Reconnecting to the same URL after a dropped connection resumes the session.

{
  "id": "0199d7a2-5c3e-7b41-9f0a-3c2d1e4f5a6b",
  "created_at": "2026-10-12T09:04:17.210Z",
  "url": "wss://eu1.api.gladia.io/v2/live?token=eyJhbGciOi..."
}

400 The request is invalid: validation_errors lists why.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

401 No API key, or an unknown one.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

402 Your workspace has no credits left (insufficient_credits): new sessions are refused until credits are added; sessions already running are not stopped.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

403 The key may not do this (its scopes, or the addresses it may be used from).

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

429 Your account already has its maximum number of open sessions.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

500 No model in this region runs the session as asked (its model, languages and features together), or none has room right now: no inference endpoint available.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}

503 The service cannot answer right now: try again.

{
  "statusCode": 400,
  "timestamp": "2026-10-12T09:04:17.210Z",
  "path": "/v2/live",
  "message": "Invalid parameter(s). See validation_errors for more details.",
  "request_id": "G-1a2b3c4d",
  "validation_errors": [
    "sample_rate Input should be 8000, 16000, 32000, 44100 or 48000"
  ],
  "error": "string"
}