Hello, World

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

The examples assume you have these prerequisites:

Step (1): 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 How to Get Your Bearer Token or Understanding Your First Request below.

1
2
3
4
5
export TOKEN= # Insert your VoiceBase Bearer token after TOKEN=

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

You should see a response like this (otherwise, see explanation and/or troubleshooting):

{
  "_links": {
    "self": {
      "href": "/v2-beta/media"
    }
  },
  "media": []
}

Step (2): 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).

1
2
3
4
5
curl https://apis.voicebase.com/v2-beta/media \
  --form media=@hello-world.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": "/v2-beta/media/ef6ed189-e19d-485e-a173-11191eeeeea4"
    }
  },
  "mediaId": "ef6ed189-e19d-485e-a173-11191eeeeea4",
  "status": "accepted",
  "metadata": {}
}

You can poll for status until the processing is done (for production, we recommend using Callbacks).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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/v2-beta/media/${MEDIA_ID}/progress \
      --header "Authorization: Bearer ${TOKEN}" \
      | jq --raw-output .status
  )
  echo "Got status: ${STATUS} for mediaId: ${MEDIA_ID} on $( date )"
done

Step (3): Get your transcript and analytics

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

1
2
3
curl https://apis.voicebase.com/v2-beta/media/${MEDIA_ID} \
  --header "Authorization: Bearer ${TOKEN}" \
  | jq .

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

1
2
3
curl https://apis.voicebase.com/v2-beta/media/${MEDIA_ID}/transcripts/latest \
  --header 'Accept: text/plain' \
  --header "Authorization: Bearer ${TOKEN}"

How to Get Your Bearer Token

First, sign into the Developer Portal.

../_images/Sign-Into-Developer-Portal.png

Click the Bearer Token Management widget in the lower-left of the portal.

../_images/Bearer-Token-Management.png

Click the + New Token button to generate a new Bearer token

../_images/New-Token.png

Click through on Create Token to generate the token.

../_images/Create-Token.png

Save your token by Copying it to the clipboard or downloading it.

../_images/Copy-Token-To-Clipboard.png

Understanding Your First Request

The root URL of the VoiceBase V2 (Beta) API is https://apis.voicebase.com/v2-beta. Every recording you submit for analysis appears in the /media collection. The first request is to GET the /media collection (which will be empty when you first sign up). We pro-actively limit the page size to 10 (?limit=10) to avoid an overwhelming response as the media collection grows.

1
2
3
4
5
export TOKEN= # Insert your VoiceBase Bearer token after TOKEN=

curl https://apis.voicebase.com/v2-beta/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 (see: Troubleshooting if you hit issues):

{
  "_links": {
    "self": {
      "href": "/v2-beta/media"
    }
  },
  "media": []
}

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

The media section the list of media in your account (up to 10 due to the limit parameter). 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.

1
2
3
4
curl https://apis.voicebase.com/v2-beta/media \
  --form media=@hello-world.mp3 \
  --header "Authorization: Bearer ${TOKEN}" \
  | jq

When you add the –form media=@filename.mp3 parameters, curl automatically sets the HTTP method to POST and the Content-Type to multipart/form-data. This is equivalent to the more explicit:

1
2
3
4
5
6
curl https://apis.voicebase.com/v2-beta/media \
  --form media=@hello-world.mp3 \
  --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:

1
2
3
4
5
curl https://apis.voicebase.com/v2-beta/media \
  --form media=@hello-world.mp3 \
  --form 'configuration={"configuration":{}}' \
  --header "Authorization: Bearer ${TOKEN}" \
  | jq

Many of the Developer Guides will address how to use specific options in the configuration attachment to address various Use Cases.

A Quick Note on Tools

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

Troubleshooting