Skip to main content
POST

Supported Formats and Limitations

  • Supported formats: MP3, WAV, M4A, FLAC, AAC, OGG, WEBM
  • Maximum file size: 100MB
  • Maximum audio duration: 4 hours

Request Parameters

Body

string
The video/audio url. Not required if file_store_key is specified.
string
The key used to store the video/audio file on Jigsawstack File Storage. Not required if url is specified.
Either url or file_store_key should be provided, not both.
string
The language to transcribe or translate the file into. Use “auto” for automatic language detection, or specify a language code. If not specified, defaults to automatic detection. All supported language codes can be found here.
boolean
default:"false"
When set to true, translates the content into English (or the specified language if language parameter is provided). All supported language codes can be found here.
boolean
default:"false"
Identifies and separates different speakers in the audio file. When enabled, the response will include a speakers array with speaker-segmented transcripts.
string
Webhook URL to send result to. When provided, the API will process asynchronously and send results to this URL when completed.
number
default:"30"
The batch size to return. Maximum value is 40. This controls how the audio is chunked for processing.
number
default:"3"
The duration of each chunk in seconds. Maximum value is 15. This controls the duration of each chunk of audio that is processed.
boolean
default:"false"
When set to true, returns each word as its own entry in the chunks array with its own start and end timestamp. Useful for caption alignment and word-accurate search. Cannot be combined with stream=true.
boolean
default:"false"
Returns results as the audio is transcribed, instead of waiting for the full result. Good for live microphone input. Only supports language=en.
boolean
default:"true"
Skip chunks that contain no speech. Only applies when stream=true.
number
default:"0.5"
Sensitivity of speech detection, between 0 and 1. Lower values detect more speech; higher values are stricter. Only applies when stream=true and vad=true.
string
required
Your JigsawStack API key

Response Structure

boolean
Indicates whether the call was successful.
object
Usage information for the API call.
string
A unique identifier for the request
string
The complete transcribed text from the audio/video file.
array
An array of transcript chunks with timestamps.
array
Only present when by_speaker is set to true. Contains speaker-segmented transcripts.
string
The language detected in the audio/video file. Available if language parameter is not provided or set to “auto”.
number
The confidence score for the language detected. Available if language parameter is not provided or set to “auto”.

Webhook Response

When using webhook_url, the initial response will be different.
enum
Status of the transcription job.
  • processing - The transcription job is queued successfully
  • error - There was an issue with the transcription job
string
A unique identifier for the transcription job.
The complete transcription result will later be sent to your webhook URL with the same structure as the direct response.

Advanced Features

Speaker Diarization

Speaker diarization is the process of separating an audio stream into segments according to the identity of each speaker. When you enable the by_speaker parameter, the API will:
  1. Transcribe the audio as usual
  2. Identify distinct speakers in the recording
  3. Label each segment with a speaker identifier (e.g., “SPEAKER_1”, “SPEAKER_2”)
  4. Return both the standard chunks and a separate speakers array with speaker-separated transcriptions
This is particularly useful for:
  • Meeting transcriptions
  • Interview transcriptions
  • Podcast transcriptions
  • Any multi-speaker audio content

Word-level timestamps

When you enable the word_timestamps parameter, each entry in the chunks array is a single word with its own start and end timestamp, instead of a multi-word segment. The API will:
  1. Transcribe the audio as usual
  2. Align each word against the audio waveform
  3. Return one entry per word in the chunks array, in order
This is particularly useful for:
  • Caption and subtitle alignment
  • Word-accurate jump-to-timestamp search
  • Video editors that cut on word boundaries
  • Karaoke-style highlighting
word_timestamps cannot be combined with stream=true.

Webhook Usage

For long audio files, processing might take some time. Instead of keeping the connection open and waiting for the result, you can provide a webhook_url parameter. The API will:
  1. Return immediately with a job ID
  2. Process the audio asynchronously
  3. Send the complete transcription results to your webhook URL when finished
Make sure your webhook endpoint is set up to:
  • Accept POST requests
  • Parse JSON content
  • Handle the same response format as the standard API response

Streaming

Set stream=true to receive results as the audio is transcribed, instead of waiting for the full result. Good for live microphone input. Requirements
  • Pass language=en (streaming currently supports English only).
  • Send audio in the request body (raw bytes with the matching Content-Type, or as a file field in multipart/form-data).
  • by_speaker and webhook_url are not available with streaming.
Example request
Events The response is a stream of events. Each event has a type: