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
  }
}
'
import requests

url = "https://api.gladia.io/v2/live"

payload = {
    "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
    }
}
headers = {
    "x-gladia-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-gladia-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
    }
  })
};

fetch('https://api.gladia.io/v2/live', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gladia.io/v2/live",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-gladia-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gladia.io/v2/live"

	payload := strings.NewReader("{\n  \"encoding\": \"wav/pcm\",\n  \"bit_depth\": 16,\n  \"sample_rate\": 16000,\n  \"channels\": 1,\n  \"custom_metadata\": {\n    \"user\": \"John Doe\"\n  },\n  \"model\": \"solaria-1\",\n  \"endpointing\": 0.05,\n  \"maximum_duration_without_endpointing\": 5,\n  \"language_config\": {\n    \"languages\": [],\n    \"code_switching\": false\n  },\n  \"pre_processing\": {\n    \"audio_enhancer\": false,\n    \"speech_threshold\": 0.6\n  },\n  \"realtime_processing\": {\n    \"custom_vocabulary\": false,\n    \"custom_spelling\": false,\n    \"translation\": false,\n    \"named_entity_recognition\": false,\n    \"sentiment_analysis\": false\n  },\n  \"post_processing\": {\n    \"summarization\": false,\n    \"summarization_config\": {\n      \"type\": \"general\"\n    },\n    \"chapterization\": false\n  },\n  \"messages_config\": {\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": true,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": true,\n    \"receive_errors\": true,\n    \"receive_lifecycle_events\": false\n  },\n  \"callback\": false,\n  \"callback_config\": {\n    \"url\": \"https://callback.example\",\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": false,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": false,\n    \"receive_errors\": false,\n    \"receive_lifecycle_events\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-gladia-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.gladia.io/v2/live")
  .header("x-gladia-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"encoding\": \"wav/pcm\",\n  \"bit_depth\": 16,\n  \"sample_rate\": 16000,\n  \"channels\": 1,\n  \"custom_metadata\": {\n    \"user\": \"John Doe\"\n  },\n  \"model\": \"solaria-1\",\n  \"endpointing\": 0.05,\n  \"maximum_duration_without_endpointing\": 5,\n  \"language_config\": {\n    \"languages\": [],\n    \"code_switching\": false\n  },\n  \"pre_processing\": {\n    \"audio_enhancer\": false,\n    \"speech_threshold\": 0.6\n  },\n  \"realtime_processing\": {\n    \"custom_vocabulary\": false,\n    \"custom_spelling\": false,\n    \"translation\": false,\n    \"named_entity_recognition\": false,\n    \"sentiment_analysis\": false\n  },\n  \"post_processing\": {\n    \"summarization\": false,\n    \"summarization_config\": {\n      \"type\": \"general\"\n    },\n    \"chapterization\": false\n  },\n  \"messages_config\": {\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": true,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": true,\n    \"receive_errors\": true,\n    \"receive_lifecycle_events\": false\n  },\n  \"callback\": false,\n  \"callback_config\": {\n    \"url\": \"https://callback.example\",\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": false,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": false,\n    \"receive_errors\": false,\n    \"receive_lifecycle_events\": true\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.gladia.io/v2/live")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-gladia-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"encoding\": \"wav/pcm\",\n  \"bit_depth\": 16,\n  \"sample_rate\": 16000,\n  \"channels\": 1,\n  \"custom_metadata\": {\n    \"user\": \"John Doe\"\n  },\n  \"model\": \"solaria-1\",\n  \"endpointing\": 0.05,\n  \"maximum_duration_without_endpointing\": 5,\n  \"language_config\": {\n    \"languages\": [],\n    \"code_switching\": false\n  },\n  \"pre_processing\": {\n    \"audio_enhancer\": false,\n    \"speech_threshold\": 0.6\n  },\n  \"realtime_processing\": {\n    \"custom_vocabulary\": false,\n    \"custom_spelling\": false,\n    \"translation\": false,\n    \"named_entity_recognition\": false,\n    \"sentiment_analysis\": false\n  },\n  \"post_processing\": {\n    \"summarization\": false,\n    \"summarization_config\": {\n      \"type\": \"general\"\n    },\n    \"chapterization\": false\n  },\n  \"messages_config\": {\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": true,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": true,\n    \"receive_errors\": true,\n    \"receive_lifecycle_events\": false\n  },\n  \"callback\": false,\n  \"callback_config\": {\n    \"url\": \"https://callback.example\",\n    \"receive_partial_transcripts\": false,\n    \"receive_final_transcripts\": true,\n    \"receive_speech_events\": false,\n    \"receive_pre_processing_events\": true,\n    \"receive_realtime_processing_events\": true,\n    \"receive_post_processing_events\": true,\n    \"receive_acknowledgments\": false,\n    \"receive_errors\": false,\n    \"receive_lifecycle_events\": true\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "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"
}
{
  "timestamp": "2023-12-28T09:04:17.210Z",
  "path": "/v2/transcription/45463597-20b7-4af7-b3b3-f5fb778203ab",
  "request_id": "G-821fe9df",
  "statusCode": 400,
  "message": "Content-Type is missing Multipart Boundary.",
  "validation_errors": [
    "Field \"language\" must be a string",
    "Field \"min_speakers\" must be a number"
  ]
}
{
  "timestamp": "2023-12-28T09:04:17.210Z",
  "path": "/v2/transcription/45463597-20b7-4af7-b3b3-f5fb778203ab",
  "request_id": "G-821fe9df",
  "statusCode": 401,
  "message": "gladia key not found"
}
{
  "timestamp": "2023-12-28T09:04:17.210Z",
  "path": "/v2/transcription/45463597-20b7-4af7-b3b3-f5fb778203ab",
  "request_id": "G-821fe9df",
  "statusCode": 422,
  "message": "Invalid parameter"
}
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"