API reference
Base URL: https://api.speechrevolutions.com
Auth: X-API-Key: <key>
Every public endpoint is also described in an OpenAPI 3.1 document. Use it with a client generator, an HTTP client, or a coding agent.
Limits
| Limit | Value | Applies to |
|---|---|---|
| Maximum file size | 10 GB | Through an SDK, which uploads in parts |
| Maximum file size | 200 MB | Direct REST upload (/api/v1/transcribe) |
| Audio retention | 30 minutes | Uploaded audio is deleted within 30 minutes of job completion |
A file larger than the limit for its path is rejected at job creation, before any upload starts. Send anything above 200 MB through an SDK rather than the REST endpoint.
Rate limits
Limits apply per API key, per endpoint, over a rolling minute. Going over returns 429. The official SDKs back off and retry automatically. If you call the API directly, retry with exponential backoff.
| Endpoint | Requests / minute |
|---|---|
POST /api/v1/transcribe | 120 |
GET /api/v1/jobs, /api/v1/jobs/{id} | 120 |
GET /api/v1/jobs/{id}/stream | 120 |
POST /api/v1/jobs/check-failed | 60 |
POST /api/v1/jobs/cancel | 30 |
Each upload creates one job, so the upload limit is also your job submission rate: 120 new jobs a minute, 7,200 an hour. To raise it for your key, contact us.
Audio formats
Audio is decoded with FFmpeg, so you do not declare the container or codec. Supported formats include mp3, wav, m4a/mp4, aac, ogg, opus, flac, webm, wma, and aiff. Video files work too: the audio track is extracted and the video discarded. Sample rate, channel count, and bit depth are normalized for you, so do not convert files before uploading. Re-encoding usually loses quality and does not make processing faster.
A file that cannot be decoded, or that contains no audio track, is not rejected at upload. The job fails at the preprocess stage, with the reason on the job record.
Errors
Every error is JSON with a detail field. For a validation error (a missing header or a field of the wrong type), detail is a list, and each entry names the invalid field in loc.
| Status | Meaning | What to do |
|---|---|---|
400 | The request is valid but cannot be processed. The most common cause is completing an upload whose bytes never arrived. | Fix the call. Retrying as-is fails the same way. |
401 | Missing, malformed or revoked API key. | Check the X-API-Key header. A request with no User-Agent header is also rejected. |
402 | The account is out of credit. | Top up, or turn on auto-recharge. Reads, listing, and cancellation keep working; only new jobs are refused. |
404 | No such job for this account. | Check the job ID. Jobs are scoped to the key that created them. |
413 | The file is over the limit for that route. | Use the SDK upload path for anything above 200 MB. |
422 | A field is missing or the wrong type. | Read detail[].loc — it names the field. |
429 | Over the rate limit for that endpoint. | Back off and retry. The SDKs do this for you. |
503 | The service is temporarily at capacity. | Retry after the interval in the Retry-After header. This error is transient and safe to retry. |
A job that fails after it was accepted does not return an HTTP error. The request succeeded, and the job record carries the failure. Poll the job or read the stream, then check failed_stage and reason. failed_stage says where the job stopped — preprocess for a file that could not be decoded, a gpu_ stage for transcription, diarization or timestamping, aggregation for assembling the transcript, and user for a job cancelled from your side.
POST /api/v1/transcribe creates a job as soon as the server has the audio, and the API has no idempotency key. If the connection drops after the accepted event, you already have the job ID: follow that job instead of resending. If it drops before, you cannot tell whether the job exists, and resending creates a second job for the same audio, transcribed and billed twice. Resend only when the request never reached the server: a connect timeout, or a 429. Everything else is safe to retry. The official SDKs follow this rule.
Endpoints
Every endpoint has its own page with parameters, request samples and response examples, generated from the OpenAPI 3.1 document.
Jobs
GET | /api/v1/jobs | List recent jobs, newest first |
GET | /api/v1/jobs/{job_id} | Retrieve one job |
GET | /api/v1/jobs/{job_id}/stream | Server-sent progress events for a job |
POST | /api/v1/jobs/cancel | Cancel a job |
POST | /api/v1/jobs/check-failed | Check many jobs for failure in one call |
Transcribe
POST | /api/v1/transcribe | Stream audio in, get the transcript back |
SDK path: the SDK uploads the file in parts, then follows the job until the transcript is ready.
Terminal path: one raw-body stream to /transcribe with SSE progress on the same connection.
By URL: pass audio_url to /upload and the API fetches the audio for you. Nothing is uploaded from your client.