> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use Batch API

> Submit audio for asynchronous transcription on the SLNG Batch API using direct file upload, URL input, or presigned S3 upload. Supported formats and limits.

This guide covers the three ways to submit audio for batch transcription. For endpoint details and schemas, see the [Batch API reference](/api-reference/speechmatics/create-batch-job).

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

**Prerequisites:**

* An [SLNG key](/getting-started)
* 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](https://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`.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Batch API
    Client->>Batch API: POST /v1/batch/jobs<br/>multipart: file + config
    Note over Batch API: Queues transcription job
    Batch API-->>Client: 202 – job_id, status: QUEUED
```

```bash theme={null}
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.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Batch API
    Client->>Batch API: POST /v1/batch/jobs<br/>JSON: input_url + config
    Note over Batch API: Downloads audio from URL
    Note over Batch API: Queues transcription job
    Batch API-->>Client: 202 – job_id, status: QUEUED
```

```bash theme={null}
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.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Batch API
    participant S3
    Client->>Batch API: POST /v1/batch/jobs<br/>JSON: mode=presign + filename
    Batch API-->>Client: 200 – job_id + presigned upload URL
    Client->>S3: PUT presigned URL<br/>binary audio file
    S3-->>Client: 200 OK
    Client->>Batch API: POST /v1/batch/jobs<br/>JSON: job_id + s3_key + config
    Note over Batch API: Queues transcription job
    Batch API-->>Client: 202 – job_id, status: QUEUED
```

<Steps>
  <Step title="Request a presigned S3 upload URL">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Upload the file to the presigned URL">
    Send the bytes with the exact headers from `upload.headers` (typically `Content-Type: application/octet-stream`):

    ```bash theme={null}
    curl -X PUT "<presigned_url>" \
      -H "Content-Type: application/octet-stream" \
      --data-binary @audio.wav
    ```
  </Step>

  <Step title="Create the job">
    Reference the `job_id` and `s3_key` from step 1.

    ```bash theme={null}
    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" }
      }'
    ```
  </Step>
</Steps>

***

## 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](/api-reference/speechmatics/get-batch-job) for the schema.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Batch API
    Client->>Batch API: GET /v1/batch/jobs/{jobId}
    Batch API-->>Client: status: IN_PROGRESS
    Note over Client: Wait and retry
    Client->>Batch API: GET /v1/batch/jobs/{jobId}
    Batch API-->>Client: status: DONE
    Client->>Batch API: GET /v1/batch/jobs/{jobId}/files
    Batch API-->>Client: Signed download URLs<br/>(JSON, TXT, SRT transcripts)
```

```bash theme={null}
curl https://api.batch.slng.ai/v1/batch/jobs/myjob123 \
  -H "Authorization: Bearer SLNG_API_KEY"
```

Once `DONE`, retrieve the transcript:

```bash theme={null}
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](/api-reference/speechmatics/list-batch-jobs) 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:

```json theme={null}
{
  "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                                    |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Batch API reference" icon="code" href="/api-reference/speechmatics/create-batch-job">
    Endpoint details, request schemas, and response formats
  </Card>

  <Card title="Getting started" icon="rocket" href="/getting-started">
    Set up your SLNG key and make your first request
  </Card>
</CardGroup>