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/transcriberequest 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-b3b26600f813Set a variable with a valid token:
token=your-token-hereUse one of the following commands to automatically redirect to the results link returned as a response:
Output the transcript(s) to
results.zipusing the curl-ooption:curl -sL "https://vcloud.vocitec.com/transcribe/result/$requestid?token=$token" -o results.zipOutput the transcript of a single audio file to
results.jsonusing the curl-ooption.curl -sL "https://vcloud.vocitec.com/transcribe/result/$requestid?token=$token" -o results.jsonNote
The
-Loption is required for curl to redirect.