V1 API Reference

Use the Speechmatics REST API to programmatically interact with our platform and various services, such as transcription.

Deprecation Note

The V1 API is now deprecated and will be removed by February 2022. Use this section for troubleshooting only.

Version: 1.1.0

Terms of service

https://www.speechmatics.com/terms-and-conditions/

Contact information

support@speechmatics.com

URI scheme

BasePath: /v1/

Schemes: HTTPS, HTTP

/user/{userid}/jobs/

GET

Summary:

List all jobs for a user.

Parameters
NameLocated inDescriptionRequiredSchema
useridpathID of user to return details for.Yesinteger
limitqueryMaximum number of results to return (always returns most recent).Nostring
startdatequeryOnly return jobs created since this date (date format should be YYYY-MM-DD).Nodate
enddatequeryOnly return jobs created before this date (date format should be YYYY-MM-DD).Nodate
Responses
CodeDescriptionSchema
200OKRetrieveJobsResponse
401UnauthorizedErrorResponse

POST

Summary:

Create a new job.

Parameters
NameLocated inDescriptionRequiredSchema
useridpathID of user to return details for.Yesinteger
data_urlformDataThe url to audio file to be processed.Nostring
data_fileformDataThe path to audio file to be processed.Nofile
text_urlformData(Alignment only) The url to text file that audio file should be aligned to. If neither of text_url and text_file is specified, the audio file will be transcribed instead.Nostring
text_fileformData(Alignment only) The path to text file that audio file should be aligned to. If neither of text_url and text_file is specified, the audio file will be transcribed instead.Nofile
modelformDataLanguage product used to process the job. Currently supported language products are listed on our support page. Language can alternatively be specified by the config object.Nostring
notificationformDataHow you would like to be notified of your job finishing.Nostring
notification_email_addressformDataThe 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'.Nostring (email)
callbackformData(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/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.Nostring
callback_formatformData(Only if notification is set to callback.) The format to be used by the Speechmatics service for the callback POST request.Nostring
metaformDataMetadata about the job you would like to be able to view later, such as the sources this job is derived from.Nostring
diarizationformDataControl whether or not the resulting transcript will have speaker information. If speed is essential, set to 'false'.Noboolean
diarisationformDataNoboolean
configformDataJobConfig encoded as JSON string indicating the type and parameters for the recognition job. This is preferred to the deprecated approach of specifying recognition job settings using individual form parameters, like model and diarization.Nostring
Responses
CodeDescriptionSchema
200OKCreateJobResponse
400Bad requestErrorResponse
401UnauthorizedErrorResponse
403ForbiddenErrorResponse

/user/{userid}/jobs/{jobid}/

GET

Summary:

Get job details, including progress and any error reports.

Parameters
NameLocated inDescriptionRequiredSchema
useridpathID of user the job belongs to.Yesinteger
jobidpathID of the job to return details for.Yesinteger
Responses
CodeDescriptionSchema
200OKRetrieveJobResponse
401UnauthorizedErrorResponse
404Not foundErrorResponse

DELETE

Summary:

Delete a job and remove all associated resources.

Parameters
NameLocated inDescriptionRequiredSchema
useridpathID of user the job belongs to.Yesinteger
jobidpathID of the job to return details for.Yesinteger
Responses
CodeDescriptionSchema
200The job that was deleted.DeleteJobResponse
401UnauthorizedErrorResponse
404Not foundErrorResponse

/user/{userid}/jobs/{jobid}/transcript

GET

Summary:

Get transcript file for a particular transcription job.

Parameters
NameLocated inDescriptionRequiredSchema
useridpathID of user the job belongs to.Yesinteger
jobidpathID of the job to return details for.Yesinteger
formatqueryThe transcription format, allowed values are json, json-v2, txt, srt, (by default the '1.0' JSON format is returned).Nostring
Responses
CodeDescriptionSchema
200OKRetrieveTranscriptResponse
401UnauthorizedErrorResponse
404Not foundErrorResponse

Models

ErrorResponse

NameTypeDescriptionRequired
codeintegerThe HTTP status code.Yes
errorstringThe error message.Yes
detailstringThe details of the error.No

User

NameTypeDescriptionRequired
balanceintegerThe remaining balance on your account, in Speechmatics credits.Yes
emailstring (email)The email address your account is associated with.Yes
idintegerThe ID of the user.Yes
auth_tokenstringThe authorization token of the user, returned if requested via /user with Basic Auth.No

RetrieveUserResponse

NameTypeDescriptionRequired
userUserYes

TranscriptionConfig

NameTypeDescriptionRequired
TranscriptionConfigobject

OutputConfig

NameTypeDescriptionRequired
OutputConfigobject

NotificationConfig

NameTypeDescriptionRequired
urlstringHTTP(S) URL which the transcription result will be POSTed back to. Will attempt POST with a 10, 20 and 30 second timeout. Uses User-agent value of 'Speechmatics API v1.0'.No

JobConfig

NameTypeDescriptionRequired
typestringYes
transcription_configTranscriptionConfigNo
output_configOutputConfigNo

CreateJobResponse

NameTypeDescriptionRequired
balanceintegerThe remaining balance on your account, in Speechmatics credits.Yes
check_waitintegerThe length of time (in seconds), Speechmatics advises you should wait before next checking on the status of this job.Yes
costintegerThe job cost (in Speechmatics credits).Yes
idintegerThe unique ID assigned to the job. Keep a record of this for later retrieval of your completed job.Yes

JobDetails

NameTypeDescriptionRequired
alignmentstring(Alignment only), The name of processed alignment output file (if the alignment field is null then the job is still in progress).No
check_waitintegerThe length of time (in seconds), Speechmatics advises you should wait before next checking on the status of this job (null if job is finished).Yes
created_atstringThe UTC date time the job was created.Yes
durationintegerThe file duration (in seconds).Yes
idintegerThe unique id assigned to the job.Yes
job_statusstringThe status of the job.Yes
job_typestringThe type of jobYes
langstringLanguage product used to process the job.Yes
metastringThe metadata provided when the job was created.Yes
namestringName of audio file submitted for job.Yes
next_checkinteger(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.Yes
notificationstringHow you would like to be notified of job completion.Yes
text_namestring(Alignment only), The text file submitted to be aligned to audio.No
transcriptionstring(Transcription only), The name of processed transcription file (if the transcription field is null then the job is still in progress).No
urlstringThe internal url used to locate your file on the Speechmatics system.No
user_idintegerThe ID of the user.Yes
transcription_configTranscriptionConfigNo

RetrieveJobsResponse

NameTypeDescriptionRequired
jobs[JobDetails]Yes

RetrieveJobResponse

NameTypeDescriptionRequired
jobJobDetailsYes

DeleteJobResponse

NameTypeDescriptionRequired
jobJobDetailsYes

RetrieveTranscriptResponse

NameTypeDescriptionRequired
RetrieveTranscriptResponseobject