New to PyAI? Set up your key, then follow the
example below. The language table lists the
supported codes for each surface.
To mask personal, payment or medical details, use
STT redaction. The same
redact selectors work across
recordings, stereo, speaker diarization, synchronous uploads and live STT.
Transcribe one file
Use the synchronous endpoint when the file is available now and your request can wait for a text result.response_format: verbose_json adds transcript metadata; it does not guarantee
word timings or speaker labels. Use async jobs for those fields, including for
short recordings. The MCP transcribe_audio convenience tool uses the
synchronous path and does not expose diarization controls.
Choose a language and writing system
Use the known language for a monolingual recording. For mixed-language audio,
omit the hint and validate representative recordings. A supported language code
does not guarantee equal accuracy across accents or language switches.
Async jobs also accept
output_script: "latin" to write recognized speech in
Roman letters. Hindi stays Hindi; it is not translated into English. Omit this
option for the original script. The async language field is a separate Recap
summary setting. See async language and script options.
For example, Hindi आप कैसे हैं? can be written as Aap kaise hain? with
transcription_language: "hi" and output_script: "latin". Setting
transcription_language: "en" means English is spoken; it does not request
English letters or a translation. For mixed Hindi–English calls, omit
transcription_language and set output_script: "latin".
Stream live speech
Use the WebSocket when a person is waiting for words to appear:sample_rate=8000; Hear converts it before recognition and endpointing.
Other sample rates and compressed encodings receive 400 unsupported_audio_format.
Render partial as revisable UI. Commit final as the corrected transcript.
Send {"type":"commit"} when your application must force the current utterance
to finish, and keep streaming silence during normal pauses so server
endpointing can advance.
The streaming guide contains browser capture, framing,
event handling, endpointing, reconnect behavior, and a runnable example.
Process a finished recording
Use async jobs when you need any of these:- Word- or segment-level timestamps.
- Stereo channel separation or mono diarization. If diarization cannot be
produced for a recording, the job can complete with a transcript and no
speaker labels. Inspect
speakeronresult.segments; do not depend on amodefield in the public result. - SRT or VTT output.
- A result that survives the submission request.
- Polling or a signed completion webhook.
- Idempotent URL or multipart submission.
Format final transcripts
All three surfaces support final-text presentation options:numerals: digits or spoken-number form.smart_format: sentence capitalization and punctuation.dictation: spoken punctuation commands.drop_fillers: optional filled-pause removal.vocabulary: request-level or explicitly enabled stored terms for known vocabulary.
Phone audio
Hear streaming accepts mono PCM16 at 8 or 16 kHz. Decode an 8 kHz phone codec before sending PCM16, and do not confuse companding with resampling. The telephony audio reference gives the exact G.711 and sample-rate path.OpenAI compatibility
POST /v1/audio/transcriptions is OpenAI-shaped, so an existing OpenAI client
needs only a new base_url and key. OpenAI model names are accepted as aliases
for pyai-hear: whisper-1, gpt-4o-transcribe, and gpt-4o-mini-transcribe.
An alias is a name and nothing else — the request is always served by Hear, so
the alias never changes the transcript you get.
Stream live speech
Partials, finals, endpointing, audio framing, and browser code.
Transcribe recordings
Timestamps, speakers, subtitles, jobs, and webhooks.
Format transcripts
Numerals, punctuation, dictation, fillers, and vocabulary.
Language support
The Hear language matrix, quality status, and unsupported-language behavior.