API Documentation


Speechmatics API V1

Speechmatics offer a secure REST API that enables you to programatically upload audio files for processing with our different products and download the resulting transcriptions.

The root url for the API is https://api.speechmatics.com/v1.0/ and is covered by the documentation below.

All examples on this page use curl.

We recommend setting your retry parameters so they retry for at least one minute, for curl e.g., '--retry 5 --retry-delay 10'. This has been omitted from the following curl examples for brevity.

All successful API calls return in JSON format with return code 200. Users of curl will see this displayed in their terminal, other interfaces may need a JSON parser.

What you should expect from unsuccessful API calls (which can be caused by errors either on your end or our end) is documented here

Register / Login

To use any Speechmatics product or service, you must first register and then login.

Testing

If you are developing an interface to a Speechmatics product or service, we recommend testing by posting a zero length audio file. This will not cost you any credits and will complete very quickly. The resulting transcription will be empty, but all other fields of the JSON returned will be as you would normally get for a Speechmatics job.

Uploads will timeout after 1 hour so please make sure your files are small enough to upload in a timely manner. After the data transfer finishes, it may take up to 120 seconds to generate the HTTP reply. We transcribe audio on video uploads and we therefore have a large file size limit of 4GB. Should either of these restrictions prove problematic please email us.

To receive callbacks you may need to open your firewall to our IP address, which is currently 35.165.188.128

API Resources

Click on a resource to jump to a detailed explanation including curl examples

Resource Description

/user/$userid/

GET user details for your account

/user/$userid/jobs/

GET a list of transcription jobs for your account.
POST to upload an audio file and start a new job.

/user/$userid/jobs/$jobid/

GET details for a particular job, including progress and any error reports.

/user/$userid/jobs/$jobid/transcript

GET transcript file for a particular transcription job.

/user/$userid/jobs/$jobid/alignment

GET aligned file for a particular alignment job.

/user/$userid/payments/

GET your credit payment history.

/status

GET current service status

errors

Common errors

/user/$userid/

GET user details for your account

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/?auth_token=$MY_API_AUTH_TOKEN"

Example Response:

{
    "user": {
      "balance": 90,
      "email": "demo@speechmatics.com",
      "id": 1
    }
  }
Fields:

'balance': your remaining balance, in Speechmatics credits.

'email': the email address your account is registered to.

'id': your unique API User ID

^ back to resources list

/user/$userid/jobs/

GET a list of transcription jobs for your account.

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/?auth_token=$MY_API_AUTH_TOKEN"
Parameters:

'limit': maximum number of results to return (always returns most recent)

'startdate': only return jobs created since this date (date format should be YYYY-MM-DD)

'enddate': only return jobs created before this date (date format should be YYYY-MM-DD)

Example Response:

{
    "jobs": [
      {
        "check_wait": null,
        "created_at": "Wed, 04 Dec 2013 16:00:47 GMT",
        "duration": 244,
        "id": 2,
        "job_status": "done",
        "job_type": "transcription",
        "lang": "en-US",
        "meta": null,
        "name": "test.mp3",
        "next_check": 0,
        "notification": "email",
        "transcription": "test.json",
        "url": "/v1.0/user/1/jobs/2/audio",
        "user_id": 1
      },
      {
        "alignment": null,
        "check_wait": 30,
        "created_at": "Mon, 10 Aug 2015 09:02:23 GMT",
        "duration": 10,
        "id": 51807,
        "job_status": "aligning",
        "job_type": "alignment",
        "lang": "en-US",
        "meta": "Project X",
        "name": "hello.wav",
        "next_check": 0,
        "notification": "email",
        "text_name": "hello.txt",
        "url": "/v1.0/user/22/jobs/51807/audio",
        "user_id": 1
      }
    ]
  }
Fields:

'alignment': (alignment only) name of processed alignment output file (if the alignment field is null then the job is still in progress).

'check_wait': how long (in seconds) Speechmatics advises you should wait before next checking on the status of this job (null if job is finished).

'created_at': when the job was submitted to Speechmatics.

'duration': file duration (in seconds).

'id': unique id assigned to the job.

'job_status': status of the job. The values this field can take are: transcribing / aligning (job is being processed), done / expired (job finished processing), rejected / unsupported_file_format / could_not_align (file could not be processed).

'job_type': the type of job (e.g., 'transcription' or 'alignment')

'lang': language product used to process the job.

'meta': any metadata provided when the job was POSTed. If there was none, defaults to null.

'name': name of audio file submitted for job.

'next_check': (deprecated - please use check_wait instead) the recommended time for your next progress check in epoch seconds - if the job is complete next_check will be zero.

'notification': how you would like to be notified of job completion (email / callback / none).

'text_name': (alignment only) text file submitted to be aligned to audio.

'transcription': (transcription only) name of processed transcription file (if the transcription field is null then the job is still in progress).

'url': internal url used to locate your file on the Speechmatics system.

'user_id': your unique Speechmatics User ID.

POST to upload an audio file and start a new job. (Content type should be multipart/form-data).

Usage:

curl -F data_file=@my_audio_file.mp3 -F model=en-US "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/?auth_token=$MY_API_AUTH_TOKEN" # transcription
  curl -F data_file=@my_audio_file.mp3 -F text_file=@my_text_file.txt -F model=en-GB "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/?auth_token=$MY_API_AUTH_TOKEN" # alignment
Fields:

'data_file': path to audio file to be processed.

'text_file': (alignment only) path to text file that audio file should be aligned to. If this field is not specified, the audio file will be transcribed instead.

'model': language product used to process the job.

'notification': (optional) how you would like to be notified of your job finishing (email / none / callback). Defaults to 'email'. e.g., -F 'notification=callback' -F 'callback=http://your_url.com/transcript_callback'

'notification_email_address': (optional) alternative email address to use in the notification. Defaults to email used during registration if this optional argument is unused. Requires notification type to be set to 'email'. e.g -F 'notification_email_address=myalternate@address.com'

'callback': (only if notification is set to callback) if set and notification set to 'callback', the Speechmatics service will make a POST request to this URL when the job completes, including the full JSON transcript in a file attachment (named data_file, accessible for example in JavaScript by request.files.get('data_file')) along with the job id as a parameter (for example, http://www.example.com/transcript_callback?id=1). The URL callback will be attempted with a 10s timeout. If it fails, it will be retried with a 20s timeout and if it fails again, with a 30s timeout. If the URL callback fails three times, an email with an error message including the HTTP return code (if any) will be sent to the user's email address..

'meta': (optional) metadata about the POSTed job you would like to be able to view later, e.g., which of your sources this job is derived from (-F meta=your_meta_tag). Metadata is limited to 1024 characters per job.

'diarisation': (optional) whether or not the resulting transcript will have speaker information. Defaults to 'true'. If speed is essential, set to 'false' (-F diarisation='false').

Example Response:

{
    "balance": 95,
    "check_wait": 30,
    "cost": 5,
    "id": 20
  }
Fields:

'balance': your remaining balance, in Speechmatics credits.

'check_wait': how long (in seconds) Speechmatics advises you should wait before next checking on the status of this job (null if job is finished).

'cost': how much the job cost (in Speechmatics credits).

'id': unique id assigned to the job. Keep a record of this for later retrieval of your completed job.

^ back to resources list

/user/$userid/jobs/$jobid/

GET details for a particular job, including progress and any error reports.

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/$MY_JOB_ID/?auth_token=$MY_API_AUTH_TOKEN"

Example Response:

{
    "job": {
      "check_wait": null,
      "created_at": "Wed, 04 Dec 2013 16:00:47 GMT",
      "duration": 244,
      "id": 2,
      "job_status": "done",
      "job_type": "transcription",
      "lang": "en-US",
      "meta": null,
      "name": "test.mp3",
      "next_check": 0,
      "notification": "email",
      "transcription": "test.json",
      "url": "/v1.0/user/1/jobs/2/audio",
      "user_id": 1
    }
  }
Fields:

'alignment': (alignment only) name of processed alignment output file (if the alignment field is null then the job is still in progress).

'check_wait': how long (in seconds) Speechmatics advises you should wait before next checking on the status of this job (null if job is finished).

'created_at': when the job was submitted to Speechmatics.

'duration': file duration (in seconds).

'id': unique id assigned to the job.

'job_status': status of the job. The values this field can take are: transcribing / aligning (job is being processed), done / expired (job finished processing), rejected / unsupported_file_format / could_not_align (file could not be processed).

'job_type': the type of job (e.g., 'transcription' or 'alignment')

'lang': language product used to process the job.

'meta': any metadata provided when the job was POSTed. If there was none, defaults to null.

'name': name of audio file submitted for job.

'next_check': (deprecated - please use check_wait instead) the recommended time for your next progress check in epoch seconds - if the job is complete next_check will be zero.

'notification': how you would like to be notified of job completion (email / callback / none).

'text_name': (alignment only) text file submitted to be aligned to audio.

'transcription': (transcription only) name of processed transcription file (if the transcription field is null then the job is still in progress).

'url': internal url used to locate your file on the Speechmatics system.

'user_id': your unique Speechmatics User ID.

^ back to resources list

/user/$userid/jobs/$jobid/transcript

GET transcript file for a particular transcription job.

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/$MY_JOB_ID/transcript?auth_token=$MY_API_AUTH_TOKEN"
Parameters:

'format=txt': (optional) With this parameter, the file is returned in plain text rather than json format. e.g.,

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/$MY_JOB_ID/transcript?format=txt&auth_token=$MY_API_AUTH_TOKEN"

Example Response:

{
    "job": {
      "lang": "en-US",
      "user_id": 1,
      "name": "hello_world.mp3",
      "duration": 2,
      "created_at": "Thu Jan 01 00:00:00 1970",
      "id": 1
    },
    "speakers": [
      {
        "duration": "2.000",
        "confidence": null,
        "name": "F1",
        "time": "0.000"
      },
    ],
    "words": [
      {
        "duration": "1.000",
        "confidence": "0.943",
        "name": "Hello",
        "time": "1.000"
      },
      {
        "duration": "1.000",
        "confidence": "0.995",
        "name": "world",
        "time": "2.000"
      },
      {
        "duration": "0.000",
        "confidence": null,
        "name": ".",
        "time": "3.000"
      },
    ]
    "format": "1.0"
  }
Fields:

'job' object:

'created_at': when the job was submitted to Speechmatics.

'duration': file duration (in seconds).

'id': unique id assigned to the job.

'lang': language product used to process the job.

'name': name of audio file submitted for job.

'user_id': your unique Speechmatics User ID.

'speakers' (information on speaker identified in audio) / 'words' (information on words identified in audio) objects:

'duration': how long the speaker / word lasted for (s).

'confidence': how confident the system is in the word (speakers and punctuation words always have this field set to null).

'name': unique speaker identifier (including M/F gender) / word identified.

'time': when in the audio (relative to the start) this item was first identified (s).

'format' object: Speechmatics .json transcript format version number.

^ back to resources list

/user/$userid/jobs/$jobid/alignment

GET aligned file for a particular alignment job.

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/$MY_JOB_ID/alignment?auth_token=$MY_API_AUTH_TOKEN"
Parameters:

'tags=one_per_line': (optional) With this parameter, the file is returned with one timing tag per line rather than one at the start and end of each word. e.g.,

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/jobs/$MY_JOB_ID/alignment?tags=one_per_line&auth_token=$MY_API_AUTH_TOKEN"

Example Response:

[00:00:00.1]	Hello world how are you? # with tags=one_per_line

More details of our alignment service can be found here.

^ back to resources list

/user/$userid/payments/

GET your credit payment history.

Usage:

curl "https://api.speechmatics.com/v1.0/user/$MY_API_USER_ID/payments/?auth_token=$MY_API_AUTH_TOKEN"
Parameters:

'limit': maximum number of results to return (always returns most recent)

'startdate': only return payments since this date (date format should be YYYY-MM-DD)

'enddate': only return payments from before this date (date format should be YYYY-MM-DD)

Example Response:

{
    "payments": [
      {
        "balance": -12,
        "created_at": "Wed, 01 Jan 2014 09:10:00 GMT",
        "description": "Transcription of hello.wav"
      },
      {
        "balance": 1000,
        "created_at": "Wed, 01 Jan 2014 09:10:00 GMT",
        "description": "1,000 credits added"
      }
    ]
  }
Fields:

'balance': the affect this payment had on your credit balance (positive numbers mean credited to your account, negative numbers mean debited from your account).

'created_at': when the payment was processed by Speechmatics.

'description': a description of the payment.

^ back to resources list

/status

GET current service status

Usage:

curl "https://api.speechmatics.com/v1.0/status"

Example Response:

{
    "Average_Turnaround_Mins": 5,
    "Known_Issues": false,
    "Queue_Length_Mins": 0,
    "Status": "Good",
    "Time_UTC": "Mon, 01 Jan 2016 00:00:00 GMT"
  }
Fields:

'Average_Turnaround_Mins': rolling average of turnaround times.

'Known_Issues': whether there are any known issues that may affect service at present.

'Queue_Length_Mins': how long after submission jobs currently have to wait to start being processed.

'Status': overall status of the service. This can either be 'Good' (all jobs should be processed in a timely manner) or 'Slow' (your jobs may be delayed).

'Time_UTC': time (in UTC) of when the service status was last checked.

^ back to resources list

Common Error Codes

If we are unable to process your request we will typically return one of the below error codes.

We would suggest that your API integration should be created robustly to these errors.

4xx errors

The 4xx class of status codes is intended for situations in which your request seems to be in some way in error.

All 4xx http errors return in JSON format. Users of curl will see this displayed in their terminal, other interfaces may need a JSON parser.

The JSON object contains two members, the return code and an error message. More details on these common errors for each endpoint are below. Example error object:

$ curl "https://api.speechmatics.com/v1.0/nonexistentendpoint"
  {
    "code": 404,
    "error": "Page Not Found"
  }
Common error returns:

400, "error": "Malformed request" Your request contained something unexpected - perhaps a string as a parameter where an integer was expected?

400, "error": "Missing data_file" Your request did not contain a data file in the data_file field.

400, "error": "No language selected" You did not supply a value in the 'model' field.

400, "error": "Missing callback" You requested notification via callback but did not provide a callback url.

400, "error": "Requested product not available" You requested an unsupported language for your alignment / transcription.

401, "error": "Invalid User Id or Token" Your user id / authentication token do not match those in our database

403, "error": "Job rejected due to invalid audio" Your audio file was in a format we do not support.

403, "error": "Insufficient Credit" Your audio file would cost more credits to process than you have available in your account.

404, "error": "Job not found" We could not find a job with the specified id associated with your account

404, "error": "Text could not be aligned to audio" Unfortunately we could not accurately align your audio and text.

404, "error": "Job was rejected on submission" The job with this id was rejected on submission, probably due to an unsupported file format.

404, "error": "Job is not of type alignment" We found a job with this id associated with your account, but it is not an alignment job.

404, "error": "Job In Progress" The requested job is still being processed - please wait.

404, "error": "Output format Not Supported" You have requested the output in an unsupported format.

429, "error": "Too Many requests" You are trying to make too many POST requests in too short a period of time. Reduce your POST send rate.

5xx errors

The 5xx class of status codes is intended for situations in which your request appears valid but nonetheless the server failed to fulfill an apparently valid request.

All 5xx http errors return a html snippet

Common error returns:

500, "Internal Server Error" Our service suffered an internal error. Please please contact us with as much information as possible for us to debug the problem.

502, "Bad Gateway" Our service is not active at present - more than likely due to maitenance. We try to inform users in advance of maintenance periods.

503, "Service Temporarily Unavailable" Our service is temporarily overloaded and unable to process your request - please try again soon.

Contact Us

If you need further help getting started with any Speechmatics service, please contact us!