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. The synchronous OpenAI-compatible endpoint returns plain text; timestamped recordings use POST /v1/transcription/jobs.
Hear transcription is English-only. The optional job language field controls Recap summarization language; it does not change transcription language and is not returned in the transcription result.

​
Submit a recording

Provide exactly one source:
  • audio_url: PyAI fetches an HTTPS URL transiently and does not write the input bytes to durable input storage. Maximum download size: 512 MiB.
  • Multipart audio: upload one file, up to 1 GiB. Uploaded input audio is retained for up to 7 days.
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.
Or upload the audio directly:
Multipart uploads are not deduplicated. Retry an ambiguous upload only after checking whether the original job was created; prefer audio_url plus Idempotency-Key when safe automatic retries are required. The submission returns 202 with status: "queued". Poll GET /v1/transcription/jobs/{job_id} until the status is completed, failed, or cancelled.

​
Timestamped result

This example shows the response shape and field units. The values are illustrative:
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. confidence is optional. Punctuation is attached to a word when formatting can be aligned safely; punctuation is not a separately timestamped token. dictation and drop_fillers can change the number of words. If the rewritten text cannot be safely realigned, the transcript remains available and words is empty. Segments are subtitle-ready spans built from the words. A segment starts when the speaker/channel changes or after a readable pause, so segment boundaries can change even when word timestamps do not.

​
Speaker labels

  • 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.
  • Do not set both options. Prefer channel whenever each participant already occupies a separate channel.

​
Idempotency, cancellation, and failures

Idempotency-Key applies to JSON audio_url submissions. Retrying the same key and body replays the original 202; using the key with a different body returns 409 idempotency_conflict. Multipart uploads are not deduplicated. 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. Mint or rotate the organization webhook secret with POST /v1/webhooks/signing-secret.

​
Retention and data use

Async jobs are not a zero-retention surface:
  • URL-fetched input bytes are not persisted.
  • 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 API does not expose a training opt-out flag. If you require contractual zero-retention, a no-training warranty, 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

Async Hear jobs are currently $0.0005/min, metered per second and rounded once at the invoice line. 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.