curl --request GET \
--url https://api.pyai.com/v1/audio/transcriptions/stream \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.pyai.com/v1/audio/transcriptions/stream"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("https://api.pyai.com/v1/audio/transcriptions/stream")
.header("Authorization", "Bearer <token>")
.asString();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>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Stream transcription (WebSocket)
Upgrade to a WebSocket for streaming speech-to-text. Partial captions are optional and revisable. Protected streams can return finals only. Requires the hear:stream scope. The only frame protocol is pyai-hear-v1, the published frame catalog below.
Auth (trusted servers only): send the key as a subprotocol, together with the pyai.v1 marker: Sec-WebSocket-Protocol: pyai.v1, pyai-key.<API_KEY> (server clients may use ?api_key= instead). Offer both values: PyAI echoes only the marker and never reflects your key, and a 101 can only select a value the client offered. The key is validated and swapped for the internal upstream credential on the upgrade. Never expose a long-lived API key to browser code; proxy browser audio through your authenticated backend unless this product documents a scoped browser credential.
Set vocabulary only when the session has known names, brands, products, or other distinctive terms. This biases known vocabulary only when supplied for the session or enabled through the stored hear_stream profile. Request terms take priority and the effective list is fixed when the session opens.
Knowledge-base retrieval is off by default for plain transcription. Set grounding=true on the connect URL to opt in when the service has retrieval configured; it does not enable an unconfigured service. Omission or grounding=false skips retrieval. Retrieval may add a grounding list to speech_final and delays delivery while the bounded lookup completes. Opting out removes that lookup and its grounding add-on usage, while preserving transcript text, event order, and Hear usage. The option is fixed for the connection; only one lowercase true or false value is accepted. Invalid or repeated values return 400 invalid_grounding before the WebSocket opens.
Client -> server: stream mono little-endian PCM16 binary audio frames continuously at sample_rate=8000 or sample_rate=16000 (default). The service converts 8 kHz input before recognition and endpointing. Other formats are rejected with 400 unsupported_audio_format before the WebSocket opens. Send a JSON {"type":"commit"} text frame to force-finalize the current utterance (e.g. when your VAD detects end-of-turn). Completion frames may have empty text when the utterance contains no recognized speech; retain these acknowledgments when draining pending commits. Closing the socket also flushes a final for any buffered audio.
Set endpointing_ms on the connect URL or send {"type":"config","endpointing_ms":800} mid-session. It is the minimum trailing-pause length before an utterance may end. Turn detection may wait longer; an utterance always completes within max(endpointing_ms, 1500 ms) of streamed silence. Keep sending audio frames, including silence, while the caller pauses. Pausing the stream pauses the frame-driven clock.
Server -> client (JSON text frames):
type | When | Payload |
|---|---|---|
config_ack | after connect-time or mid-session endpointing config | {endpointing_ms, effective_floor_ms, effective_ceiling_ms, score_interval_ms, warnings}, the applied values and any validation warnings |
partial | when an interim result is available | {text, stable_text, active_text, utterance_id, t_ms}, the live hypothesis for that utterance_id |
partial_stable | when a prefix locks in | {text, utterance_id, t_ms}, the portion the recognizer no longer expects to revise |
speech_final | on endpoint/commit | {text, utterance_id, t_ms, audio_ms, endpoint_reason, start, end, words, word_timing_status}, end of an utterance. Utterance bounds, word spans, and timing status are optional. |
final | follows speech_final | {text, utterance_id, t_ms, audio_ms, endpoint_reason, start, end, words, word_timing_status}, corrected transcript. Save this version. Utterance bounds, word spans, and timing status are optional. |
transcript_gap | temporary redaction outage | {utterance_id, code}. Mark the affected utterance as missing and keep reading. |
usage | at session end | {product, meter, audio_seconds, minutes, units, word_timing_status, utterances_without_word_times} reports metered audio. The last two fields report coverage when a timed stream ends normally under the best-effort policy. |
error | on fault | {code, message} |
Handle text-only finals. When present, words: [{word, start, end}] and the utterance’s start and end use seconds from the beginning of audio on this socket, including silence. Formatting may map multiple words to a shared span. A redacted multiword entity can produce repeated placeholders at the original intervals. For two-speaker calls, send one mono stream per speaker, preserve silence, and order sentences by their utterance start plus any known stream offset. Highlight individual words only when both offsets are numeric and end is greater than start.
On accounts enabled for per-word coverage, the normal connection preserves the protected final text and all measured words. A word with no measured interval has start and end set to null and timing_status set to unavailable. Affected finals report word_timing_status as partial (some measured words) or unavailable (none). Use utterance start/end for sentence placement. A completed best-effort stream reports word_timing_status and utterances_without_word_times in terminal usage, then closes with 1000. Explicit strict mode reports word_timings_failed and closes with 1011 if timing remains incomplete. A recognition interruption or redaction gap still makes the session incomplete.
t_ms is elapsed server time when the event is created; audio_ms is the utterance’s active-speech length (the billed signal); utterance_id groups partials/finals for one utterance. Assert that config_ack.warnings is empty instead of inferring that a setting applied. Warning reasons include clamped_to_range, not_a_number, and unknown_config_field; invalid config leaves the session open. endpoint_reason reports why automatic endpointing fired, including peak_te_early for the high-confidence path and silence_backstop for the bounded fallback. Log it when tuning conversational turns. Cue grounding configuration frames remain reserved and cannot change the connect-time grounding option.
PyAI tries internal recovery if recognition becomes unavailable. If accepted audio still cannot be completely recognized, the server emits error with code: recognition_interrupted and closes with 1011. Treat that session as incomplete. Reconnecting starts a new timeline and does not recover audio from the previous socket. No further transcript results or automatic Recap are produced from the interrupted session. With redact, optional partial captions and all final text and words undergo protection before delivery. A temporary verifier outage can produce a text-free transcript_gap with code redaction_unavailable. Discard earlier captions for that utterance and continue reading. The session ends with redaction_failed and close 1011, and automatic Recap is skipped.
Close codes: 1000 normal · 1008 auth/policy (bad key, scope, revoked token) · 1011 engine error · 1013 admission temporarily busy · 4429 over concurrency cap.
Billing: metered active audio at the Hear rate ($0.001/min), speech time derived from transcript timing rather than connection wall-clock.
curl --request GET \
--url https://api.pyai.com/v1/audio/transcriptions/stream \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.pyai.com/v1/audio/transcriptions/stream"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("https://api.pyai.com/v1/audio/transcriptions/stream")
.header("Authorization", "Bearer <token>")
.asString();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>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Authorizations
Query Parameters
Knowledge-base retrieval and grounding add-on usage are off by default. Set true to opt in when the service has retrieval enabled; omission or false skips retrieval. Fixed at connection start; send a single lowercase true or false. Invalid or repeated values return 400 invalid_grounding before upgrade. Transcript text, event order, and Hear usage are unchanged.
Omit or use auto to detect the spoken language automatically. An explicit supported language code pins recognition for the session. Unsupported explicit values are rejected at the upgrade with 400 unsupported_language.
auto, en, es, fr, de, hi, it, pt, nl, zh, yue, ar, id, ko, th, vi, ja, tr, ms, sv, da, fi, pl, cs, fil, fa, el, hu, mk, ro, ru Optional on timed streams. Accounts enabled for per-word coverage keep streaming by default when word times are missing. best_effort requests a normal close and a timing coverage summary. strict requests word_timings_failed (1011) if any timing remains incomplete.
strict, best_effort Opt-in STT text redaction for all organizations. Select pci, pii, phi, numbers, aggressive_numbers, or individual entity types. English contextual entity recognition; digit masking also handles other scripts. Applies after primary or recovery transcription, before text, words, segments, subtitles and callbacks are returned. Does not mute source audio. Unknown selectors return 400; unavailable protection fails closed. See /guides/stt-redaction. Repeat the parameter or use comma-separated values. Protected prefixes may arrive before the final. A verifier outage can emit a text-free transcript_gap, and unrecovered protection failures end the stream with redaction_failed.
pci, phi, pii, numbers, account_number, age, bank_account, credit_card, credit_card_expiration, cvv, date, date_interval, dob, email_address, event, filename, gender_sexuality, healthcare_number, ip_address, location, location_address, location_city, location_coordinate, location_country, location_state, location_zip, money, name, name_given, name_family, name_medical_professional, numerical_pii, occupation, origin, passport_number, password, phone_number, physical_attribute, ssn, time, url, username, vehicle_id, condition, drug, injury, blood_type, medical_process, statistics, language, marital_status, organization, political_affiliation, religion, routing_number, zodiac_sign, aggressive_numbers, true, expiration, pin, email, us_phone Tri-state inverse-text normalization for English final transcripts (never interim partials). true renders spoken numbers as digits (phones, currency, dates, ordinals). false keeps those spans in spoken form. Omitted keeps the live engine default: number formatting is ON for finals. Independent of smart_format.
Opt-in English punctuation and sentence capitalization on final transcripts only. Interim partials are never formatted. May change only case and punctuation; any failure returns the unformatted final. Default false. Independent of numerals. Non-English requests are unchanged.
Optional per-session terms for known names, brands, products, and other distinctive phrases. PyAI trims entries, removes case-insensitive duplicates, and keeps the first spelling and order. Entries shorter than 4 characters, longer than 64 characters, longer than 5 words, or made only of common words are ignored. At most 5 effective terms are used. When stored vocabulary is enabled for hear_stream, request terms come first and stored suggestions fill any remaining slots. The effective list is fixed for the session and does not select transcription language. Send a comma-separated list or a JSON array string.
2048Minimum trailing-pause length in milliseconds (50-5000, clamped) before an utterance may end. Turn detection may wait longer; an utterance always completes within max(endpointing_ms, 1500 ms) of streamed silence. The same setting can be changed mid-session with {"type":"config","endpointing_ms":800}. Both paths emit config_ack; assert that warnings is empty. A non-empty warnings means a value was not applied verbatim, but the session remains open. Timing counts only audio you stream, including silence, so pausing the stream pauses the clock. {"type":"commit"} still forces immediate end-of-turn on the STT socket.
50 <= x <= 5000Response
Switching Protocols, the streaming transcription WebSocket is open.