# Transcription workflow

Build a reliable process for upload, job creation, tracking and artifact download

Canonical: https://alef-bot.top/en/developers/guides/transcription-workflow

Updated: 2026-08-14

## Upload → Transcribe → Track → Download

Treat each operation as a separate step and retain `upload_id` and `job_id` so retries and support checks remain predictable

1. **Upload.** Reserve an upload slot and transfer the file before expiry. A mismatched file size is rejected
2. **Transcribe.** Create one job per upload. If the response is uncertain, reuse the same Idempotency-Key
3. **Track.** Poll with increasing delays. Send the latest ETag in If-None-Match to receive 304 when nothing changed
4. **Download.** Download only after completion. SRT, TXT, PDF and DOCX are available; choose using `format`, a path extension or `Accept`

## Production behavior

- Live jobs usually return 202 Accepted; Test jobs may return 200 immediately
- Upload and transcription creation are limited to 15 requests per minute on Premium and 60 on Platinum
- Reads, polling and artifact requests are limited to 60 per minute on Premium and 240 on Platinum
- Webhook tests are limited to 5 per minute on Premium and 20 on Platinum
- All account keys share the limits; each operation group is counted separately
- X-RateLimit-Reset is a Unix timestamp in UTC seconds; for 429, also honor Retry-After in whole seconds
- Retain X-Request-ID on failure so AlefBot support can trace the request

## Machine-readable sources

- [OpenAPI JSON](https://alef-bot.top/api/v1/openapi.json)

- [OpenAPI YAML](https://alef-bot.top/api/v1/openapi.yaml)

- [Arazzo workflow](https://alef-bot.top/api/v1/workflows/transcribe.arazzo.yaml)