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

## Parameters

- `region` (query, string, one of: `eu`, `us`, `eu-west`, `us-west`): 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.

## Body

- `encoding` (string, default: `"wav/pcm"`, one of: `wav/pcm`, `wav/alaw`, `wav/ulaw`): Encoding of the audio you send.
- `bit_depth` (integer, default: `16`, one of: `8`, `16`, `24`, `32`): Bit depth of the audio. `wav/alaw` and `wav/ulaw` are 8-bit.
- `sample_rate` (integer, default: `16000`, one of: `8000`, `16000`, `32000`, `44100`, `48000`): Sample rate of the audio, in Hz.
- `channels` (integer, default: `1`, 1 to 8): 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.
- `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, 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`): 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.
- `endpointing` (number, default: `0.64`, 0.01 to 10): Silence, in seconds, that ends an utterance and produces its final transcript. Short values give faster finals and may cut sentences at hesitations.
- `maximum_duration_without_endpointing` (number, 5 to 60): Longest utterance, in seconds: a final is forced after this much speech without a pause. Omitted: no limit.
- `language_config` (object): The languages to expect.
  - `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, default: `false`): Detect the language as the conversation goes, among `languages` when given: for speakers who switch languages.
- `realtime_processing` (object): Processing applied to each final transcript, during the session.
  - `custom_vocabulary` (boolean, default: `false`): Bias the transcription toward the words of `custom_vocabulary_config`.
  - `custom_vocabulary_config` (object, default: `null`): The words to favour. Required with `custom_vocabulary`.
    - `vocabulary` (array of string or object, required): Words or phrases, as strings or as objects with their own options.
      - `value` (string, required): The word or phrase.
      - `intensity` (number, default: `null`, 0 to 1): How strongly it is favoured, from 0 to 1.
      - `pronunciations` (array of string, default: `null`): Other ways it may be pronounced, written as they sound.
    - `default_intensity` (number, default: `null`, 0 to 1): How strongly the words are favoured, from 0 to 1, when an entry sets none.
  - `custom_spelling` (boolean, default: `false`): Rewrite words as `custom_spelling_config` says.
  - `custom_spelling_config` (object, default: `null`): The spellings to apply. Required with `custom_spelling`.
    - `spelling_dictionary` (object, required): The spelling to write (key) for each variant heard (values): `{"Gladia": ["gladya", "glad ia"]}`. Whole words, case-insensitive.
  - `translation` (boolean, default: `false`): Translate each final transcript into the target languages.
  - `translation_config` (object, default: `null`): The target languages. Required with `translation`.
    - `target_languages` (array of string, required, at least 1 item(s)): The languages to translate into (ISO 639-1 codes).
  - `named_entity_recognition` (boolean, default: `false`): The same as the top-level `named_entity_recognition: true`.
  - `sentiment_analysis` (boolean, default: `false`): The sentiment (positive, neutral, negative) and emotion of each final, in a `sentiment_analysis` message after it.
- `messages_config` (object): The messages sent on the WebSocket.
  - `receive_partial_transcripts` (boolean, default: `false`): Partial transcripts, updated while the utterance is spoken.
  - `receive_final_transcripts` (boolean, default: `true`): The final transcript of each utterance.
  - `receive_speech_events` (boolean, default: `true`): `speech_start` and `speech_end`.
  - `receive_pre_processing_events` (boolean, default: `true`): Pre-processing messages.
  - `receive_realtime_processing_events` (boolean, default: `true`): Messages of the realtime processing: `translation`, `named_entity_recognition`, `sentiment_analysis`.
  - `receive_post_processing_events` (boolean, default: `true`): `post_transcript` and `post_final_transcript`, at the end.
  - `receive_acknowledgments` (boolean, default: `true`): `audio_chunk` and `stop_recording` acknowledgments.
  - `receive_errors` (boolean, default: `true`): `error` messages.
  - `receive_lifecycle_events` (boolean, default: `false`): `start_recording`, `end_recording` and `end_session`.
- `callback` (boolean, default: `false`): Also send the session's messages to `callback_config.url`, by HTTP POST.
- `callback_config` (object, default: `null`): Where and which messages the callback receives. Required with `callback`.
  - `url` (string, required, uri): The HTTPS URL that receives the messages, one POST each.
  - `receive_partial_transcripts` (boolean, default: `false`): Partial transcripts.
  - `receive_final_transcripts` (boolean, default: `true`): Final transcripts.
  - `receive_speech_events` (boolean, default: `false`): `speech_start` and `speech_end`.
  - `receive_pre_processing_events` (boolean, default: `true`): Pre-processing messages.
  - `receive_realtime_processing_events` (boolean, default: `true`): Messages of the realtime processing.
  - `receive_post_processing_events` (boolean, default: `true`): `post_transcript` and `post_final_transcript`.
  - `receive_acknowledgments` (boolean, default: `false`): Acknowledgments.
  - `receive_errors` (boolean, default: `false`): `error` messages.
  - `receive_lifecycle_events` (boolean, default: `true`): `start_session`, `start_recording`, `end_recording` and `end_session`.
- `profile` (string, default: `null`, one of: `fast`, `medium`, `balanced`, `precise`): Latency profile: `fast` gives the earliest transcripts, `precise` the most accurate ones. The same as a profile in `model`.
- `diarization` (boolean, default: `false`): Speaker labels on single-channel audio: each utterance and word gets a `speaker` number.
- `diarization_config` (object): Diarization options.
  - `number_of_speakers` (integer, at least 1): Expected number of speakers, when you know it.
  - `max_speakers` (integer, at least 1): Highest number of speakers to tell apart.
- `punctuation` (boolean, default: `true`): Punctuation and casing of the transcripts. On unless `false`.
- `end_of_turn` (boolean or object, default: `false`): 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.
  - `threshold` (number, default: `null`, 0 to 1): End-of-turn probability, between 0 and 1 (excluded), above which the turn ends.
  - `silence_ms` (integer, default: `null`, 0 to 10000): Silence, in milliseconds, before a turn is evaluated.
  - `stop_s` (number, default: `null`, 0 to 60): Silence, in seconds, that ends the turn whatever the probability.
  - `emit_scores` (boolean, default: `null`): Also send an `end_of_turn_score` message for each evaluation, to calibrate `threshold`.
  - `window_s` (number, default: `null`, 0 to 8): Audio, in seconds, an evaluation reads before the silence (at most 8).
  - `speech_dbfs` (number, default: `null`, -100 to 0): Level, in dBFS, under which audio counts as silence.
  - `reeval_ms` (integer, default: `null`, 0 to 10000): Interval, in milliseconds, between two evaluations of the same silence.
- `numerals` (boolean or object, default: `false`): 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.
  - `region` (string, default: `null`): 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.
- `named_entity_recognition` (boolean or object, default: `false`): 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.
  - `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": [...]}`.
    - `enable` (array of string)
    - `disable` (array of string)
  - `threshold` (number, default: `0.5`, 0 to 1): Confidence, from 0 to 1, under which an entity is ignored.
- `pii` (boolean or object, default: `false`): 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.
  - `entities` (string or array of string or object, default: `"pii"`): Which types to redact: a preset (`pii`, the default; `pci`, `phi`, `contact`, `financial`…), a list of types and presets, or `{"enable": [...], "disable": [...]}`.
    - `enable` (array of string)
    - `disable` (array of string)
  - `mode` (string, default: `"marker"`, one of: `marker`, `mask`, `tag`): `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.
  - `threshold` (number, default: `0.5`, 0 to 1): Confidence, from 0 to 1, under which a span is not redacted.
  - `mask_character` (string, default: `"*"`): The character of `mask` mode.
  - `coreference` (string, default: `"heuristics"`, one of: `heuristics`, `exact`, `off`): How mentions of the same entity get the same `id`: `heuristics` (the default), `exact` (same text only) or `off`.
  - `return_entities` (boolean, default: `false`): Also return the redacted text in the `pii` message (`text`).
- `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.
  - `hold` (boolean): The number hold.

Example:

```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
  }
}
```

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

```json
{
  "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.

### 401

No API key, or an unknown one.

### 402

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

### 403

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

### 429

Your account already has its maximum number of open sessions.

### 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`.

### 503

The service cannot answer right now: try again.

## Example

```bash
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
    }
  }'
```