> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.sofer.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sofer.ai/_mcp/server. # Create Batch Transcription POST https://api.sofer.ai/v1/transcriptions/batch Content-Type: application/json Create multiple transcriptions in a single batch request. **Choose a processing mode:** - **Express mode**: Submit up to 10 files at once with `audio_sources`. Express batches may take longer than individual transcription requests, but make it easier to submit multiple files together. Pricing for v1 is $1.50/hour. - **Standard mode**: Transcriptions processed within 24 hours. Max 500 files. Lower cost. First upload a manifest via [Upload Batch Manifest File](/api-reference/batch-transcribe/upload-batch-file), then pass the `batch_file_id` here. Pricing for v1 batch standard is $1.00/hour. If you need higher limits, contact support@sofer.ai. All files in the batch share the same transcription settings (model, language, etc.) defined in `info`. Speaker settings can be provided at the batch level or per item. Per-item `num_speakers` or `auto_detect_speakers` settings take precedence over the batch-level speaker settings in `info`. If an item omits both speaker fields, it inherits the batch-level setting. If neither level provides a speaker setting, the transcription defaults to one speaker. Do not provide both `num_speakers` and `auto_detect_speakers` in the same object. If you include a `client_item_id` on each item, it must be unique within the batch. You can later resolve a `client_item_id` back to the canonical transcription ID with [Get Batch Transcription By Client Item ID](/api-reference/batch-transcribe/get-batch-transcription-by-client-item-id). Reference: https://docs.sofer.ai/api-reference/batch-transcribe/create-batch-transcription ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a BatchTranscriptionRequest. - `info` (BatchTranscriptionRequestInfo, required) — Transcription settings applied to all files in the batch (model, language, etc.). Batch-level speaker settings are defaults. Per-item `num_speakers` or `auto_detect_speakers` settings in `audio_sources` or a batch manifest take precedence for that item. - `processing_mode` (enum, optional) — Choose how the batch is processed: - `standard` (default): Lower cost, processed within 24 hours. Max 500 files. Use with `batch_file_id`. Pricing for v1 batch standard is $1.00/hour. If you need higher limits, contact support@sofer.ai. - `express`: Submit up to 10 files at once with `audio_sources`. Express batches may take longer than individual transcription requests, but make it easier to submit multiple files together. Pricing for v1 is $1.50/hour. - Allowed values: `standard`, `express` - `batch_file_id` (UUID, optional) — **For standard mode only.** ID of a previously uploaded batch manifest. Get this by calling [Upload Batch Manifest File](/api-reference/batch-transcribe/upload-batch-file) first. - `audio_sources` (list of BatchAudioSource, optional) — **For express mode only.** List of audio URLs to transcribe (max 10). Each item needs an `audio_url` and can optionally include a `title`, `client_item_id`, `num_speakers`, or `auto_detect_speakers`. Per-item `num_speakers` or `auto_detect_speakers` settings take precedence over the batch-level speaker settings in `info`. If you provide `client_item_id`, it must be unique within the batch and can be used later to look up the resulting transcription. - `batch_title` (string, optional) — Default title prefix for transcriptions. Individual items can override this. Items without titles become "\{batch\_title} - Item 1", "\{batch\_title} - Item 2", etc. ## Response ### 200 Returns the batch ID and individual transcription IDs. Use [Get Batch Status](/api-reference/batch-transcribe/get-batch-status) to track progress. - `batch_id` (UUID, required) — Use this ID to check batch progress via [Get Batch Status](/api-reference/batch-transcribe/get-batch-status) - `transcription_ids` (list of UUID, required) — IDs for each transcription in the batch. Use these to retrieve individual results via [Get Transcription](/api-reference/transcribe/get-transcription) - `total_count` (integer, required) — Number of transcriptions created - `status` (enum, required) — Initial batch status (typically `RECEIVED`) - Allowed values: `RECEIVED`, `PROCESSING`, `COMPLETED`, `FAILED` ## Errors ### 401 Authentication Error Authentication error ### 429 Rate Limit Error Rate limit exceeded, or you have used up your quota ## Types ### BatchTranscriptionRequestInfo - `transliteration_style` (enum, optional) — Pronunciation used for Hebrew and Aramaic transliteration across this batch. Omit to use the saved account preference, or Sephardi when no preference is saved. Applies when the primary language is English and Hebrew words are transliterated. - Allowed values: `sefardi`, `ashkenazi` - `model` (string, optional) — Model to be used for the transcription. Default is "v1". - v1: Our latest and most accurate model, especially for audio with longer stretches of Hebrew. Priced at 1.50 USD per hour of audio transcribed. - v0: Not generally recommended. Cheaper, but less accurate. Priced at 1.00 USD per hour. - `title` (string, optional) — Title for the transcription, Default is "Untitled" - `folder_id` (UUID, optional) — Optional owned document folder applied to every transcript created by this batch. - `primary_language` (enum, optional) — Specifies the primary language spoken in the audio content. Default is English. - en: English - he: Hebrew - yi: Yiddish - fr: French - Allowed values: `en`, `he`, `yi`, `fr` - `hebrew_word_format` (list of enum, optional) — Relevant only when `primary_language` is `en`. This setting controls how Hebrew, Yiddish, and Aramaic speech is rendered across the batch. * Omit it or specify `["hybrid"]` (the default) to transliterate phrases of three words or fewer in italicized English letters and write longer phrases in Hebrew letters. * Specify `["he"]` to write all such speech in Hebrew letters. * Specify `["en"]` to transliterate all such speech into italicized English letters. * Specify `["en", "he"]` to provide every Hebrew word in both formats, with the transliteration in `` tags. * When the primary language is not English, omit this field or specify `["he"]`; `["he"]` is the only supported format. - Allowed values: `en`, `he`, `hybrid` - `num_speakers` (integer, optional) — Expected number of speakers in the audio. Default is 1. This field is mutually exclusive with `auto_detect_speakers`. If a number more than 1 is passed, it will be used for speaker labeling and adds **$0.30/hour**. - `auto_detect_speakers` (boolean, optional) — Automatically detect the number of speakers in the audio. This field is mutually exclusive with `num_speakers`. If both are provided, the API returns a 400 error. Auto-detection adds **$0.30/hour**. ### BatchAudioSource A single audio file in a batch request. Per-item speaker settings take precedence over the batch-level speaker settings in `info`. - `audio_url` (string, required) — Direct download URL to the audio file (MP3, WAV, etc.) - `title` (string, optional) — Title for this transcription. Falls back to batch_title or auto-generated "Item 1", "Item 2", etc. - `client_item_id` (string, optional) — Caller-defined identifier for this batch item. Must be unique within the batch. Use this to map the item back to the resulting transcription later. - `num_speakers` (integer, optional) — Expected number of speakers for this specific file. Mutually exclusive with `auto_detect_speakers`. If provided, this overrides the batch-level speaker setting for this item. Values greater than 1 add **$0.30/hour**. - `auto_detect_speakers` (boolean, optional) — Automatically detect the number of speakers for this specific file. Mutually exclusive with `num_speakers`. If provided, this overrides the batch-level speaker setting for this item. Auto-detection adds **$0.30/hour**. ## Examples ### express_mode Submit up to 10 files at once with audio_sources. Express batches may take longer than individual transcription requests, but make it easier to submit multiple files together. Pricing for v1 is $1.50/hour. **Request** ```json { "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": [ "en", "he" ], "num_speakers": 1 }, "processing_mode": "express", "audio_sources": [ { "audio_url": "https://example.com/audio1.mp3", "title": "Rabbi Cohen's Shiur on Shabbos", "client_item_id": "shiur_shabbos" }, { "audio_url": "https://example.com/audio2.mp3", "title": "Rabbi Cohen's Shiur on Kashrus", "client_item_id": "shiur_kashrus" } ], "batch_title": "Rabbi Cohen Shiurim" } ``` **Response** ```json { "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "transcription_ids": [ "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32", "e6f0d95a-d3c3-5ca5-c5c1-8aad8b0aad43" ], "total_count": 2, "status": "RECEIVED" } ``` **SDK Code** ```python express_mode import requests url = "https://api.sofer.ai/v1/transcriptions/batch" payload = { "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": ["en", "he"], "num_speakers": 1 }, "processing_mode": "express", "audio_sources": [ { "audio_url": "https://example.com/audio1.mp3", "title": "Rabbi Cohen's Shiur on Shabbos", "client_item_id": "shiur_shabbos" }, { "audio_url": "https://example.com/audio2.mp3", "title": "Rabbi Cohen's Shiur on Kashrus", "client_item_id": "shiur_kashrus" } ], "batch_title": "Rabbi Cohen Shiurim" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript express_mode const url = 'https://api.sofer.ai/v1/transcriptions/batch'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"info":{"model":"v1","primary_language":"en","hebrew_word_format":["en","he"],"num_speakers":1},"processing_mode":"express","audio_sources":[{"audio_url":"https://example.com/audio1.mp3","title":"Rabbi Cohen\'s Shiur on Shabbos","client_item_id":"shiur_shabbos"},{"audio_url":"https://example.com/audio2.mp3","title":"Rabbi Cohen\'s Shiur on Kashrus","client_item_id":"shiur_kashrus"}],"batch_title":"Rabbi Cohen Shiurim"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go express_mode package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sofer.ai/v1/transcriptions/batch" payload := strings.NewReader("{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"express\",\n \"audio_sources\": [\n {\n \"audio_url\": \"https://example.com/audio1.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Shabbos\",\n \"client_item_id\": \"shiur_shabbos\"\n },\n {\n \"audio_url\": \"https://example.com/audio2.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Kashrus\",\n \"client_item_id\": \"shiur_kashrus\"\n }\n ],\n \"batch_title\": \"Rabbi Cohen Shiurim\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby express_mode require 'uri' require 'net/http' url = URI("https://api.sofer.ai/v1/transcriptions/batch") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"express\",\n \"audio_sources\": [\n {\n \"audio_url\": \"https://example.com/audio1.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Shabbos\",\n \"client_item_id\": \"shiur_shabbos\"\n },\n {\n \"audio_url\": \"https://example.com/audio2.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Kashrus\",\n \"client_item_id\": \"shiur_kashrus\"\n }\n ],\n \"batch_title\": \"Rabbi Cohen Shiurim\"\n}" response = http.request(request) puts response.read_body ``` ```java express_mode import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sofer.ai/v1/transcriptions/batch") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"express\",\n \"audio_sources\": [\n {\n \"audio_url\": \"https://example.com/audio1.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Shabbos\",\n \"client_item_id\": \"shiur_shabbos\"\n },\n {\n \"audio_url\": \"https://example.com/audio2.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Kashrus\",\n \"client_item_id\": \"shiur_kashrus\"\n }\n ],\n \"batch_title\": \"Rabbi Cohen Shiurim\"\n}") .asString(); ``` ```php express_mode request('POST', 'https://api.sofer.ai/v1/transcriptions/batch', [ 'body' => '{ "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": [ "en", "he" ], "num_speakers": 1 }, "processing_mode": "express", "audio_sources": [ { "audio_url": "https://example.com/audio1.mp3", "title": "Rabbi Cohen\'s Shiur on Shabbos", "client_item_id": "shiur_shabbos" }, { "audio_url": "https://example.com/audio2.mp3", "title": "Rabbi Cohen\'s Shiur on Kashrus", "client_item_id": "shiur_kashrus" } ], "batch_title": "Rabbi Cohen Shiurim" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp express_mode using RestSharp; var client = new RestClient("https://api.sofer.ai/v1/transcriptions/batch"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"express\",\n \"audio_sources\": [\n {\n \"audio_url\": \"https://example.com/audio1.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Shabbos\",\n \"client_item_id\": \"shiur_shabbos\"\n },\n {\n \"audio_url\": \"https://example.com/audio2.mp3\",\n \"title\": \"Rabbi Cohen's Shiur on Kashrus\",\n \"client_item_id\": \"shiur_kashrus\"\n }\n ],\n \"batch_title\": \"Rabbi Cohen Shiurim\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift express_mode import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "info": [ "model": "v1", "primary_language": "en", "hebrew_word_format": ["en", "he"], "num_speakers": 1 ], "processing_mode": "express", "audio_sources": [ [ "audio_url": "https://example.com/audio1.mp3", "title": "Rabbi Cohen's Shiur on Shabbos", "client_item_id": "shiur_shabbos" ], [ "audio_url": "https://example.com/audio2.mp3", "title": "Rabbi Cohen's Shiur on Kashrus", "client_item_id": "shiur_kashrus" ] ], "batch_title": "Rabbi Cohen Shiurim" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sofer.ai/v1/transcriptions/batch")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### standard_mode Standard mode processes within 24 hours at lower cost. Upload a batch file first, then reference it here. Pricing for v1 batch standard is $1.00/hour. **Request** ```json { "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": [ "en", "he" ], "num_speakers": 1 }, "processing_mode": "standard", "batch_file_id": "f1234567-89ab-cdef-0123-456789abcdef", "batch_title": "Weekly Shiurim Collection" } ``` **Response** ```json { "batch_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "transcription_ids": [ "c7d8e9f0-a1b2-3456-cdef-789012345678", "d8e9f0a1-b2c3-4567-def0-890123456789", "e9f0a1b2-c3d4-5678-ef01-901234567890" ], "total_count": 3, "status": "RECEIVED" } ``` **SDK Code** ```python standard_mode import requests url = "https://api.sofer.ai/v1/transcriptions/batch" payload = { "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": ["en", "he"], "num_speakers": 1 }, "processing_mode": "standard", "batch_file_id": "f1234567-89ab-cdef-0123-456789abcdef", "batch_title": "Weekly Shiurim Collection" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript standard_mode const url = 'https://api.sofer.ai/v1/transcriptions/batch'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"info":{"model":"v1","primary_language":"en","hebrew_word_format":["en","he"],"num_speakers":1},"processing_mode":"standard","batch_file_id":"f1234567-89ab-cdef-0123-456789abcdef","batch_title":"Weekly Shiurim Collection"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go standard_mode package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sofer.ai/v1/transcriptions/batch" payload := strings.NewReader("{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"standard\",\n \"batch_file_id\": \"f1234567-89ab-cdef-0123-456789abcdef\",\n \"batch_title\": \"Weekly Shiurim Collection\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby standard_mode require 'uri' require 'net/http' url = URI("https://api.sofer.ai/v1/transcriptions/batch") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"standard\",\n \"batch_file_id\": \"f1234567-89ab-cdef-0123-456789abcdef\",\n \"batch_title\": \"Weekly Shiurim Collection\"\n}" response = http.request(request) puts response.read_body ``` ```java standard_mode import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sofer.ai/v1/transcriptions/batch") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"standard\",\n \"batch_file_id\": \"f1234567-89ab-cdef-0123-456789abcdef\",\n \"batch_title\": \"Weekly Shiurim Collection\"\n}") .asString(); ``` ```php standard_mode request('POST', 'https://api.sofer.ai/v1/transcriptions/batch', [ 'body' => '{ "info": { "model": "v1", "primary_language": "en", "hebrew_word_format": [ "en", "he" ], "num_speakers": 1 }, "processing_mode": "standard", "batch_file_id": "f1234567-89ab-cdef-0123-456789abcdef", "batch_title": "Weekly Shiurim Collection" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp standard_mode using RestSharp; var client = new RestClient("https://api.sofer.ai/v1/transcriptions/batch"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"info\": {\n \"model\": \"v1\",\n \"primary_language\": \"en\",\n \"hebrew_word_format\": [\n \"en\",\n \"he\"\n ],\n \"num_speakers\": 1\n },\n \"processing_mode\": \"standard\",\n \"batch_file_id\": \"f1234567-89ab-cdef-0123-456789abcdef\",\n \"batch_title\": \"Weekly Shiurim Collection\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift standard_mode import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "info": [ "model": "v1", "primary_language": "en", "hebrew_word_format": ["en", "he"], "num_speakers": 1 ], "processing_mode": "standard", "batch_file_id": "f1234567-89ab-cdef-0123-456789abcdef", "batch_title": "Weekly Shiurim Collection" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sofer.ai/v1/transcriptions/batch")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```