Contexta360

Speech To Text - Contexta360

Contexta360

Gain insight into phone conversations with your customers

Instant, accurate transcripts of phone conversations

  • Communication

API reference on SwaggerHub API reference on Postman

Introduction

The Speech To Text 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.

Conceptual model

Conceptual model

Definitions

Decoder

A decoder in this context is speech analyser that is optimised to reckognise expected circumstances like the languages used or sometimes dialect used.

Callback (WebHook)

A Callback or WebHook is a HTTP POST callback implemented by you, that can be called by another system when an event is triggered on that system to notify you. You will need to make the address of your webhook/callback known on the other system to make it work.

API workflow

API workflow

Features and constraints

Features

  • Recognition of spoken text in Dutch and English (more to come).
  • Callback support to let the sender know that the decoding has been finished.
  • Supports Transcription history.

Constraints

  • Supported file formats are: .wav, .mp3 or .opus.
  • Maximum audio file size is 10MB.
  • /transcripts request is only available in production.

Getting started

Setting up your third party accounts

Make sure you have a registered account on the API Store and created an application on the portal, to receive the associated client ID and secret. These are neccessary to request an access token. You will receive these after your app is approved on te API Store.

Authentication

OAuth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: those tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end-user). We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information.

Get Access Token

Copy your app's credentials (Consumer Key & Consumer Secret) to be used in the Authentication requests below.

Authentication in SwaggerHub:

  1. Upon loading completed within SwaggerHub, look top right for the Authorize button and click it.
  2. In the form, fill in client_id and client_secret fields, using your app's credentials.
  3. Click Authorize.
  4. Now you are authorized to issue the requests provided.

Authentication in Postman:

  1. Select Get Access Token from the collection.
  2. Make sure the right Environment corresponding to the API is selected.
  3. Edit the environment variables client_id and client_secret, using your app's credentials.
  4. Check the response code and message.
  5. Press the Send button to get the access token.
  6. Now you are authorized to issue the other requests in the collection.

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

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

How to...

List decoders

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

SwaggerHub:

  1. Select GET /decoders.
  2. Click Try it out.
  3. Click Execute.
  4. Check the response code and message.

Postman:

  1. Select (GET) /decoders.
  2. Click Send.
  3. Check the response code and message.

Result example:

{
  "data": {
    "decoders": [
      {
        "tag": "PUBLIC",
        "default": false,
        "_id": "5af597e9f36d280745034405",
        "description": "Standard Contexta models for English transcription purposes",
        "lang": "en",
        "title": "Contexta Standard English"
      },
      {
        "tag": "PUBLIC",
        "default": false,
        "_id": "5b16b7c7fb6fc02bcb8ec28e",
        "description": "Standard Contexta models for generic transcription purposes",
        "lang": "nl",
        "title": "Contexta Standard Dutch"
      },
      {
        "tag": "PUBLIC",
        "default": true,
        "_id": "5af57b13f36d280745033547",
        "description": "Enhanced Contexta models for phone-related transcription purposes",
        "lang": "nl",
        "title": "Contexta Enhanced Dutch"
      }
    ]
  }
}

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)
  • Minimum bit rate: 32k
  • 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 language 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.

SwaggerHub:

  1. Select POST /transcripts/create.
  2. Click Try it out.
  3. Edit the parameters by filling out audio by providing an audio file. Other parameters are optional, for example callbackurl to provide a callback, or decoder to force a decoder _id.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) /create.
  2. Click the Params section of the request and provide values for the audio key. Other keys are optional, for example callbackurl to provide a callback, or decoder to force a decoder _id.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
  "data": {
    "transcriptId": "5c9b99fd4d1c2752***"
  }
}

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.

SwaggerHub:

  1. Select GET /transcripts/status/{transcriptId}.
  2. Click Try it out.
  3. Edit the parameters by filling out transcriptId by providing the transcript id, obtained from the result of a /create request.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Upon a /create request, the resulting transcriptId should automatically reflect to the environment variable with the name contexta_transcriptId.
  2. This request assumes that the contexta_transcriptId was filled. Please check that it was.
  3. Select (GET) /status/{transcriptId}.
  4. Click Send.
  5. Check the response code and message.

Result example:

{
  "data": {
    "transcriptId": "5c9b99fd4d1c2752***",
    "status": "DONE"
  }
}

Get the transcribed audio as JSON

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

SwaggerHub:

  1. This request is not supported for SwaggerHub.

Postman:

  1. Upon a /create request, the resulting transcriptId should automatically reflect to the environment variable with the name contexta_transcriptId.
  2. This request assumes that the contexta_transcriptId was filled. Please check that it was.
  3. Select (GET) /transcripts/{transcriptId}.
  4. Click Send.
  5. Check the response code and message.

Result example:

{
  "name":"3b23f5ca295d09752fdef***",
  "overall_conf":"0.86",
  "path":"3b23f5ca295d09752fdef***.wav",
  "word_count":"22",
  "SpeakerList":
    [
      {"spkid":"spk1"},
    ],
  "SegmentList":
    [
      {"spkid":"spk1","question":"False","words":
        [
          {"text":"okay","conf":"0.87","dur":"0.42","stime":"0.70"},
          {"text":"we're","conf":"0.97","dur":"0.24","stime":"1.12"},
          {"text":"trying","conf":"1.00","dur":"0.33","stime":"1.36"},
          {"text":"this","conf":"0.99","dur":"0.18","stime":"1.69"},
          {"text":"for","conf":"0.99","dur":"0.18","stime":"1.90"},
          {"text":"a","conf":"0.99","dur":"0.21","stime":"2.08"},
          {"text":"second","conf":"1.00","dur":"0.39","stime":"2.32"},
          {"text":"time","conf":"1.00","dur":"0.54","stime":"2.74"},
          {"text":"to","conf":"1.00","dur":"0.27","stime":"3.31"},
          {"text":"test","conf":"1.00","dur":"0.54","stime":"3.61"},
          ...
        ]
      }
    ]
}

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.

SwaggerHub:

  1. Select GET /transcripts.
  2. Click Try it out.
  3. Click Execute.
  4. Check the response code and message.

Postman:

  1. Select (GET) /transcripts.
  2. Click Send.
  3. Check the response code and message.

Result example:

[
  {
    "_id": "string",
    "duration": 0,
    "numSpeakers": 0,
    "decoder": {
      "_id": "string",
      "title": "string"
    },
    "callbackurl": "string",
    "progressNotifications": "string",
    "data": "string",
    "originalName": "string",
    "status": "PENDING",
    "created_at": "string"
  }
]

Return codes

Code   Description
200   Success
201   Created
202   Accepted
302   Found. Link in location header
400   Bad request
401   Unauthorized
403   Forbidden
404   Not found
405   Method not allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable

API versions

Version   Description
1.0   Initial version