Obtaining Transcription Results
Using a callback to automatically return results from V‑Cloud is the recommended way of using V‑Cloud, since it provides the shortest turnaround time between issuing a /transcribe
request and receiving the results. Results return as soon as transcription completes and no subsequent request is required to retrieve the results. The callback mechanism is the most efficient way to use V‑Cloud.
By default, the results produced by V‑Cloud differ based on whether you submitted a single audio file or a zip file containing one or more audio files.
If you submit a non-zipped audio file, the result is a JSON transcript of that audio file (unless you specified other options).
If you submit one or more audio files contained in a zip file, the result is a zip file that contains the transcript(s) of the audio files in the zip archive (unless you specified other options).
Tip
Uploading and downloading zip files is recommended to minimize network bandwidth consumption.
A requestid
is returned in response to any transcription request for tracking or retrieval (if no callback is specified or the callback fails).
Using the Recommended Callback Flow
If you specify a callback, results are sent to the specified endpoint as soon as transcription completes. The callback server must be able to receive multipart requests containing the results and the associated requestid
. For example, the following request simulates the data that would be sent from V‑Cloud to your callback server.
curl -F "file=@samples.zip;type=application/zip" \
-F requestid=700e7496-4fce-4963-aa7b-b3b26600f813 \
https://hostname:port/endpoint
The example above demonstrates the two required form-data fields of the multipart request that the callback server needs to handle. Make sure that your callback server correctly returns success (HTTP code 200) when these two fields are received. Results are automatically deleted from V‑Cloud once the callback succeeds. Refer to Receiving Transcription Results for more information on the data that V‑Cloud sends to a callback server.
Note
Using the /transcribe/result
method in conjunction with a callback is not recommended because you will only be able to retrieve results if the callback has failed.
The following request instructs V‑Cloud to transcribe sample7.wav
and send the results to the specified callback
address:
curl -F callback=https://hostname:port/endpoint \
-F "file=@sample7.wav;type=audio/x-wav" \
-F token=your-token-here \
https://vcloud.vocitec.com/transcribe
Manually Retrieving Transcription Results
As an alternative to using the recommended callback flow, you can retrieve results manually from the /transcribe/result
endpoint. It requires a token and requestid
to return a secure URL from which you can download the results. The URL that is returned is valid for 1 hour. After 1 hour, you can still retrieve the results, but you must call /transcribe/result
again to get an updated URL.
Note
By default, results created by a non-callback /transcribe
request are preserved on V‑Cloud for 24 hours. To determine how long results will be preserved, check the GET
header of the URL returned by /transcribe/result
.
/transcribe/result
EndpointDescription:
The /transcribe/result
endpoint enables manual retrieval of transcription results. To manually retrieve results, submit a GET
request containing a valid authorization token and requestid
as query parameters:
token
(required) — String used to authenticate and authorize V‑Cloud requests. All requests made with your token are tied to your account. Contact support@vocitec.com immediately if your token is compromised or lost.Example token: 123e4567e89b12d3a456426655440000
requestid
(required) — String returned from a successful/transcribe
request to access the results.
Examples:
The following URL calls the /transcribe/result
endpoint:
https://vcloud.vocitec.com/transcribe/result?token=123e4567e89b12d3a456426655440000
&requestid=700e7496-4fce-4963-aa7b-b3b26600f813
Response:
"https://vcloud-download.s3.amazonaws.com/a7406862-9811-4c81-a896-81abd4705a4f-zip?X-Amz-Security-Token=FQ...3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180130T193649Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAIDW6XGGVYD5XLVFA%2F20180130%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=0a2562c15863a909490e44f7968a281489bb5b5b294c5bd93d1ad5701e0fd68a"
The response is a secure link to the results from the file(s) submitted to the /transcribe
endpoint. The link will contain a single text or JSON file if a single audio file was submitted in the initial /transcribe
request. If a zip file containing multiple audio files was submitted, the results link will contain multiple text or JSON transcripts in a zip file.
The following steps detail how to retrieve results on the command-line with an automatic redirect to the secure link containing the results:
Set a variable with a valid
requestid
:requestid=700e7496-4fce-4963-aa7b-b3b26600f813
Set a variable with a valid token:
token=your-token-here
Use one of the following commands to automatically redirect to the results link returned as a response:
Output the transcript(s) to
results.zip
using the curl-o
option:curl -sL "https://vcloud.vocitec.com/transcribe/result/$requestid?token=$token" -o results.zip
Output the transcript of a single audio file to
results.json
using the curl-o
option.curl -sL "https://vcloud.vocitec.com/transcribe/result/$requestid?token=$token" -o results.json
Note
The
-L
option is required for curl to redirect.