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 Stream ambient audio over WebSocket, WebSocket streaming wire format, and Complete the session after streaming.

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
Token - Your sdp_suki_token
Ambient session ID - Your ambient session ID

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

For example:

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

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

Full code examples

For end-to-end ambient and Form filling streaming examples, start with these tutorials:

Build Ambient Streaming Client All Tutorials

Authorizations

sdp_suki_token

string

header

required

Suki access token (suki_token) from Login or Register. Expires after one hour.

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>,<ambient_session_id>' (comma-separated; token second, ambient session id third). Other subprotocol names are not mapped and typically yield 401.

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 for standard partners.

Required for:

Bearer authentication. Use the same provider_id returned by the Login or Register API.
Single Auth Token authentication. Include the same provider_id on every request as sdp_provider_id.

Example:

"provider-123"

Response

Switching Protocols - Indicates successful WebSocket handshake.

The response is of type string.

Last modified on July 23, 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

​Full code examples

Authorizations

Headers

Response

Prerequisites

Browser clients

Non-browser clients

Full code examples