Accurate transcripts of phone conversations

Quickly receive transcripts of audio files.


Quick start

Make sure you’ve read Getting Started.

About

The Contexta speech API is a highly accurate and customizable speech-to-text service that can transcribe audio files to text. Currently it supports Dutch and English, and more languages will follow soon.

The service is asynchronous, which means that you upload the audio in one API call and get a transcriptionId in return while the transcription process is running on the server. By checking the status with the /transcripts/status service - or by providing a callback URL with your create request - you can find out when the transcription is done and download it with the transcripts/show request.

How it works

To get started and test the API from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials in order to authenticate.

 
 

If you use cURL scroll down to see the examples.

Connect to the API

To start testing the API you need to get authorization credentials. Log in to your account and create a developer app on the my apps page. The steps to create a developer app are briefly discussed under 'Support' 🡆 'Frequently Asked Questions'.

Get access token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute the below cURL command to receive an access token.

You can use the same token to make multiple 'API' calls, provided the token is active. If the token expires then you can repeat this step.


curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[SpeechContextaV1]",
    "organization_name": "kpn",
    "developer.email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1530111215949",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "e1bb2b38-af9f-4fbc-b520-86a8f3c262df",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

List decoders

Get a list of possible decoders from Contexta and define the one that fits your use case best.


curl -X GET \
  https://api-prd.kpn.com/communication/contexta/speech-to-text/decoders \
  -H 'authorization: BearerToken access_token'

Create a transcript from an audio recording

Provide an audio file with the conversation to be transcribed. The file must honor the following conditions: File format is .wav.mp3 or .opus (uncompressed files preferred), and minimum bit rate: 32k and sampling rate: 8KHz, encoding: pcm_s16le. Preferred bit rate of 256k and sampling rate of 16KHz. Maximum audio file size: 10MB

Provide the appropriate decoder ID (retreived by GET /decoders), depending on the laguage spoken in the audio file. An optional callback URL can be provided where a notification will be send when the transcription process is finished. An optional JSON metadata object can be provided as well, which is passed through as is to the callback URL (if given) when the transcript is done.


curl -X POST \
  https://api-prd.kpn.com/communication/contexta/speech-to-text/transcripts/create \
  -H 'Authorization: Bearer access_token' \
  -H 'content-type: multipart/form-data; \
  -F callbackurl=http://mysite.com/webhook \
  -F 'data={"message" :"welcome to Contexta speech API"}' \
  -F 'audio=@C:\Users\<username>\Desktop\sample_call.mp3' \
  -F decoder=5b16b7c7fb6fc02bcb8ec28e

Check the transcription process status

You can check the status of the transcription process for a previously uploaded audio file by providing its transcriptId. the request will respond with one of the following: pending, inprogress, ready


curl -X GET \
  https://api-prd.kpn.com/communication/contexta/speech-to-text/transcripts/status/transcriptId \
  -H 'Authorization: Bearer access_token'

Get the transcribed audio as JSON

When ready you can produce a JSON file with the transcript of a previously uploaded audio file.


curl -X GET \
  https://api-prd.kpn.com/communication/contexta/speech-to-text/transcripts/transcriptId \
  -H 'Authorization: Bearer access_token'

Check history of transcriptions

You can check the history of transcription requests and their status by accessing this endpoint. For security reasons, this feature is only available after being approved for production.


curl -X GET \
  https://api-prd.kpn.com/communication/contexta/speech-to-text/transcripts/ \
  -H 'Authorization: Bearer access_token'