POST /v1/transcription/jobs, save the returned job_id, then poll
for the result or receive a signed webhook when transcription is ready.
Your key needs hear:transcribe and transcribe:jobs scopes.
For text without speakers or timestamps, use synchronous STT.
For audio that is arriving live, use streaming STT.
Submit a recording
Provide exactly one source:audio_url: an HTTPS URL PyAI can fetch. Maximum download size: 512 MiB. Include any source authorization in a short-lived signed URL; keep it valid long enough for processing. See retention.- Multipart
audio: upload one file, up to 1 GiB. Uploaded input audio is retained for up to 7 days.
result_url.
This example is for a stereo call with one participant per channel. Replace
both example URLs. For mono audio, omit channel, or use diarize: true for
speaker turns. Omit webhook_url if you prefer polling.
audio field:
Idempotency-Key. Choose one
source method per logical job and reuse its key after an uncertain response;
do not submit both examples for the same recording. See safe retries.
The submission returns 202 Accepted, for example:
Read the result or receive a callback
SetJOB_ID to the returned ID, then fetch the job:
queued or running, poll with backoff. Stop on completed,
failed, or cancelled. A completed job includes result, or a signed
result_url for a larger JSON result. Requested subtitle links appear in
result.formats.srt and result.formats.vtt.
To be notified automatically, set webhook_url at submission and handle
transcription.job.completed and transcription.job.failed. The
signed webhook receiver guide covers setup, signature verification,
and duplicate deliveries. Polling remains available to reconcile a missing callback.
Connect a post-call pipeline
- Submit once when the recording is ready. Save the returned
job_idagainst your own call ID; reuse the sameIdempotency-Keyif submission is uncertain. - Verify the callback signature over the raw request body. Durably enqueue the verified event, then acknowledge promptly.
- Fetch
GET /v1/transcription/jobs/{job_id}with your key. Use the job’s terminal state as the authority; store its result once per organization, project, and job. Duplicate callbacks must not create a second transcript or downstream action. - Reconcile a delayed callback by polling the saved ID with backoff. On
failed, preserve the failure reason and apply a bounded application retry policy. A completed job stays completed even if delivery of its callback fails.
Language and writing system
Choose the language being spoken separately from the letters used to write it. Hindi written in English letters is still Hindi.Hindi, English and mixed-language examples
These examples illustrate the writing system; exact wording and Roman spelling can vary with recognition.
Async jobs accept the 29 published STT language codes.
For a known monolingual recording, set
transcription_language. For mixed-language
audio, omit it and evaluate your recordings. Do not send "auto" as an async
language value; automatic detection is requested by omission. The result does
not currently include a detected-language code.
Mixed Hindi–English call in English letters
Send this JSON body toPOST /v1/transcription/jobs. Replace the recording URL.
This example uses stereo channels and PII redaction; omit channel for mono
audio. It deliberately omits transcription_language so recognition can handle
both languages.
"transcription_language": "hi" to that body.
For multipart uploads, use -F output_script=latin and omit the
transcription_language field for mixed speech.
Display the requested script
Readresult.text, result.words[].word, and result.segments[].text for
the selected writing system. When the job returns a result_url, read those
same fields from the downloaded result object.
With output_script: "latin", source_text and source_word intentionally
retain the original script. They may contain Hindi characters; use the presented
text fields above for a Roman-text display. Existing Latin text, timing, channel
labels, and numbers are preserved. Redaction runs before Romanization, so the
original-script fields are also protected when redaction is enabled.
Use
redact: ["pii", "pci"] for STT redaction, including
stereo and diarized results, subtitles, callbacks and recovery. Availability is
organization-controlled. The older trace: true scan is a separate entitled,
metered add-on. Trace alone does not support stereo or diarized jobs; combine it
with redact if you also need the Trace summary.Bias known names and terms
Setvocabulary when a recording contains known names, brands, products, or
other distinctive terms. The list is optional and applies only to that job.
Omitting it preserves the normal transcription path unless your organization
has explicitly enabled stored vocabulary for the batch profile.
PyAI sanitizes the list before saving the job:
- Surrounding whitespace is trimmed and repeated internal whitespace is collapsed.
- Non-string entries and terms shorter than 4 characters are ignored.
- Terms longer than 64 characters are ignored.
- Phrases longer than 5 words are ignored.
- Common-only terms are ignored.
- Matching is case-insensitive for duplicates. The first spelling and order are preserved.
- The first 5 valid terms are used. Extra terms are ignored.
vocabulary were omitted. The field does not choose
the transcription language. Vocabulary biases recognition toward the listed
terms; use output_script separately to choose the writing system. Job responses keep their
existing shape and do not echo the vocabulary.
Current common-word denylist
Current common-word denylist
A phrase is removed only when every normalized word is in this list. A phrase
such as
Acme Support remains eligible because Acme is distinctive.Stored organization vocabulary
UsePUT /v1/hear/vocabulary with the hear:configure scope to save up to five organization-owned terms.
Stored terms remain inactive until enabled_for includes batch. If a job also
sends vocabulary, those request terms come first and stored suggestions fill
remaining slots up to five. The effective list is saved with the job and stays
the same on every chunk, retry, and fallback.
Hear does not read a global glossary. It also does not automatically import
names from a CRM, dialer, or callee record. Automatic ingestion is a separate
follow-up.
Timestamped result
Readresult from GET /v1/transcription/jobs/{id}. For a large result, fetch
the signed result_url. The downloaded JSON has the same fields as the inline
result object.
A completed job can have a full transcript with partial word timings. In this
example, Hear measured “Hello” and retained “everyone” with its timing marked
unavailable.
start, end, and audio_seconds are decimal seconds. Word and segment
offsets start at 0.0 on the decoded source-media timeline. Leading,
inter-word, and trailing silence are not removed or compacted. Resampling and
internal chunking do not shift later offsets.
When timing recovery leaves any word unmeasured, the result includes
word_timing_status: "partial". Read words in order to display the full
transcript. Highlight a word only when its start and end are numbers and
end > start. Entries with timing_status: "unavailable" have two null
offsets. You can still timestamp their sentence using the segment bounds when
available. Wholly measured results omit word_timing_status.
The same rule applies to redacted words and to Roman-script output. Display
word for the selected script. When output_script: "latin" adds
source_word, both forms refer to the same timing entry.
confidence is optional. Formatting can attach punctuation to a word.
dictation and drop_fillers can change the displayed words. On a partial
result, displayed words that cannot be matched to a measured interval also
have null offsets. On wholly measured input, these options can still clear
words if the rewritten transcript cannot be safely realigned.
Segments are subtitle-ready spans. Their boundaries can change at a pause or
when the speaker or channel changes.
Speaker diarization and channel separation
For a complete mono-audio example, fallback handling, and the distinction between speaker labels and identity, see the speaker diarization guide.- For stereo audio, use
channel: true. Channel 0 isspeaker_1, channel 1 isspeaker_2. Separation is channel-based and exact, but labels are neutral: PyAI does not infer which channel is the agent or customer. - For mono audio, use
diarize: true. Speaker labels are model-derived and identify turns within that result. Do not use them as stable person IDs across separate jobs. If diarization cannot be produced for a recording, the job can still complete with a transcript and no speaker labels. Check whether returned segments containspeakerbefore relying on speaker attribution. - Do not set both options. Prefer
channelwhenever each participant already occupies a separate channel.
Idempotency, cancellation, and failures
Idempotency-Key applies to JSON and multipart submissions and is scoped to
the authenticated project. The same key and normalized processing options
return the original durable job. For uploads, keep the audio bytes and filename
unchanged too. Changing the source, filename, or processing options while
reusing a key returns 409 idempotency_conflict.
Keep the original key after a timeout or lost response. Retrying does not
restart a completed, failed, or cancelled job, or create another billing identity.
Without an idempotency key, separate submissions can create separate jobs.
DELETE /v1/transcription/jobs/{id} cancels queued or running work. It is
idempotent on terminal jobs, but it is not a data-erasure endpoint.
A failed job has status: "failed" and a normalized human-readable error.
That field is not a stable machine-readable failure code. Submission,
authorization, billing, and rate failures use the codes in
Errors and limits.
Signed webhooks
Whenwebhook_url is set, PyAI sends:
transcription.job.failed. Verify the exact request
body with X-PyAI-Signature:
X-PyAI-Event-Id or the
delivery Idempotency-Key, checking the signed payload identity as well.
Use your organization’s signing secret, separate from the API key. The
webhook guide explains obtaining the secret and verifying the raw
body; do not rotate a working receiver’s secret merely to try an example.
Retention and data use
Async jobs are not a zero-retention surface:- URL-fetched input is normally processed transiently. Organizations explicitly enabled for transcription fallback can have bounded chunks stored privately for processing and recovery. Completed fallback inputs are deleted; unresolved inputs expire within 7 days.
- Uploaded input audio is retained for up to 7 days.
- Job result artifacts are retained for up to 30 days.
- Signed result links normally expire after 7 days.
- There is no
store: falsejob option and cancellation does not erase data.
Pricing, rate limits, and versioning
result.audio_seconds reports the decoded recording duration. For current rates,
metering rules, included usage, and plan availability, see the
pricing page. Your key’s request rate, burst,
concurrency, and quota posture are returned by GET /v1/me.
There is no published job-completion timeout SLA. Processing time depends on
media length, queue load, diarization, and requested formats.
Every control-plane response includes X-PyAI-Contract-Version, which matches
the live OpenAPI info.version. The transcription result does not currently
echo a model version or a separate result-schema version.
API reference
Exact request and response schemas.
Format Hear transcripts
Punctuation, dictation, fillers, and timestamp realignment.
Security and data
Retention windows, tenancy, and regions.
Errors and limits
Stable request errors and retry guidance.