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 allows you to login and get an account token

Request Body

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

200 Login successfully

{
    "accessToken": "Your token"
}

404 Email or password is incorrect

{
    "statusCode": 401,
    "message": "Unauthorized"
}

Register

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

This endpoint allows you to register an account

Request Body

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

200 Register successfully. You should check your inbox for verification email

{
    "role": "user",
    "isVerified": false,
    "_id": "user_id",
    "email": "user_email",
    "createdAt": "created date",
    "message": "Please check your inbox for verification email"
}

400 Your email or password is not valid

    "statusCode": 400,
    "message": [
        "password must be longer than or equal to 6 characters",
        "password should not be empty",
        "password must be a string"
    ],
    "error": "Bad Request"
}

422 Duplicate email

{
    "statusCode": 422,
    "message": "Duplicate record!"
}

After successfully register your account, there will be an email sent to your inbox 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. Format: Bearer <your token after login>

Request Body

Name	Type	Description
file	object	File Object
lang	string	must be one of: ['english', 'mandarin', 'malay', 'english-mandarin', 'english-malay']
queue	string	Queue where your job will be running in
audioType	string	One of: ['closetalk', 'telephony']
audioTrack	string	One of: ['single', 'multi']
webhook	string	API endpoint to receive update when your speech is ready (good way to get update of a speech, see below). Eg: http://your-api.com/status

200

{
    "result": null,
    "status": "created",
    "formats": [
        "stm",
        "srt",
        "TextGrid"
    ],
    "sampling": "16khz",
    "lang": "english",
    "name": "Note",
    "_id": "5f11c797b6d18b0029b60975", // Note this ID
    "queue": "normal",
    "createdAt": "2020-07-17T15:45:27.882Z"
}

403 This status can be one one: - Your email hasn't been verified. Please check your inbox for verification email - You're not allowed to submit job to this queue - Your account has been blocked. Please contact our administration for further detail.

{
    "statusCode": 403,
    "message": "You haven't verify your email yet. Please check your inbox.",
    "error": "Forbidden"
}

404 No speech found with provided ID

{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}

Note: If you can provide audioType and audioTrack that best describe your audio file, we'll try to use our best-fit model to give you better result.

After request successfully, in response returned, you'll see a field name _id, this is ID of your speech, we also call it SpeechID. Notice this for further requests.

About webhook: an audio may take long time to decode (depends on its duration, type,...), and the processing time is not exact, not same even if you submit 2 identical jobs. So instead of keep calling us to get the status, You can provide your HTTP endpoint in webhook field and we'll send your audio's status, and when status is done you just need to call our endpoint to download your transcription

About queue: a queue is where your job will be running in, each queue will have some workers to pick up your job and process, by default your job will be submitted to normal queue and this queue is shared among others, because of that sometimes your job will have to be queued until our workers available. If you want to have dedicated queue to not share with others, contact our support to get in detail.

Get job status

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

This api is to retrieve speech's status. If you mean to call this api many times to get speech's status, consider passing webhook when submitting your job as described in above section

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access token. Format: Bearer <your token after 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"
    }
}

403 This status can be one of: - Your haven't verified your account - Your account is blocked

{
    "statusCode": 403,
    "message": "You haven't verify your email yet. Please check your inbox.",
    "error": "Forbidden"
}

404 No speech found with provided ID

{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}

Get transcription (Deprecated)

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

This API is used to download transcription when speech's status is done

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access token. Format: Bearer <your token after login>

200

Return transcription downloadable file

403 This status can be one of: - You haven't verified your account - Your account has been blocked

{
    "statusCode": 403,
    "message": "You haven't verify your email yet. Please check your inbox.",
    "error": "Forbidden"
}

404 No speech found with provided ID

{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}

Get transcription (New)

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

This API returns transcription when speech's status is done

Path Parameters

Name	Type	Description
id	string	Speech's ID

Headers

Name	Type	Description
Authorization	string	Access token. Format: Bearer <your token>

200

{
    url: "a downloadable link"
}

403 This can happen when: - You account hasn't been verified - Your account has been blocked

{
    "statusCode": 403,
    "message": "You haven't verify your email yet. Please check your inbox.",
    "error": "Forbidden"
}

404 No speech found with provided ID

{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}

Change account's password

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

Request Body

Name	Type	Description
email	string	Your email
currentPassword	string	Your current password
newPassword	string	New Password
confirmNewPassword	string	Confirm new password

200

{
    "message": "Password changed successfully"
}

400 Your body parameters are not valid

{
    "statusCode": 400,
    "message": [
        "email must be longer than or equal to 6 characters",
        "email must be an email"
    ],
    "error": "Bad Request"
}

404 No account found with provided email

{
    "statusCode": 404,
    "message": "Account not found",
    "error": "Not Found"
}

Forgot account's password

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

This API is used to reset account password

Request Body

Name	Type	Description
email	string	Account's email

200 Request to reset password sent successfully, check your inbox to get reset code

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

400 Your body params are invalid

{
    "statusCode": 400,
    "message": [
        "email must be longer than or equal to 6 characters",
        "email must be an email"
    ],
    "error": "Bad Request"
}

404 No account found with provided email

{
    "statusCode": 404,
    "message": "Email not found",
    "error": "Not Found"
}

After sending this API, there's an email will be sent to your email address which contains a code used to reset password (see the API below)

Reset password

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

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 Successfully reset your account's password

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

400 Your body params are invalid

{
    "statusCode": 400,
    "message": [
        "email must be longer than or equal to 6 characters",
        "email must be an email"
    ],
    "error": "Bad Request"
}

404 No account found with provided email or your code are invalid

{
    "statusCode": 404,
    "message": "Email not found or code is incorrect",
    "error": "Not Found"
}

406 Your newPassword and confirmNewPassword are not matched

{
    "statusCode": 406,
    "message": "New passwords are not matched each other",
    "error": "Not Acceptable"
}

Send verification email

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

Verification email is sent right after account registration, and will be valid for 12 hours. This api endpoint is used in case you want to send new verification email

Headers

Name	Type	Description
Authorization	string	Access token: Format: Bearer <your_token>

200

{
    "message": "Please check your inbox for verification email"
}

422 Your account has been verified before

{
    "statusCode": 422,
    "message": "Account has been verified before"
}

Create an application

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

This endpoint is used to create a third-party application that make uses of Gateway APIs. Note: if success, app secret will only be shown once, be sure to save it somewhere privately

Headers

Name	Type	Description
Authorization	string	Access Token: Format: Bearer <your_token>

Request Body

Name	Type	Description
name	string	Your app'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 endpoints return 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