/
SaaS
/
Introduction

Introduction

This document will walk you through how to use the RESTful API for the Speechmatics SaaS. This document will show you

  • How to authenticate and connect to the Speechmatics SaaS endpoint
  • How to successfully submit a file for processing
  • How to check on the status of any transcription job
  • How to retrieve a transcript in the format of your choice

This section shows:

  • Supported languages and file formats
  • How to use the Authorization Token
  • How to connect to a valid Speechmatics endpoint
  • Rate limits

Supported languages

The Speechmatics 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.

LanguageLanguage Code
Arabic(ar)
Bulgarian(bg)
Catalan(ca)
Croatian(hr)
Czech(cs)
Danish(da)
Dutch(nl)
English(en)
Finnish(fi)
French(fr)
German(de)
Greek(el)
Hindi(hi)
Hungarian(hu)
Italian(it)
Japanese(ja)
Korean(ko)
Latvian(lv)
Lithuanian(lt)
Malay(ms)
Mandarin(cmn)
Norwegian(no)
Polish(pl)
Portuguese(pt)
Romanian(ro)
Russian(ru)
Slovakian(sk)
Slovenian(sl)
Spanish(es)
Swedish(sv)
Turkish(tr)

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 ISO639-1 code that must be provided for any transcription request.

Supported file types

The Speechmatics SaaS supports the following file types for transcription:

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

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

File Size Limits

The supported size limit for jobs is 2 hours of audio or 1 GB file size. Any larger or longer files may be rejected.

Data Retention Limits

Audio files, transcripts, and configuration data are stored in the Speechmatics 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

Connecting to the Speechmatics SaaS

This section talks through the Pre-Requisites to authenticate to the Speechmatics SaaS

Authorization Token

Speechmatics Support will provide you a unique Authorization Token. This must be used with any interaction with the Speechmatics 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 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.

Trial tokens

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.

Supported endpoints

Below are the supported endpoints.You should use the hostname for the region you are contracted to use:

  • EU region: asr.api.speechmatics.com
  • US region: us.asr.api.speechmatics.com
  • Trial: trial.asr.api.speechmatics.com

If you want to use a different region please contact sales@speechmatics.com. If you try to use a hostname for a region you are not contracted to use, that job will be unsuccessful

IP whitelisting (for notifications)

If you want to receive notifications from the Speechmatics SaaS, you will need to whitelist the following egress IP addresses. You should only whitelist the IP addresses from the geo region you are contracted to use

The list is below:

IP AddressRegion
20.101.4.47Trial
20.93.251.234Trial
40.74.41.91EU
52.236.157.154EU
40.74.37.0EU
20.73.209.153EU
20.73.142.44EU
52.149.21.32US
52.149.21.10US
52.137.102.83US
40.64.107.92US
40.64.107.99US

Rate limiting and fair usage

Speechmatics 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:

  • 10 new jobs per second (POST API calls).
  • 50 job status requests per second (GET API calls).

Aside from rate limiting, there is no limit to the number of jobs that you can submit. However, Speechmatics 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

Timestamps

Please note: all timestamps from the Speechmatics SaaS are in ISO 8601 format, and use Coordinated Universal Time (UTC).

A note on tools

Code samples in this guide use curl for making HTTP requests to the API, and the jq tool to parse and display JSON responses.

API Specification

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.