How to use Batch API

This guide covers the three ways to submit audio for batch transcription. For endpoint details and schemas, see the Batch API reference.

The Batch API is served from https://api.batch.slng.ai, not https://api.slng.ai, and uses the same bearer SLNG key.

Prerequisites:

An SLNG key
Audio in a supported format: wav, mp3, flac, aac, ogg, m4a, mp4, amr, mpeg

Placeholders

The snippets below use these placeholders. Replace them before running the code.

Placeholder	Replace with
`SLNG_API_KEY`	An SLNG key from app.slng.ai/api-keys
`myjob123` / `job8f3a...`	The `job_id` returned by `POST /v1/batch/jobs` (auto-generated if omitted)
`<presigned_url>`	The presigned upload URL returned by the `mode: "presign"` flow
`audio.wav` / `s3_key`	Your local file path / the S3 key the platform returned at presign time

Input Methods

Method 1: File Upload

Upload the audio file directly using multipart/form-data.

curl -X POST https://api.batch.slng.ai/v1/batch/jobs \
  -H "Authorization: Bearer SLNG_API_KEY" \
  -F file=@audio.wav \
  -F transcription_config='{"language":"en"}'

Method 2: URL Input

Provide a publicly accessible HTTPS URL. The system downloads the file (max 1 GB). Supports presigned S3/GCS URLs for private files.

curl -X POST https://api.batch.slng.ai/v1/batch/jobs \
  -H "Authorization: Bearer SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_url": "https://example.com/audio.wav",
    "transcription_config": { "language": "en" }
  }'

Field	Type	Required	Description
`input_url`	string	yes	HTTPS URL of the audio file
`transcription_config`	object	yes	Transcription settings
`job_id`	string	no	Alphanumeric job ID (auto-generated if omitted)
`model_code`	string	no	Model to use (default: `slng/speechmatics/batch:15.0.0`)
`metadata`	object	no	Arbitrary key-value metadata

Method 3: Presigned Upload

Use this method for large files or when you need upload progress tracking. Three steps: request a presigned URL, upload the file directly to S3, then create the job referencing the upload.

Request a presigned S3 upload URL

curl -X POST https://api.batch.slng.ai/v1/batch/jobs \
  -H "Authorization: Bearer SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "presign",
    "filename": "audio.wav",
    "transcription_config": { "language": "en" }
  }'

Returns 200 OK (no job is created yet). The response carries the job_id, the validated transcription_config (and any other config you sent, echoed back), the future S3 locations, and an upload object with the presigned PUT URL plus the headers your upload must send:

{
  "job_id": "job8f3a...",
  "transcription_config": { "language": "en", "operating_point": "standard", "diarization": "none" },
  "input_s3_uri": "s3://slng-production-batch-input/inputs/job8f3a.../audio.wav",
  "output_s3_prefix": "s3://slng-production-batch-output/outputs/job8f3a.../",
  "upload": {
    "url": "https://slng-production-batch-input.s3.amazonaws.com/...",
    "s3_key": "inputs/job8f3a.../audio.wav",
    "s3_uri": "s3://slng-production-batch-input/inputs/job8f3a.../audio.wav",
    "expires_in": 1800,
    "headers": { "Content-Type": "application/octet-stream" }
  }
}

Carry the returned transcription_config (and any echoed tracking / output_config) verbatim into step 3.

Upload the file to the presigned URL

Send the bytes with the exact headers from upload.headers (typically Content-Type: application/octet-stream):

curl -X PUT "<presigned_url>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @audio.wav

Create the job

Reference the job_id and s3_key from step 1.

curl -X POST https://api.batch.slng.ai/v1/batch/jobs \
  -H "Authorization: Bearer SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job8f3a...",
    "s3_key": "inputs/job8f3a.../audio.wav",
    "transcription_config": { "language": "en" }
  }'

Job Lifecycle

After submission, a job moves through these statuses: QUEUED → IN_PROGRESS → DECODING → POST_PROCESSING → DONE / FAILED A successfully deleted job moves to DELETED (terminal). Poll GET /v1/batch/jobs/{jobId} until the status reaches DONE or FAILED. The response includes the full job record (config, timestamps, error_message on failures); see the API reference for the schema.

curl https://api.batch.slng.ai/v1/batch/jobs/myjob123 \
  -H "Authorization: Bearer SLNG_API_KEY"

Once DONE, retrieve the transcript:

curl https://api.batch.slng.ai/v1/batch/jobs/myjob123/files \
  -H "Authorization: Bearer SLNG_API_KEY"

This returns signed download URLs for the input audio and the output transcripts. Each output entry carries a format field: json, txt, or srt. Signed URLs expire after roughly one hour. To list jobs instead of polling a single one, use GET /v1/batch/jobs. It supports pagination (page, page_size) plus filtering by status, model_code, and submission date range, and sorting by submitted_at, status, or model_code. See the API reference for the full parameter list.

Transcription Config

Field	Type	Default	Description
`language`	string	`en`	Language code for the audio
`operating_point`	string	`standard`	Accuracy level: `standard` or `enhanced`
`diarization`	string	`none`	Speaker separation: `none`, `speaker`, or `channel`
`domain`	string	—	Domain-specific language model
`output_locale`	string	—	Locale for formatting (dates, numbers)
`enable_entities`	boolean	—	Detect and format entities (dates, times, addresses)
`additional_vocab`	array	—	Custom words to improve recognition

Example with diarization and enhanced accuracy:

{
  "transcription_config": {
    "language": "en",
    "operating_point": "enhanced",
    "diarization": "speaker"
  }
}

Limits

Limit	Value
Max file size	1 GB
Presigned upload URL expiry	30 minutes
Supported audio formats	wav, mp3, flac, aac, ogg, m4a, mp4, amr, mpeg
URL input scheme	HTTPS only

Get started

Text-to-Speech

Speech-to-Text

Voice Agents

Integrations

SDKs & Tools

Reference

Placeholders

Input Methods

Method 1: File Upload

Method 2: URL Input

Method 3: Presigned Upload

Job Lifecycle

Transcription Config

Limits

Next Steps

Batch API reference

Getting started

​Placeholders

​Input Methods

​Method 1: File Upload

​Method 2: URL Input

​Method 3: Presigned Upload

​Job Lifecycle

​Transcription Config

​Limits

​Next Steps

Batch API reference

Getting started

Placeholders

Input Methods

Method 1: File Upload

Method 2: URL Input

Method 3: Presigned Upload

Job Lifecycle

Transcription Config

Limits

Next Steps