Audio Streaming

GET

stream

cURL

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

import requests

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

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

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

print(response.text)

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

fetch('https://sdp.suki.ai/ws/stream', 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/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ambient_session_id: <ambient_session_id>",
    "sdp_suki_token: <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"
	"net/http"
	"io"
)

func main() {

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

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

	req.Header.Add("ambient_session_id", "<ambient_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/stream")
  .header("ambient_session_id", "<ambient_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

Use this API to stream audio to the speech service over a WebSocket connection for ambient and Form filling sessions. For more information on how to handle the handshake, wire format, message order, and error handling, refer to the Ambient audio streaming guide.

Prerequisites

Complete these steps before opening the WebSocket.

Opening /ws/stream before the session and context are ready often leads to handshake failures or a broken stream.

Authenticate and obtain sdp_suki_token
Create an ambient session with POST /api/v1/ambient/session/create. A successful create returns 201 Created; keep the ambient_session_id you used or received.
Seed session context with POST /api/v1/ambient/session/{ambient_session_id}/context. Send the JSON body your integration requires (see that endpoint for the full schema).
Authenticate and open the WebSocket on wss://sdp.suki-stage.com/ws/stream. To stream audio, you must first establish an authenticated WebSocket connection. The authentication method you use depends on your client types: browser or non-browser.

Browser clients

When connecting from a browser, include the Sec-WebSocket-Protocol header as part of the WebSocket handshake. Set the header value as a single comma-separated string. The order must be:

Subprotocol name
Ambient session ID - Your ambient session ID
Token - Your sdp_suki_token

Avoid adding spaces between values unless your client library requires it.

For example:

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

The server negotiates this subprotocol to establish the connection.

Non-browser clients

For non-browser clients such as mobile apps, backend services, or testing tools, pass authentication details as separate HTTP headers in the WebSocket upgrade request. Do not use the Sec-WebSocket-Protocol header. Include the following headers:

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

If you push non-JSON payloads where the server expects JSON, you can see parse errors (for example invalid character or null byte errors).

Code examples

Python
TypeScript

# pip install websocket-client
import base64
import json
from datetime import datetime, timezone

import websocket

ambient_session_id = "<ambient_session_id>"
token = "<sdp_suki_token>"
sdp_provider_id = "<sdp_provider_id>"  # Optional; Required for Single Auth Token authentication
CHUNK_BYTES = 3200
WAV_HEADER_BYTES = 44

# Non-browser: headers on upgrade. Staging WebSocket URL:
ws_url = "wss://sdp.suki-stage.com/ws/stream"
ws = websocket.create_connection(
    ws_url,
    header=[
        f"sdp_suki_token: {token}",
        f"sdp_provider_id: {sdp_provider_id}",
        f"ambient_session_id: {ambient_session_id}",
    ],
)


def b64(data: bytes) -> str:
    return base64.b64encode(data).decode("ascii")


try:
    rfc3339 = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    ws.send(json.dumps({"type": "START_TIME", "data": b64(rfc3339.encode("utf-8"))}))

    with open("audio.wav", "rb") as f:
        raw = f.read()
    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE":
        pcm = raw[WAV_HEADER_BYTES:]
    else:
        pcm = raw

    for i in range(0, len(pcm), CHUNK_BYTES):
        chunk = pcm[i : i + CHUNK_BYTES]
        ws.send(json.dumps({"type": "AUDIO", "data": b64(chunk)}))

    ws.send(json.dumps({"type": "AUDIO", "data": b64(b"EOF")}))

    while True:
        try:
            print(ws.recv())
        except websocket.WebSocketConnectionClosedException:
            break
finally:
    ws.close()

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

const ambientSessionId = '<ambient_session_id>';
const token = '<sdp_suki_token>';
const CHUNK_BYTES = 3200;
const WAV_HEADER_BYTES = 44;

function utf8ToBase64(s: string): string {
  const bytes = new TextEncoder().encode(s);
  let binary = '';
  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
  return btoa(binary);
}

function bytesToBase64(u8: Uint8Array): string {
  let binary = '';
  for (let i = 0; i < u8.length; i++) binary += String.fromCharCode(u8[i]!);
  return btoa(binary);
}

// Staging WebSocket URL
const ws = new WebSocket(`wss://sdp.suki-stage.com/ws/stream`, [
  `SukiAmbientAuth,${ambientSessionId},${token}`,
]);

ws.binaryType = 'arraybuffer';

ws.onopen = () => {
  const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
  ws.send(JSON.stringify({ type: 'START_TIME', data: utf8ToBase64(rfc3339) }));

  const input = document.getElementById('audioFile') as HTMLInputElement;
  const file = input.files?.[0];
  if (!file) return;

  const reader = new FileReader();
  reader.onload = () => {
    const buf = new Uint8Array(reader.result as ArrayBuffer);
    let pcm = buf;
    if (
      buf.length >= 12 &&
      buf[0] === 0x52 &&
      buf[1] === 0x49 &&
      buf[2] === 0x46 &&
      buf[3] === 0x46 &&
      buf[8] === 0x57 &&
      buf[9] === 0x41 &&
      buf[10] === 0x56 &&
      buf[11] === 0x45
    ) {
      pcm = buf.subarray(WAV_HEADER_BYTES);
    }
    for (let i = 0; i < pcm.length; i += CHUNK_BYTES) {
      const chunk = pcm.subarray(i, i + CHUNK_BYTES);
      ws.send(JSON.stringify({ type: 'AUDIO', data: bytesToBase64(chunk) }));
    }
    ws.send(
      JSON.stringify({
        type: 'AUDIO',
        data: bytesToBase64(new Uint8Array([0x45, 0x4f, 0x46])),
      }),
    );
  };
  reader.readAsArrayBuffer(file);
};

ws.onmessage = (ev) => console.log('Received:', ev.data);
ws.onerror = (e) => console.error(e);
ws.onclose = () => console.log('closed');

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. Format: 'SukiAmbientAuth,<ambient_session_id>,<sdp_suki_token>' (comma-separated, no spaces required between parts).

ambient_session_id

string

required

Required for non-browser clients only. Session UUID from Create Ambient Session or Create Form Filling 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

Ambient Session Metadata

End Ambient Session

⌘I

cURL

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

import requests

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

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

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

print(response.text)

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

fetch('https://sdp.suki.ai/ws/stream', 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/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ambient_session_id: <ambient_session_id>",
    "sdp_suki_token: <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"
	"net/http"
	"io"
)

func main() {

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

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

	req.Header.Add("ambient_session_id", "<ambient_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/stream")
  .header("ambient_session_id", "<ambient_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

​Prerequisites

​Browser clients

​Non-browser clients

​Code examples

Authorizations

Headers

Response

Prerequisites

Browser clients

Non-browser clients

Code examples