Audio Streaming

WebSocket endpoint for real-time audio streaming during Ambient sessions

GET /ws/stream

cURL

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>'

101

"<string>"

Use this API to stream audio to the speech service over a WebSocket connection for ambient and Form filling sessions.

Related guides

Stream Ambient Audio Overview

Ambient Streaming Wire Format

Complete the Ambient Session after Streaming

Audio Capture Best Practices

Streaming Architecture Overview

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 type: 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.

To build the recorder UI states (Start, Pause, Stop) and when to open the socket, refer to Stream Ambient audio in your product guide for recommendations.

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 ambient session.

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

101

application/json

Switching Protocols - Indicates successful WebSocket handshake.

The response is of type string.