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.
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 audio in your product guide for recommendations.
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:
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.