Speech RevolutionsDocs

API reference · Upload

Create a job and get a presigned upload URL

POST /api/v1/upload

Creates the job and returns a URL to PUT the audio to. The job is not queued until /api/v1/upload/complete is called. Rate limit: 120 requests per minute.

This request is NOT safe to retry blindly: the job is created the moment the server handles it, so a retry after an ambiguous failure creates a second job for the same audio. The official SDKs retry it only on a connect timeout or a 429.

Authenticate with your key in the X-API-Key header — Authentication.

Request body

Required. application/json

  • model string default: zephyr

    The transcription model. One today.

  • output_type string default: json

    Format of the stored transcript at download_url.

    One of json, txt, srt, vtt, docx, pdf

  • word_timestamps boolean default: true

    Per-word start and end times.

  • speaker_labels boolean default: true

    Diarize, labelling turns SPEAKER_1, SPEAKER_2 and so on, dense and numbered from one in order of first appearance.

  • nltk boolean default: true

    Punctuation and sentence segmentation.

  • custom_vocabulary string[] | null

    Domain terms to bias towards — names, jargon, product names.

  • callback_url string (uri) | null

    Webhook to POST on completion or permanent failure. The body is signed with HMAC-SHA256 in X-SR-Signature, and carries X-SR-Event and X-SR-Delivery.

  • file_size integer | null

    Size in bytes of the file you are about to upload. Used to plan the upload; the real size is checked at complete.

  • audio_url string (uri) | null

    Fetch the audio from here instead of uploading it. When set, no upload_url is returned and the job is queued immediately.

Responses

  • 200 Job created.
  • 400 The request was understood but cannot be acted on — for example, completing an upload whose bytes never arrived.
  • 401 Missing, malformed or revoked API key.
  • 402 The account is out of credit. Top up, or turn on auto-recharge, and retry. Reads and cancellations keep working.
  • 413 The file exceeds the limit for this route: 10 GB through the upload routes, 200 MB streaming to /api/v1/transcribe.
  • 422 A field is missing or the wrong type. The body names the offending field.
  • 429 Too many requests for this endpoint. Back off and retry; the official SDKs do this for you.

200 response fields

  • job_id string (uuid) required
  • upload_url string (uri) | null

    PUT the audio here. Null when audio_url was given.

  • download_url string (uri) required

    Where the finished transcript will be readable.

  • content_type string required

    The Content-Type to send with the PUT. The signature covers it, so it must match exactly.

  • expires_in integer required

    Seconds until the presigned URLs expire.

Related endpoints