Skip to main content
PyAI Hear converts spoken audio into text. Use a synchronous request for a file, a WebSocket for live speech, or an async job for timestamped recordings and completion callbacks. All three use your PyAI API key. Three surfaces. Pick by when the audio exists and what the result must contain: 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.
Example response; the text depends on your recording:
Supported file types are WAV, MP3, M4A, FLAC, and OGG. This compatibility surface is best for a simple migration or a short file when you do not need a durable job, speaker labels, subtitle artifacts, or contracted word offsets.

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:
Send mono little-endian PCM16. For 8 kHz telephony PCM, set 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 speaker on result.segments; do not depend on a mode field 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.
The timestamped jobs guide defines the response schema, decoded source-media timeline behavior, speaker labels, size limits, webhook signature, and retention.

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.
Formatting can change the relationship between text and word timestamps. Read Format Hear transcripts before enabling token-changing options on subtitles, legal audio, or compliance evidence.

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.

Failure recovery

See STT recovery for supported recorded and live paths, replay limits, and how to handle an incomplete session.