Developer account setup
To access the APIs you will need to create a developer account through the portal.
Simply register for an account and enter some contact details.
Access API Services
Once you are signed in you can request access to our APIs in the API Catalogue.
We currently have two plan options:
The Trial plan.
This is for you to get started and try out the API.
- Request an API key, it will be approved straight away.
- Visit the API documentation to getstarted with the API. The trial plan has a simplified authentication flow so you only need your API key.
Note: The trial plan is limited to 1,000 API calls for 1 month and a concurrency of 1 request per second.
If you are ready to use our API in one of your production applications then you will need to request a custom plan:
- Request an API key for the custom plan in the API catalogue. You will be asked to fill out a form with some information about your use case. Make sure you enter your contact details so we can get in touch.
- We will contact you and discuss a custom quota, concurrency and pament plan for you.
- Once we have agreed on a plan you will be given:
- Your API key, used for tracking your usage.
- A set of oauth2 client credentials. This is a necessary additional layer of security in case your API key get’s compromised. For more information check out the oauth flow section bellow and the postman examples
- You now have everything you need to get started with your custom API plan. You can check out the API documentation for the custom plan in the API catalogue.
Checking API Usage
You can see your API plan details and usage in your developer dashboard –> Here
Oauth2 Authentication Flow
If you are using a custom plan then the API endpoints will be authorized with your API key plus oauth2 access tokens.
Because you may want to store your API key on the client side this key could be compromised and used by someone else. So as an additional layer of security the API will require a valid oauth access token.
Here is the authentication flow with oauth2:
- Your application client side makes a request to your backend server for an access token.
- Your application backend server has your Client ID and Client Secret stored securely. It uses these to request an access token to our oauth2 authentication provider at:
- Our authentication provider validates your client credentials and sends back an access token to your backend server. This token is set to expire after a set time. (The expiry time will be in the token response )
- Your backend server forwards down the access token to your application client side.
- Your application client side uses the access token + your API key to call our API server.
- Our API server validates the access token and API key and returns the requested API resource.
- Your application clientside will have to request new tokens when they expire.
You are responsible for keeping your client credentials safe. Do not check them into version control.
For your convenience, you can use this Postman collection to see how the requests are made in more detail.
In particular the oauth2 token request.
Submitting the audio as a Base64 string
The API requires that you send the audio for pronunciation scoring as a Base64 string.
To try this on your local machine you can use the Base64 CLI tool for your OS on any file that meets the audio requirements:
base64 <your file name> | pbcopy
In your applications, you can use the recommended library for your language. Just search “Base64 encode “
The acceptable audio formats for the API are MP3 and WAV at a sample rate higher or equal to 16kHz