REST API

Transcription is a long-running operation. Submit a request and poll for the result.

Authentication

Supply your API key in the X-Api-Key header.

curl -X POST https://api.example.com/v2/transcript \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"audio_url": "https://example.com/audio.mp3"}'

Submitting a Transcript

Audio can be provided as a URL or as a file upload. The two options are mutually exclusive.

Option 1: Audio URL

POST /v2/transcript
Content-Type: application/json

curl -X POST https://api.example.com/v2/transcript \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "language_code": "en",
    "filler_words": true,
    "format_text": true,
    "boosted_words": ["artificial intelligence", "machine learning"]
  }'

Option 2: File Upload

POST /v2/transcript
Content-Type: multipart/form-data

curl -X POST https://api.example.com/v2/transcript \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "[email protected]"

Optional parameters can be included as additional form fields:

curl -X POST https://api.example.com/v2/transcript \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "language_code=en" \
  -F "filler_words=true" \
  -F "boosted_words[]=artificial intelligence" \
  -F "boosted_words[]=machine learning" \
  -F "boosted_words[]=neural network"

Array fields in multipart requests

For array parameters like boosted_words, use [] suffix notation to send multiple values: -F "boosted_words[]=term1" -F "boosted_words[]=term2".

Request Parameters

Parameter	Type	Default	Description
audio_url	String	—	URL of the audio file to transcribe. Required unless audio is provided.
audio	File	—	Audio file upload (max 100MB). Supported: mp3, wav, ogg, flac, m4a, mp4, webm. Required unless audio_url is provided.
language_code	String	en_us	Language code. See supported languages below.
language_auto	Boolean	false	Enable automatic language detection.
filler_words	Boolean	false	Include filler words (um, uh) in the transcript.
format_text	Boolean	true	Apply text formatting (capitalization, punctuation).
boosted_words	Array	—	List of terms to boost recognition accuracy for. Max 100 items.

* Provide either audio_url or audio, not both.

Supported Languages

Code	Language
en	English
en_us	English (US) — default
en_uk	English (UK)
en_au	English (AU)
es	Spanish
fr	French
de	German
id	Indonesian
it	Italian
ja	Japanese
nl	Dutch
pl	Polish
pt	Portuguese
ru	Russian
tr	Turkish
uk	Ukrainian
ca	Catalan

Response

{
    "id": "/v2/transcript/abc123-def456",
    "status": "queued"
}

Checking Status

Request

GET /v2/transcript/{id}

Response (Processing)

{
    "id": "/v2/transcript/abc123-def456",
    "status": "processing"
}

Response (Completed)

{
    "id": "/v2/transcript/abc123-def456",
    "status": "completed",
    "text": "Hello, this is a sample transcription of the audio file.",
    "audio_duration": 45
}

Response (Error)

{
    "id": "/v2/transcript/abc123-def456",
    "status": "error",
    "error": "Download failed. The file is not accessible."
}

Response Fields

Field	Type	Description
id	String	Transcript identifier (path format).
status	String	Current status: queued, processing, completed, or error.
text	String	The transcribed text. Present when status is completed.
audio_duration	Integer	Audio duration in seconds. Present when status is completed.
error	String	Error description. Present when status is error.

Error Responses

Validation Error (422)

{
    "message": "The given data was invalid.",
    "errors": {
        "audio_url": ["Either audio_url or an audio file is required."]
    }
}

Rate Limited (429)

{
    "error": "Rate limit exceeded. Try again in 45 seconds."
}