Hello, World
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 under "Understanding Your First Request" below.
bash:
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:
javascript:
{
"_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:
bash:
curl https://apis.voicebase.com/v3/media \
--form 'media=@hello-world.mp3' \
--header "Authorization: Bearer ${TOKEN}" \
| tee media-post.json \
| jq .
Using a remote media URL:
bash:
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.
javascript:
{
"_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>__
bash:
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.
bash:
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.
bash:
curl https://apis.voicebase.com/v3/media/${MEDIA_ID}/transcript/text \
--header 'Accept: text/plain' \
--header "Authorization: Bearer ${TOKEN}"
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.
bash:
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:
javascript:
{
"_links": {
"self": {
"href": "/v3/media"
}
},
"media": []
}
All successful responses from the API will include a _links section with HAL metadata that helps navigate the API.
javascript:
{
"_links": { }
}
The media section the list of media in your account. If you have previously uploaded media, it will appear in the list.
javascript:
{
"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 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:
bash:
curl https://apis.voicebase.com/v3/media \
--form media=@hello-world.mp3 \
--header "Authorization: Bearer ${TOKEN}" \
| jq
bash:
curl https://apis.voicebase.com/v3/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:
bash:
curl https://apis.voicebase.com/v3/media \
--form media=@hello-world.mp3 \
--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.
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/