> ## 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.

# Transcribe recordings with timestamps

> Submit async Hear jobs, read word and segment timestamps, preserve the media timeline, receive signed webhooks, and understand retention and limits.

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`.

<Info>
  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.
</Info>

## 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`.

```bash theme={null}
curl https://api.pyai.com/v1/transcription/jobs \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-481-v1" \
  -d '{
    "audio_url": "https://media.example.com/clip-481.wav",
    "channel": true,
    "output_formats": ["json", "srt", "vtt"],
    "webhook_url": "https://app.example.com/webhooks/pyai"
  }'
```

Or upload the audio directly:

```bash theme={null}
curl https://api.pyai.com/v1/transcription/jobs \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -F audio=@clip-481.wav \
  -F channel=true \
  -F output_formats=json,srt,vtt \
  -F webhook_url=https://app.example.com/webhooks/pyai
```

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:

```json theme={null}
{
  "job_id": "job_aZ09...",
  "status": "completed",
  "created_at": 1787220000000,
  "updated_at": 1787220012000,
  "result": {
    "text": "[speaker_1] Hello everyone.",
    "audio_seconds": 120,
    "speakers": 1,
    "words": [
      {
        "word": "Hello",
        "start": 0.42,
        "end": 0.81,
        "confidence": 0.98,
        "speaker": "speaker_1",
        "channel": 0
      }
    ],
    "segments": [
      {
        "id": 0,
        "text": "Hello everyone.",
        "start": 0.42,
        "end": 1.8,
        "speaker": "speaker_1",
        "channel": 0
      }
    ],
    "formats": {
      "srt": "https://storage.example/signed-result",
      "vtt": "https://storage.example/signed-result"
    }
  }
}
```

`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](/errors-and-limits).

## Signed webhooks

When `webhook_url` is set, PyAI sends:

```json theme={null}
{
  "type": "transcription.job.completed",
  "created": 1787220012,
  "data": {
    "job_id": "job_aZ09...",
    "status": "completed"
  }
}
```

Failure deliveries use `transcription.job.failed`. Verify the exact request
body with `X-PyAI-Signature`:

```text theme={null}
t=<unix_seconds>,v1=<hex_hmac>
HMAC-SHA256(secret, "<t>.<rawBody>")
```

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](https://pyai.com/legal/terms)
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](/security-and-data) and
[Reliability and regions](/reference/reliability).

## 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.

<CardGroup cols={2}>
  <Card title="API reference" href="/api-reference/transcription-jobs/create-an-async-transcription-job">Exact request and response schemas.</Card>
  <Card title="Format Hear transcripts" href="/guides/hear-transcript-formatting">Punctuation, dictation, fillers, and timestamp realignment.</Card>
  <Card title="Security and data" href="/security-and-data">Retention windows, tenancy, and regions.</Card>
  <Card title="Errors and limits" href="/errors-and-limits">Stable request errors and retry guidance.</Card>
</CardGroup>