Stream transcription (WebSocket)

curl --request GET \
  --url https://api.pyai.com/v1/audio/transcriptions/stream \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pyai.com/v1/audio/transcriptions/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://api.pyai.com/v1/audio/transcriptions/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.pyai.com/v1/audio/transcriptions/stream"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/audio/transcriptions/stream")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

Hear

Stream transcription (WebSocket)

Upgrade to a WebSocket for low-latency streaming speech-to-text with eager partials (first partial typically within ~300 ms). Transcription-only, distinct from /v1/realtime (Omni duplex). Requires the hear:stream scope. With knowledge-base grounding enabled this surface becomes Cue (turn detection + retrieved context for your own LLM/voice pipeline), billed at the Cue rate.

Auth: browsers can’t set Authorization on a WebSocket, so send the key as a subprotocol: Sec-WebSocket-Protocol: pyai-key.<API_KEY> (server clients may use ?api_key= instead). The key is validated and swapped for the internal upstream credential on the upgrade.

Client -> server: stream binary audio frames continuously (PCM16 at the negotiated sample_rate, or opus). Send a JSON {"type":"commit"} text frame to force-finalize the current utterance (e.g. when your VAD detects end-of-turn); the literal text frame EOF is also accepted as an equivalent flush. Closing the socket also flushes a final for any buffered audio.

Server -> client (JSON text frames):

`type`	When	Payload
`partial`	every eager tick	`{text, stable_text, active_text, utterance_id, t_ms}`, the live hypothesis for that `utterance_id`
`speech_final`	on endpoint/commit	`{text, utterance_id, t_ms, audio_ms}`, stable, end of an utterance
`final`	follows `speech_final`	`{text, utterance_id, t_ms, audio_ms}`, corrected full-context transcript
`usage`	just before a graceful close	`{product, meter, audio_seconds, minutes}`, the session’s billed active-audio, so you can reconcile realtime spend in-band (a realtime WS carries no `x-pyai-units` response header). Best-effort; absent if the session had no billable audio or closed abnormally.
`error`	on fault	`{code, message}`

t_ms is the audio-timeline position of the hypothesis; audio_ms is the utterance’s active-speech length (the billed signal); utterance_id groups partials/finals for one utterance. With grounding enabled (Cue), speech_final/final frames also carry a grounding array: [{content, score}, ...] (top-K KB passages, [] when no KB is bound or retrieval times out). Enable + tune Cue with the first JSON frame {"type":"config","grounding":true}, optionally grounding_k (passages to retrieve, 1-20, default 3), grounding_min_score (drop passages below this score, 0-1, default 0), and grounding_timeout_ms (max wait at the final before failing open to [], 50-2000, default 450). Retrieval is fail-open: a slow/failed lookup yields grounding: [] and never stalls the turn.

Close codes: 1000 normal · 1008 auth/policy (bad key, scope, revoked token) · 1011 engine error · 4429 over concurrency cap.

Billing: metered active audio at the Hear rate ( $0.001/min), speech time derived from the transcript timing, not connection wall-clock. With grounding enabled (Cue), the session bills a single `cue.minutes` line at$ 0.015/min instead.

GET

audio

transcriptions

stream

Stream transcription (WebSocket)

curl --request GET \
  --url https://api.pyai.com/v1/audio/transcriptions/stream \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pyai.com/v1/audio/transcriptions/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://api.pyai.com/v1/audio/transcriptions/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.pyai.com/v1/audio/transcriptions/stream"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/audio/transcriptions/stream")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Query Parameters

model

string

default:pyai-hear

Streaming STT model.

language

string

ISO-639-1 language hint forwarded to the engine (e.g. en). English is the GA, benchmarked language today; other codes are accepted as hints but recognition accuracy is not yet published, see the Language support reference. One hint per session; there is no mid-session auto-detect.

sample_rate

integer

default:16000

Input PCM sample rate in Hz.

encoding

enum<string>

default:pcm16

Audio frame encoding.

Available options:

pcm16,

opus

interim_results

boolean

default:true

Emit eager partial hypotheses.

numerals

boolean

default:false

Format spoken numbers as digits in the transcript (e.g. 'one two three' → '123'). Same semantics as the batch numerals flag; forwarded to the engine. Useful for voice agents that read back phone numbers, codes, and amounts. Default false (spoken form).

seed

integer

Optional determinism seed for reproducible eval runs. Forwarded to the engine and honored once the engine supports it; no effect when omitted.

temperature

number

Optional sampling temperature for reproducible eval runs. Forwarded to the engine and honored once the engine supports it; no effect when omitted.

endpointing_ms

integer

Optional turn-segmentation tuning: the trailing-pause length (ms, 50-5000) that ends an utterance. Useful where turn-taking pacing differs. Clamped to the valid range and forwarded to the engine; honored once the engine supports it, a no-op when omitted. You can always force end-of-turn from the client with {"type":"commit"}.

Required range: 50 <= x <= 5000

Response

Switching Protocols, the streaming transcription WebSocket is open.

Identity

Call Integrations

Sandbox

Models

Hear

Speak

Agents

Studio

Transcription Jobs

Trace

Recap

Integrations

AMD

Omni

Knowledge Bases

Telephony

Realtime

Stream transcription (WebSocket)

Authorizations

Query Parameters

Response