Usage

Note: If you have your own app/backend, and you want to integrate the API gateway as a service, we recommend you to read through Integration, to help you reduce user management part and delegate to the API gateway instead

Login

POST https://gateway.speechlab.sg/auth/login

This endpoint is used to log in into an existing account.

Request Body

Name	Type	Description
email	string	Account's email
password	string	Account's password

200 Login successful

{
    "accessToken": "Your token"
}

401 Email or Password is incorrect

Register

POST https://gateway.speechlab.sg/auth/register

This endpoint is used to register an account.

Request Body

Name	Type	Description
name	string	Account's name Must be longer than 2 characters
email	string	Account's email
password	string	Account's password Must be longer than 5 characters

201 Registration successful

{
    "role": "user",
    "_id": "user_id",
    "name": "user_name",
    "email": "[e-mail]",
    "createdAt": "2020-12-31T00:00:00.000Z"
}

After successfully registering an account, an email verification link will sent to the email address to verify your email address. You need to click into verification link which is sent along with the email.

Submit a job

POST https://gateway.speechlab.sg/speech

Headers

Name	Type	Description
Authorization	string	Access Token. Bearer <access token obtained from login>

Request Body

Name	Type	Description
file	object	File Object
lang	string	Language code Examples (not exhaustive): 'english', 'mandarin', 'malay', 'english-mandarin', 'english-malay'
queue	string	Queue that speech job will be assigned to Example (not exhaustive): 'normal' If not specified, will default to 'normal' queue
audioType	string	Examples: 'fartalk', 'closetalk', 'mobile', 'telephony', 'boundary'
audioTrack	string	Examples: 'single', 'multi'
sampling	string	Example: '16khz' If not specified, will default to '16khz'
keywords	array	An array of strings
numChn	number	Number of audio channels
outputFormats	array	An array of file extensions Example: ['txt', 'srt']
checksum	string	md5 checksum string of the file object to check if received file is identical
webhook	string	API endpoint to receive update when your speech is completed Example: 'http://your-api.com/status'
customData	JSON object	To pass other extra metadata such as num_spk and orgID. Example: {"num_spk":-1} -1 if no. of speaker is unknown.

200

{
    "queue": "normal",
    "result": null,
    "status": "created",
    "formats": [
        "stm",
        "srt",
        "TextGrid"
    ],
    "sampling": "16khz",
    "lang": "english",
    "name": "Note",
    "_id": "609608c3ec54c0066abb7531", // Note down this value
    "type": "batch",
    "createdAt": "2021-05-08T03:42:59.708Z"
}

400 No "file" object was found in the request.

403 User is not allowed to submit jobs to the "queue" specified in the request.

422 "lang" field provided was not one of the accepted values. Invalid values for other fields will also return 422 error code.

After request successfully, in the response returned, the field _id is the ID of the job, also referred to as 'SpeechID'. Note this value down (to be used in future requests).

About audioType and audioTrack: If audioType and audioTrack fields can be provided that best describes the audio file, our system will try to use our best-fit model to give a better result.

About webhook: An audio file may take a long time to decode (dependent on its duration, type,...), and the processing time is not deterministic (likely not the same for 2 identical jobs). Instead of calling our endpoint to check on the status of a job, a HTTP endpoint can be provided via the webhook field, and when the job is done, the HTTP endpoint provided will be notified of the job's completion. Subsequently, our other endpoint can be called to download the transcription file(s).

About queue: A queue is where the job will be running in, each queue will have some workers to pick up jobs and process. If not specified, the job will be submitted to normal queue and where this queue is shared among others. Therefore, when there are already existing jobs in the queue, this job will be pending until there are workers available. If you want to have dedicated queue that is not shared with others, please contact our support to get in touch.

Get user's speech history

GET https://gateway.speechlab.sg/speech/history

This endpoint is used to retrieve a user's speech history. Filter options "queue", "status", "lang", and "type" are optionally available to filter returned results.

Path Parameters

Name	Type	Description
email	string	Email of user's history to retrieve For 'normal' accounts, only user's own email is accepted (but is optional as user can be identified by their token already)
queue	string	Queue of speech jobs Example (not exhaustive): 'normal'
status	string	Status of speech jobs Examples (not exhaustive): 'done', 'processing'
lang	string	Language code of speech jobs Examples (not exhaustive): 'english', 'mandarin', 'malay', 'english-mandarin', 'english-malay'
type	string	Type of speech jobs Examples: 'live', 'batch'

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

200

{
    "history": [
        {
            "queue": "normal",
            "status": "done",
            "formats": [
                "txt",
                "stm"
            ],
            "sampling": "16khz",
            "lang": "english",
            "name": "Note",
            "_id": "6135c0fc9dda32002d4d91d2",
            "userCreated": {
                "role": "admin",
                "type": "normal",
                "name": "user",
                "_id": "5f868425deb32e0029690890",
                "isBlocked": false,
                "isDeleted": false,
                "isVerified": true,
                "email": "[e-mail]",
                "createdAt": "2020-10-14T04:52:53.905Z",
                "updatedAt": "2021-05-25T08:50:13.832Z",
                "__v": 0
            },
            "input": [
                {
                    "isSubmitted": true,
                    "errorCode": null,
                    "status": "done",
                    "progress": [
                        {
                            "content": "DECODING",
                            "createdAt": "2021-09-06T07:19:42.772Z"
                        },
                        {
                            "content": "DONE",
                            "createdAt": "2021-09-06T07:21:25.186Z"
                        }
                    ],
                    "_id": "6135c0fc9dda32002d4d91d4",
                    "file": {
                        "children": [],
                        "parent": null,
                        "_id": "6135c0fc9dda32002d4d91d3",
                        "originalName": "audio.wav",
                        "mimeType": "audio/wave",
                        "filename": "36436d30-701b-407b-9dfd-230a9d5ba600-1630912764391.wav",
                        "size": 187404,
                        "duration": 5.855,
                        "userCreated": "5f868425deb32e0029690890",
                        "createdAt": "2021-09-06T07:19:24.591Z"
                    }
                }
            ],
            "type": "batch",
            "createdAt": "2021-09-06T07:19:24.550Z",
            "updatedAt": "2021-09-06T07:21:25.333Z",
            "__v": 0,
            "sourceFile": {
                "children": [],
                "parent": null,
                "_id": "6135c0fc9dda32002d4d91d3",
                "originalName": "audio.wav",
                "mimeType": "audio/wave",
                "filename": "36436d30-701b-407b-9dfd-230a9d5ba600-1630912764391.wav",
                "size": 187404,
                "duration": 5.855,
                "userCreated": "5f868425deb32e0029690890",
                "createdAt": "2021-09-06T07:19:24.591Z"
            }
        }
    ],
    "totalHistory": 1
}
        

401 "Normal" account user tried to query for another user's history

Get job status

GET https://gateway.speechlab.sg/speech/:id

This endpoint is used to retrieve a speech job's status. Alternatively, consider passing webhook field when submitting a job as described in "Submit a job" endpoint above.

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

200

{
    "status": "processing",
    "formats": [
        "stm",
        "srt",
        "TextGrid"
    ],
    "sampling": "16khz",
    "lang": "english",
    "name": "Note",
    "_id": "5f11c797b6d18b0029b60975",
    "queue": "normal",
    "input": [
        {
            "isSubmitted": true,
            "errorCode": null,
            "status": "processing",
            "progress": [{
                "content": "Decoding",
                "createdAt": "2020-07-17T15:45:27.941Z"
            }],
            "_id": "5f11c798b6d18b0029b60977",
            "file": {
                "_id": "5f11c797b6d18b0029b60976",
                "originalName": "james-test.wav",
                "mimeType": "audio/wave",
                "filename": "5f11c797b6d18b0029b60976.wav",
                "size": 187404,
                "duration": 5.855,
                "createdAt": "2020-07-17T15:45:27.941Z"
            }
        }
    ],
    "createdAt": "2020-07-17T15:45:27.882Z",
    "sourceFile": {
        "_id": "5f11c797b6d18b0029b60976",
        "originalName": "james-test.wav",
        "mimeType": "audio/wave",
        "filename": "5f11c797b6d18b0029b60976.wav",
        "size": 187404,
        "duration": 5.855,
        "createdAt": "2020-07-17T15:45:27.941Z"
    }
}

404 No speech job found for provided Speech ID

Get transcription (Deprecated)

GET https://gateway.speechlab.sg/speech/result/:id

This endpoint will redirect to a URL to download the transcription files if Speech status is done.

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

200

Return transcription downloadable file

404

Get transcription (New)

GET https://gateway.speechlab.sg/speech/:id/result

This endpoint will return a URL to download the transcription files if Speech status is done.

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

200

{
    "url": "link to download transcription files"
}

404

Change account's password

POST https://gateway.speechlab.sg/auth/change-password

This endpoint is used to change an existing account's password.

Request Body

Name	Type	Description
email	string	Account's email
currentPassword	string	Account's current password
newPassword	string	New password
confirmNewPassword	string	New password for confirmation

200

{
    "message": "Password changed successfully"
}

404 No account found with provided email

Forgot account's password

POST https://gateway.speechlab.sg/auth/forgot-password

This endpoint is used to reset an existing account's password. An email will be sent to the email address which contains a code used to reset password.

Request Body

Name	Type	Description
email	string	Account's email

200 Request to reset password send successfully, check email's inbox to get reset code

{
    "message": "Please check your inbox for reset password code"
}

404 No account found with provided email

Reset password

POST https://gateway.speechlab.sg/auth/reset-password

This endpoint is used to reset an account's password with a code obtained from the "Forgot account's password" endpoint.

Request Body

Name	Type	Description
email	string	Account's email
code	string	Forgot password code
newPassword	string	New password
confirmNewPassword	string	Confirm new password

200 Account's password successfully reset.

{
    "message": "Your password has been reset"
}

404 No account found with the provided email, or the code is invalid.

406 Your newPassword and confirmNewPassword are not matched.

Change account's name

GET https://gateway.speechlab.sg/users/change-name

This endpoint is for users to change their own account's name.

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

Request Body

Name	Type	Description
newName	string	John Doe

200 The response contains information about the updated User Account

{
    "message": "Your name has been changed to John Doe"
}

Create an application

POST https://gateway.speechlab.sg/applications

The endpoint is used to create a third-party applications that makes use of Gateway's APIs. Note: If successful, app's secret will only be shown once, be sure to save it somewhere privately.

Headers

Name	Type	Description
Authorization	string	Access Token. Format: Bearer <access token obtained from login>

Request Body

Name	Type	Description
name	string	Application's name

200

{
    "_id": "5f8d581e87bf680b226d3cc1", // App ID
    "name": "Test App",
    "key": "5f8d581e87bf680b226d3cc0", // Key ID (used to get public key to verify JWT token)
    "createdAt": "2020-10-19T09:10:54.482Z",
    "secret": "41d29bb4c52389441c1647764de94493c16a8c42e9529bdaa7502cccc7f111e7" // App secret
}

Get JWT Public Key

GET https://gateway.speechlab.sg/keys/:keyId

This endpoint returns JWT public key, third-party will use this key in order to verify JWT token generated from API gateway.

Path Parameters

Name	Type	Description
keyId	string	Key ID returned after creating application (see above)

200

public key in file