For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages can be requested by appending `.md` to the URL, or by setting the `Accept` header to `text/markdown`.
Skip to main content
Transcription API

Create a new job

POST https://eu1.asr.api.speechmatics.com/v2/jobs

Authentication

  • bearerAuth Authorization: Bearer <token>

    Your API key, or a temporary key (JWT).

Query parameters

wait
integer≥ 0
optional

If set, the request blocks for up to this many seconds, waiting for the job to reach a terminal state before responding. The value is capped by a server-side configured limit. The response is always 201 because the job record was created. Passing wait opts in to the extended response: the status field is included and reports whether the job reached a terminal state within the wait. If the wait elapses before the job finishes, the job is returned in its current (non-terminal) state with status set to created. If the job completes within the wait, status is done and the result is returned under the key named after the selected format (json-v2, txt, or srt); if it is rejected, status is rejected. If wait is omitted, the legacy response is returned: just the job id, with no status field.

format
"json-v2" | "txt" | "srt"
optional

The transcript format returned in the transcript field of the response when the job completes within wait (by default the json-v2 format is returned). Only relevant when wait is set.

Header parameters

X-SM-Processing-Data
string
optional

Note: Only available for on-prem JSON dictionary of processing settings for the job worker. Currently supports parallel_engines (integer), which controls the number of engines the worker can use in parallel for this job, and user_id (string), which is the user id for this job. Example: {"parallel_engines": 4}

Request body

required
multipart/form-data
config
JobConfig

The job's configuration, sent as a JSON string.

data_file
string<binary>
optional

The data file to be processed. Alternatively the data file can be fetched from a url specified in JobConfig.

Responses

OK

application/json application/vnd.speechmatics.v2+json
id
string

The unique ID assigned to the job. Keep a record of this for later retrieval of your completed job.

status
enumone of
optional

Note: Only available on SaaS on Cloud. Present only when the wait query parameter is set. Reports the outcome of the wait, which is distinct from the job lifecycle status returned by GET /jobs/{jobid}.

json-v2
object
optional

The transcript as a JSON object (the Speechmatics JSON v2 transcript — see RetrieveTranscriptResponse), returned verbatim from the stored transcript. Best-effort: present when status is done and format was json-v2 (the default) and the result is readable; if absent, fetch it from GET /jobs/{id}/transcript.

txt
string
optional

The transcript as plain text. Best-effort: present when status is done and format was txt and the result is readable; if absent, fetch it from GET /jobs/{id}/transcript.

srt
string
optional

The transcript as SubRip (SRT) subtitles. Best-effort: present when status is done and format was srt and the result is readable; if absent, fetch it from GET /jobs/{id}/transcript.

import { openAsBlob } from "node:fs";
import { BatchClient } from "@speechmatics/batch-client";

const client = new BatchClient({ apiKey: "YOUR_API_KEY", appId: "my-app" });

// In a browser, pass a File from a file input instead.
const file = new File([await openAsBlob("example.wav")], "example.wav");

const { id } = await client.createTranscriptionJob(file, {
  transcription_config: { language: "en", model: "enhanced" },
});
console.log(id);

Examples