> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hear speech-to-text

> Choose the right Hear endpoint for one file, live partials, or timestamped recording jobs.

Hear has three transcription surfaces. Pick by when the audio exists and what
the result must contain:

| You need                                            | Endpoint                              | Result                              | Scope                                 |
| --------------------------------------------------- | ------------------------------------- | ----------------------------------- | ------------------------------------- |
| Plain text from one file now                        | `POST /v1/audio/transcriptions`       | Synchronous text response           | `hear:transcribe`                     |
| Partials and finals while someone speaks            | `GET /v1/audio/transcriptions/stream` | WebSocket events                    | `hear:stream`                         |
| Timestamps, speakers, SRT/VTT, polling, or webhooks | `POST /v1/transcription/jobs`         | Async job with word/segment offsets | `hear:transcribe` + `transcribe:jobs` |

<Warning>
  Hear transcription is English-only. Send `language=en` or omit it. Any other
  Hear language value returns `400 unsupported_language`; use Omni for a
  multilingual end-to-end voice experience.
</Warning>

## Transcribe one file

Use the synchronous endpoint when the file is available now and your request can
wait for a text result:

```bash theme={null}
curl https://api.pyai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F file=@audio.wav \
  -F model=pyai-hear \
  -F language=en
```

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.

## Stream live speech

Use the WebSocket when a person is waiting for words to appear:

```text theme={null}
wss://api.pyai.com/v1/audio/transcriptions/stream
  ?protocol=pyai-hear-v1
  &language=en
  &sample_rate=16000
  &encoding=pcm16
  &interim_results=true
```

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](/guides/streaming-stt) 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.
* SRT or VTT output.
* A result that survives the submission request.
* Polling or a signed completion webhook.
* Idempotent URL-based submission.

The [timestamped jobs guide](/guides/async-transcription-jobs) 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`: per-call phrase boost and recasing.

Formatting can change the relationship between text and word timestamps. Read
[Format Hear transcripts](/guides/hear-transcript-formatting) before enabling
token-changing options on subtitles, legal audio, or compliance evidence.

## Phone audio

Hear streaming accepts PCM16 or Opus. Decode an 8 kHz phone codec before sending
PCM16, and do not confuse companding with resampling. The
[telephony audio reference](/reference/telephony-audio) gives the exact G.711
and sample-rate path.

<CardGroup cols={2}>
  <Card title="Stream live speech" href="/guides/streaming-stt">Partials, finals, endpointing, audio framing, and browser code.</Card>
  <Card title="Transcribe recordings" href="/guides/async-transcription-jobs">Timestamps, speakers, subtitles, jobs, and webhooks.</Card>
  <Card title="Format transcripts" href="/guides/hear-transcript-formatting">Numerals, punctuation, dictation, fillers, and vocabulary.</Card>
  <Card title="Language support" href="/reference/language-support">The English-only Hear contract and multilingual alternatives.</Card>
</CardGroup>