This document will walk you through how to use the RESTful API for the Speechmatics Batch SaaS. This document will show you
This section shows:
The Speechmatics Batch SaaS supports the following languages. Your ability to use any or all of the languages will depend on what languages you are contracted to use.
Speechmatics takes a global first approach to our languages. In a single language pack we aim to support many different accents and dialects. This simplifies your workflow when selecting which language to use, not requiring you to know which accent is being spoken in your audio up-front. With this approach we still achieve very high accuracy compared to accent specific language packs.
| Language | Language Code |
|---|---|
| Arabic | (ar) |
| Bashkir | (ba) |
| Basque | (eu) |
| Belarusian | (be) |
| Bulgarian | (bg) |
| Cantonese | (yue) |
| Catalan | (ca) |
| Croatian | (hr) |
| Czech | (cs) |
| Danish | (da) |
| Dutch | (nl) |
| English | (en) |
| Esperanto | (eo) |
| Estonian | (et) |
| Finnish | (fi) |
| French | (fr) |
| Galician | (gl) |
| German | (de) |
| Greek | (el) |
| Hindi | (hi) |
| Hungarian | (hu) |
| Interlingua | (ia) |
| Italian | (it) |
| Indonesian | (id) |
| Japanese | (ja) |
| Korean | (ko) |
| Latvian | (lv) |
| Lithuanian | (lt) |
| Malay | (ms) |
| Mandarin | (cmn) |
| Marathi | (mr) |
| Mongolian | (mn) |
| Norwegian | (no) |
| Polish | (pl) |
| Portuguese | (pt) |
| Romanian | (ro) |
| Russian | (ru) |
| Slovakian | (sk) |
| Slovenian | (sl) |
| Spanish | (es) |
| Swedish | (sv) |
| Tamil | (ta) |
| Thai | (th) |
| Turkish | (tr) |
| Uyghur | (ug) |
| Ukrainian | (uk) |
| Vietnamese | (vi) |
| Welsh | (cy) |
Please note any languages outside this list are not explicitly supported. Only one language can be processed within each request. Each language above has a two-letter code (ISO639-1) or three-letter code (ISO639-3) that must be provided for any transcription request.
The Speechmatics Batch SaaS also supports specialized language packs that enhance the requested transcription language with optimization for a particular field. This is particularly useful for increasing the accuracy for domains that have specific terminology. The domain packs build on our global languages to give the best accuracy.
| Domain | Supported languages | Description |
|---|---|---|
| Finance | (en) | Improve accuracy for audio containing financial terms such as those found in earnings calls or financial broadcast |
Refer to documentation here for more details on how to set the domain parameter.
The Speechmatics Batch SaaS supports the following file types for transcription:
The list above is exhaustive - any file format outside the list above is explicitly not supported.
The supported size limit for jobs is 2 hours of audio or 1 GB file size. Any larger or longer files may be rejected.
Audio files, transcripts, and configuration data are stored in the Speechmatics Batch SaaS for 7 days. Any request to retrieve a transcript or file more than 7 days after it was processed will receive a HTTP 404 error message and a status of expired.
You can delete audio or transcripts in advance of this 7 day period - how to do so is documented in the How-To Guide.
This section talks through the prerequisites to authenticate to the Speechmatics Batch SaaS.
Speechmatics Support will provide you a unique Authorization Token. This must be used with any interaction with the Speechmatics Batch SaaS to authenticate to the service. Any interaction without this token will receive a HTTP 401 - Unauthorized response.
The Authorization Token must be passed in the header of any request to the Speechmatics Batch SaaS. The Token itself conforms to OAuth2 protocols.
It is your responsibility to store the Authorization Token securely and ensure it is not mishandled. It is recommended that you store and provide access to the Token on the principle of least privilege. If you believe that your Token has been compromised, please contact Speechmatics Support.
If you are using the trial Speechmatics endpoint, please note your authorization token may be time limited. If you try and use the token after the trial period has expired, you will receive a HTTP 401 - Unauthorized response.
Speechmatics Batch SaaS supports the following endpoints for production use:
| Region | Environment | Endpoints |
|---|---|---|
| EU | EU1 | eu.asr.api.speechmatics.com eu1.asr.api.speechmatics.com asr.api.speechmatics.com |
| EU | EU2 | eu2.asr.api.speechmatics.com |
| US | US1 | us.asr.api.speechmatics.com us1.asr.api.speechmatics.com |
| US | US2 | us2.asr.api.speechmatics.com |
Authorization Tokens are replicated between all environments in the same region. Therefore, you can use any environment in a region that you are entitled to access.
All production environments are active and highly available. Multiple environments can be used to balance requests or provide a failover in the event of disruption to one environment.
Note that jobs are created in the environment corresponding to the endpoint used. You must use the same endpoint for all requests relating to a specific job.
If you attempt to use an endpoint for a region you are not contracted to use, that request will be unsuccessful. If you want to use a different region, please contact sales@speechmatics.com.
The Trial endpoint is trial.asr.api.speechmatics.com
If you want to receive notifications from the Speechmatics Batch SaaS, you need to enable access to (allowlist) the egress IP addresses for the relevant environments.
Here is a list of the egress IP addresses for each environment:
| Regions | IP Addresses |
|---|---|
| EU1 | 40.74.41.91, 52.236.157.154, 40.74.37.0, 20.73.209.153, 20.73.142.44 |
| EU2 | 20.105.89.153, 20.105.89.173, 20.105.89.184, 20.105.89.98, 20.105.88.228 |
| US1 | 52.149.21.32, 52.149.21.10, 52.137.102.83, 40.64.107.92, 40.64.107.99 |
| US2 | 52.146.58.224, 52.146.58.159, 52.146.59.242, 52.146.59.213, 52.146.58.64 |
| Trial | 20.101.4.47, 20.93.251.234 |
Speechmatics Batch SaaS applies rate limiting and fair queueing to provide a consistently high quality of service to all users.
If you make a large number of requests in a short period of time, some of these requests may fail with the response HTTP 429 - Rate Limited. To minimise the possibility of encountering rate limiting errors, we recommend that you do not exceed the following rates:
POST API calls).GET API calls).Aside from rate limiting, there is no limit to the number of jobs that you can submit. However, Speechmatics Batch SaaS applies a fair queueing policy which means that if you have a large number of jobs in progress at one time, the most recently submitted jobs may take longer to complete.
If you require a service which exceeds the recommendations above, please contact support@speechmatics.com
Please note: all timestamps from the Speechmatics Batch SaaS are in ISO 8601 format, and use Coordinated Universal Time (UTC).
Code samples in this guide use curl for making HTTP requests to the API, and the jq tool to parse and display JSON responses.
The API uses a standardised authentication method, with a wide range of supported output formats and has a structured JSON configuration that is easier to extend in the future.
For the full API specification please refer to the API Reference section.