Stream Audio To Dictation Session

GET

transcribe

cURL

curl --request GET \
  --url https://sdp.suki.ai/ws/transcribe \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --header 'transcription_session_id: <transcription_session_id>'

import requests

url = "https://sdp.suki.ai/ws/transcribe"

headers = {
    "transcription_session_id": "<transcription_session_id>",
    "sdp_suki_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    transcription_session_id: '<transcription_session_id>',
    sdp_suki_token: '<api-key>'
  }
};

fetch('https://sdp.suki.ai/ws/transcribe', 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://sdp.suki.ai/ws/transcribe",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>",
    "transcription_session_id: <transcription_session_id>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://sdp.suki.ai/ws/transcribe"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("transcription_session_id", "<transcription_session_id>")
	req.Header.Add("sdp_suki_token", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/ws/transcribe")
  .header("transcription_session_id", "<transcription_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/ws/transcribe")

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

request = Net::HTTP::Get.new(url)
request["transcription_session_id"] = '<transcription_session_id>'
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

Use this WebSocket endpoint to stream audio to an active session for real-time transcription. For the complete workflow, usage guidelines, wire format, message order, and error handling, refer to the Audio dictation and Dictation streaming guides.

For a single guide that compares /ws/stream and /ws/transcribe (handshake, proxy behavior, and message shapes), refer to Audio streaming guide.
Stream audio in chunks for the best latency and throughput.
For partial and final inbound transcript frames, EOF, and session state rules, refer to Dictation streaming.

If the dictation session is RUNNING, COMPLETED, or in another state, the WebSocket handshake fails with FailedPrecondition (for example transcript session is not accepting new speech sessions).

Inbound transcript messages

The server sends JSON text frames that include transcript, is_final, and transcript_id. Use is_final to identify whether the transcript is a partial result or a final result. After the audio stream ends, the server sends { "transcript": { "transcript": "EOF" } } and then closes the WebSocket connection. Refer to Dictation streaming for frame examples, words and speaker IDs on finals, and client-side filtering rules.

Authentication

Authentication is applied during the WebSocket handshake. The method depends on your client type. Use Sec-WebSocket-Protocol header for browser clients, and sdp_suki_token and transcription_session_id headers for non-browser clients.

Browser clients

If you are connecting from a browser, you must use the Sec-WebSocket-Protocol header during the WebSocket handshake. The header must specify the SukiAmbientAuth protocol, followed by the token and the transcription session ID in the following format.

Sec-WebSocket-Protocol: SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>

Non-browser clients

If you are connecting from a non-browser client, such as a mobile or server-side application, you must provide the token and session ID as separate HTTP headers in the initial WebSocket upgrade request.

sdp_suki_token: Session token from login.
sdp_provider_id: Provider identifier. Optional for standard partners; Required for Single Auth Token authentication.
transcription_session_id: The ID for the current session.

Important:

All messages must be sent as JSON text frames over the WebSocket connection.
Do not send raw binary data or use HTTP endpoints for streaming audio.

Code examples

Python
TypeScript

# pip install websocket-client
import base64
import json
import websocket

# Replace with values from Create dictation session and your authentication flow.
transcription_session_id = "<transcription_session_id>"
sdp_suki_token = "<sdp_suki_token>"
sdp_provider_id = "<sdp_provider_id>"  # Optional; Required for Single Auth Token authentication

# Staging WebSocket URL
ws_url = "wss://sdp.suki-stage.com/ws/transcribe"

ws = websocket.create_connection(
    ws_url,
    header=[
        f"sdp_suki_token: {sdp_suki_token}",
        f"sdp_provider_id: {sdp_provider_id}",
        f"transcription_session_id: {transcription_session_id}",
    ],
)

# If the file is WAV, skip the 44-byte header so payloads are PCM_S16LE only.
WAV_HEADER_BYTES = 44
CHUNK_BYTES = 3200  # Example chunk size; size your chunks to your capture pipeline.

try:
    with open("audio.wav", "rb") as audio_file:
        if WAV_HEADER_BYTES:
            audio_file.read(WAV_HEADER_BYTES)
        chunk = audio_file.read(CHUNK_BYTES)
        while chunk:
            msg = {
                "type": "AUDIO",
                "audioData": base64.b64encode(chunk).decode("ascii"),
            }
            ws.send(json.dumps(msg))
            chunk = audio_file.read(CHUNK_BYTES)
    ws.send(json.dumps({"type": "EVENT", "event": "AUDIO_END"}))
finally:
    ws.close()

// Browser example: same IDs as Python tab; add <input type="file" id="audioFile" /> in your HTML.

const transcriptionSessionId = '<transcription_session_id>';
const sdpSukiToken = '<sdp_suki_token>';

// Staging WebSocket URL
const ws = new WebSocket('wss://sdp.suki-stage.com/ws/transcribe', [
  `SukiAmbientAuth,${sdpSukiToken},${transcriptionSessionId}`,
]);

function uint8ToBase64(bytes: Uint8Array): string {
  let binary = '';
  for (let i = 0; i < bytes.byteLength; i += 1) {
    binary += String.fromCharCode(bytes[i]!);
  }
  return btoa(binary);
}

ws.onopen = () => {
  const input = document.getElementById('audioFile') as HTMLInputElement | null;
  const file = input?.files?.[0];
  if (!file) {
    console.error('Select a file for #audioFile');
    ws.close();
    return;
  }
  const reader = new FileReader();
  reader.onload = () => {
    const buffer = reader.result as ArrayBuffer;
    const wavHeaderBytes = 44; // Set to 0 if the file is already raw PCM.
    const pcm = new Uint8Array(buffer, wavHeaderBytes);
    const chunkSize = 3200;
    for (let offset = 0; offset < pcm.byteLength; offset += chunkSize) {
      const end = Math.min(offset + chunkSize, pcm.byteLength);
      const chunk = pcm.subarray(offset, end);
      ws.send(
        JSON.stringify({
          type: 'AUDIO',
          audioData: uint8ToBase64(chunk),
        }),
      );
    }
    ws.send(JSON.stringify({ type: 'EVENT', event: 'AUDIO_END' }));
  };
  reader.readAsArrayBuffer(file);
};

ws.onmessage = (event) => {
  const payload = JSON.parse(event.data as string);
  if (payload.transcript?.transcript === 'EOF') {
    console.log('End of transcription stream');
    return;
  }
  console.log('Partial:', !payload.is_final, payload.transcript?.transcript);
};

Authorizations

sdp_suki_token

string

header

required

Suki access token for the authenticated provider. Obtain this by calling Login or Register with a valid partner_token. Pass the suki_token value from the JSON response as the sdp_suki_token header on REST requests and non-browser WebSocket upgrades. Browser WebSocket clients pass the token in Sec-WebSocket-Protocol instead. Tokens expire after one hour; call Login again to refresh.

Headers

Sec-WebSocket-Protocol

string

Required FOR BROWSER CLIENTS ONLY. Sent during WebSocket handshake. Browsers must use the same subprotocol the grpc-wsproxy maps to Authorization: 'SukiAmbientAuth,<sdp_suki_token>,<transcription_session_id>' (comma-separated; token second, transcription session id third). Other names (e.g. SukiTranscriptionAuth) are not mapped and typically yield 401.

transcription_session_id

string

required

Required for non-browser clients only. UUID from Create Transcription Session.

sdp_provider_id

string

Optional - Stable identifier for the active provider. Omit for standard partners whose partner_token identifies the user. Required for Bearer partners and Single Auth Token authentication where multiple providers share one partner_token. Use the same provider_id you sent on Login or Register.

Example:

"provider-123"

Response

Switching Protocols - Indicates successful WebSocket handshake.

The response is of type string.

Last modified on June 30, 2026

Create Dictation Session

End Dictation Session

⌘I

cURL

curl --request GET \
  --url https://sdp.suki.ai/ws/transcribe \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --header 'transcription_session_id: <transcription_session_id>'

import requests

url = "https://sdp.suki.ai/ws/transcribe"

headers = {
    "transcription_session_id": "<transcription_session_id>",
    "sdp_suki_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    transcription_session_id: '<transcription_session_id>',
    sdp_suki_token: '<api-key>'
  }
};

fetch('https://sdp.suki.ai/ws/transcribe', 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://sdp.suki.ai/ws/transcribe",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "sdp_suki_token: <api-key>",
    "transcription_session_id: <transcription_session_id>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://sdp.suki.ai/ws/transcribe"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("transcription_session_id", "<transcription_session_id>")
	req.Header.Add("sdp_suki_token", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/ws/transcribe")
  .header("transcription_session_id", "<transcription_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/ws/transcribe")

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

request = Net::HTTP::Get.new(url)
request["transcription_session_id"] = '<transcription_session_id>'
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

​Inbound transcript messages

​Authentication

​Browser clients

​Non-browser clients

​Code examples

Authorizations

Headers

Response

Inbound transcript messages

Authentication

Browser clients

Non-browser clients

Code examples