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
Speech to TextBatch transcription

Input

Learn about configuration and supported input audio formats for the Speechmatics Batch API

Supported file types​

The following file formats types are supported for transcription by REST API:

  • wav
  • mp3
  • aac
  • ogg
  • mpeg
  • amr
  • m4a
  • mp4
  • flac

The list above is exhaustive - any file format outside the list above is explicitly not supported.

Only files where the type can be determined by data inspection are supported. Raw audio formats where the codec is not embedded in the file cannot be processed in batch mode. This includes files commonly given extensions like ".raw" or ".g729" where the codec is only hinted at in the name.

The optimal format for speed is 16bit 16kHz mono WAV. This format will not need preprocessing before transcription, which can make a difference to turnaround time for very short input files.

Job configuration options​

Jobs are configured by passing a JSON string to the config field of the CreateJobRequest (see API reference)

JobConfig schema​

Below are the complete fields of the configuration object:

JobConfigIn the API reference: Create a new job
type
JobType"transcription"
fetch_data
DataFetchConfig
optional
fetch_text
DataFetchConfig
optional
transcription_config
TranscriptionConfig
optional
notification_config
NotificationConfig[]
optional
tracking
TrackingData
optional
output_config
OutputConfig
optional
translation_config
TranslationConfig
optional
language_identification_config
LanguageIdentificationConfig
optional
summarization_config
SummarizationConfig
optional

Configuration options for summarization.

sentiment_analysis_config
SentimentAnalysisConfig
optional
topic_detection_config
TopicDetectionConfig
optional
auto_chapters_config
AutoChaptersConfig
optional
audio_events_config
AudioEventsConfig
optional

Language hints​

The Melia 1 model detects every language it hears automatically, so language hints are optional. To select Melia 1, refer to Models.

Hints tell the model which languages to expect in the audio, biasing detection toward them. They are most useful for short clips, audio with heavy accents, or recordings where two languages sound similar, where they make language labeling more reliable.

Provide hints as a list of supported languages to guide detection without restricting it. This config hints that the audio contains English and Arabic:

{
  "type": "transcription",
  "transcription_config": {
    "model": "melia-1",
    "language": "multi",
    "language_hints": ["en", "ar"]
  }
}

The model can still detect and label a language you did not hint, and it labels only the languages it actually hears.

Fetch URL​

If you store your digital media in cloud storage (for example AWS S3 or Azure Blob Storage) you can also submit a job by providing the URL of the audio file. The configuration uses a fetch_data section, which looks like this:

Configuration example​

{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  "fetch_data": {
    "url": "${URL}/{FILENAME}"
  }
}

In SaaS, fetch requests made to the URL in fetch_data have user agent set to Speechmatics-API/2.0.

Fetch failure​

If the Speechmatics Batch SaaS is unable to retrieve audio from the specified online location, the job will fail, with a status of rejected, and no transcript will be generated. Users can now retrieve failure information by making a GET /jobs/$JOBID request, and use that to carry out diagnostic information.

If the job has failed, there will be an additional errors element, which will show all failure messages Speechmatics Batch SaaS encountered when carrying out the fetch request. Please note, there can be multiple failure attempts associated with one submitted job, as there is a retry mechanism in place.

{
  "job": {
    "config": {
      "fetch_data": {
        "url": "https://example.com/average-files/punctuation1.mp3"
      },
      "notification_config": [
        {
          "contents": ["jobinfo"],
          "url": "https://example.com/"
        }
      ],
      "transcription_config": {
        "language": "de"
      },
      "type": "transcription"
    },
    "created_at": "2021-07-19T12:55:03.754Z",
    "data_name": "",
    "duration": 0,
    "errors": [
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:05.425Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:07.649Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:17.665Z"
      },
      {
        "message": "unable to fetch audio: http status code 404",
        "timestamp": "2021-07-19T12:55:37.643Z"
      }
    ],
    "id": "a81ko4eqjl",
    "status": "rejected"
  }
}