Skip to main content
Use async Hear jobs when you need timestamps, speaker separation, SRT/VTT subtitles, or processing that should continue after the request disconnects. Submit to 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.
Connected projects can also use the separately enabled GPT-Live import source; see the API reference for that connection’s requirements. The input must contain a decodable audio stream. There is no separate media duration ceiling. Request JSON, SRT, or VTT output. The JSON result is returned inline unless it is large enough to require a signed 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.
Or upload the audio directly, using the audio field:
JSON and multipart submissions both support 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

Set JOB_ID to the returned ID, then fetch the job:
While status is 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

  1. Submit once when the recording is ready. Save the returned job_id against your own call ID; reuse the same Idempotency-Key if submission is uncertain.
  2. Verify the callback signature over the raw request body. Durably enqueue the verified event, then acknowledge promptly.
  3. 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.
  4. 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.
Internal STT recovery, when enabled, uses the same job and callback. Your receiver does not need a separate backup integration. It also does not guarantee that every call finishes within the trial processing budget.

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.
transcription_language: "en" means English speech, not “write Hindi in English letters.” To get Hindi in English letters, use output_script: "latin". Neither field translates Hindi into English.

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 to POST /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.
For Hindi-only audio, add "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

Read result.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

Set vocabulary 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:
  1. Surrounding whitespace is trimmed and repeated internal whitespace is collapsed.
  2. Non-string entries and terms shorter than 4 characters are ignored.
  3. Terms longer than 64 characters are ignored.
  4. Phrases longer than 5 words are ignored.
  5. Common-only terms are ignored.
  6. Matching is case-insensitive for duplicates. The first spelling and order are preserved.
  7. The first 5 valid terms are used. Extra terms are ignored.
Invalid vocabulary entries do not reject the job. If every entry is removed, the job runs exactly as if 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.
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

Use PUT /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

Read result 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 is speaker_1, channel 1 is speaker_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 contain speaker before relying on speaker attribution.
  • Do not set both options. Prefer channel whenever 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

When webhook_url is set, PyAI sends:
Failure deliveries use transcription.job.failed. Verify the exact request body with X-PyAI-Signature:
Reject stale timestamps and deduplicate retries using 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: false job option and cancellation does not erase data.
Customer Content remains yours. The Terms of Service grant PyAI a limited license to process it solely to provide the Services. The no-training warranty applies by default to customer content and generated outputs; no API opt-out flag is required. Retention is separate. If you require contractual zero-retention, a deletion SLA, a subprocessor schedule, or backup-retention terms, confirm those requirements in a data-processing agreement before sending production data. PyAI currently processes data in one US region and does not offer India data residency. See Security and data handling and Reliability and regions.

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.