Hello, World

This Quickstart tutorial gets you up and running with your first transcription and speech analytics.

The examples assume you have these prerequisites:

Your Bearer token
jq for working with JSON (see: :ref:A Quick Note on Tools <tools> for details)
curl (comes with most Linux systems, see: :ref:A Quick Note on Tools <tools> for details)

How to Get Your Bearer Token

Sign into your VoiceBase account.
Go to Settings/Bearer Tokens and click Add Bearer Token.

Save your token in a secure location; it won't be visible in your account after its initial creation.

Verify your Bearer Token and tools are working

Start by verifying your Bearer token is working by running the following from a command prompt. Please remember to insert your Bearer token after TOKEN= in the first line of the example. You can also find more detailed instructions on Understanding Your First Request below.

export TOKEN= # Insert your VoiceBase Bearer token after TOKEN=

  curl https://apis.voicebase.com/v3/media \
    --header "Authorization: Bearer TOKEN" \
    | jq

You should see a response like this:

{
    "_links": {
      "self": {
        "href": "/v3/media"
      }
    },
    "media": []
  }

Upload a media file for transcription and analysis

To upload a recording for transcription and analysis, POST to /media with the recording as an attachment named media (you can also provide a URL to your recording instead using the form field 'mediaUrl'. Note that a 2 minute timeout is recommended when POSTing media URLs.)

Note: When uploading a batch files, we recommend sending an average of 250-300 minutes per minute or ~50 files per minute on a estimated average of 5 minutes per call.

Using local media:

curl https://apis.voicebase.com/v3/media \
    --form '[email protected]' \
    --header "Authorization: Bearer ${TOKEN}" \
    | tee media-post.json \
    | jq .

Using a remote media URL:

curl https://apis.voicebase.com/v3/media \
    --form 'mediaUrl=http://myServer.com/mediaFile.mp3' \
    --header "Authorization: Bearer ${TOKEN}" \
    | tee media-post.json \
    | jq .

The response includes a mediaId (assigned by the API) and a status of accepted.

{
    "_links": {
      "self": {
        "href": "/v3/media/10827f19-7574-4b54-bf9d-9387999eb5ec"
      },
      "progress": {
        "href": "/v3/media/10827f19-7574-4b54-bf9d-9387999eb5ec/progress"
      },
      "metadata": {
        "href": "/v3/media/10827f19-7574-4b54-bf9d-9387999eb5ec/metadata"
      }
    },
    "mediaId": "10827f19-7574-4b54-bf9d-9387999eb5ec",
    "status": "accepted",
    "dateCreated": "2021-04-22T18:23:02Z",
    "dateFinished": "2021-04-22T18:23:58Z",
    "mediaContentType": "audio/mp3",
    "length": 10031,
    "metadata": {}
  }

You can poll for status until the processing is done (for production, we recommend using Callbacks <callbacks.html>__).

export MEDIA_ID=$( cat media-post.json | jq --raw-output .mediaId )
  export STATUS=$( cat media-post.json | jq --raw-output .status )

  while [[ ${STATUS} != 'finished' && ${STATUS} != 'failed' ]]; do
    sleep 1
    STATUS=$(
      curl https://apis.voicebase.com/v3/media/${MEDIA_ID}/progress \
        --header "Authorization: Bearer ${TOKEN}" \
        | jq --raw-output .progress.status
    )
    echo "Got status: ${STATUS} for mediaId: ${MEDIA_ID} on $( date )"
  done

Get your transcript and analytics

You can retrieve the JSON version of the transcript and all analytics with a simple API call.

curl https://apis.voicebase.com/v3/media/${MEDIA_ID}/transcript \
    --header "Authorization: Bearer ${TOKEN}" \
    | jq .

You can also retrieve a plain-text version using transcript/text and the Accept HTTP header.

curl https://apis.voicebase.com/v3/media/${MEDIA_ID}/transcript/text \
    --header 'Accept: text/plain' \
    --header "Authorization: Bearer ${TOKEN}"

.. _understanding_step1:

Understanding Your First Request

The root URL of the VoiceBase V3 API is https://apis.voicebase.com/v3. Every recording you submit for analysis appears in the /media collection and is viewable in the 'Media Browser' tab. The first request is to GET the /media collection (which will be empty when you first sign up). Pagination default limit is set to 100.

export TOKEN= # Insert your VoiceBase Bearer token after TOKEN=

  curl https://apis.voicebase.com/v3/media?limit=10 \
    --header "Authorization: Bearer ${TOKEN:?'(hint: insert your token after export TOKEN=)'}" \
    | jq

If you're running this for the first time, the API returns:

{
    "_links": {
      "self": {
        "href": "/v3/media"
      }
    },
    "media": []
  }

All successful responses from the API will include an _links section with HAL_ metadata that helps navigate the API.

{
    "_links": { }
  }

The media section the list of media in your account. If you have previously uploaded media, it will appear in the list.

{
    "media": []
  }

Understanding Your First Upload

The next step is to upload a recording to the API for transcription and analysis, but making a POST to /media, with the recording as an attachment named media.

When you add the --form [email protected] parameters, curl automatically sets the HTTP method to POST and the Content-Type to multipart/form-data. This is equivalent to the more explicit:

curl https://apis.voicebase.com/v3/media \
    --form [email protected] \
    --header "Authorization: Bearer ${TOKEN}" \
    | jq

curl https://apis.voicebase.com/v3/media \
    --form [email protected] \
    --header "Authorization: Bearer ${TOKEN}" \
    --request POST \
    --header "Content-Type: multipart/form-data" \
    | jq

Finally, many operations will rely on providing a configuration JSON attachment with additional processing instructions. Omitting the attachment is equivalent to including the following default configuration:

curl https://apis.voicebase.com/v3/media \
    --form [email protected] \
    --form configuration='{}' \
    --header "Authorization: Bearer ${TOKEN}" \
    | jq

The 'How-to' guides in this documentation show configurations for each feature of the VoiceBase platform, including an overall sample configuration.

.. _tools:

A Quick Note on Tools

curl: The examples in this documentation make use of curl_ for making HTTP requests to the API.
jq: The jq_ tool helps parse JSON responses and work with JSON data.

.. _curl: https://curl.haxx.se/docs/manpage.html
.. _jq: http://stedolan.github.io/jq/