V‑Cloud REST API Overview
The V‑Cloud API is a collection of REST web services that can be accessed by any programming language capable of performing HTTP POST and GET calls. The endpoint for this service is available at https://vcloud.vocitec.com. Additional endpoints that isolate processing to particular regions (for example, the European Union) are available on request.
Available methods and mandatory parameters for the V‑Cloud API are discussed in Querying V‑Cloud Status and Transcribing Audio Files. V‑Cloud Transcription Parameters has a complete list of all the available V‑Cloud parameters.
Note
All audio file examples use the WAV audio file format , identified by the .wav filename extension. MP3 files are not supported by V‑Cloud unless transcode=true. Refer to Adjusting for Different Types of Input for more information on the transcode parameter.
Web Service Overview
The V‑Cloud API is a collection of REST web services that can be accessed by any programming language capable of performing HTTP POST and GET calls.
The V‑Cloud API utilizes web services to receive requests and return results. The following image illustrates some web service interactions between your system and the V‑Cloud API.
 |
Your machine POSTs a single audio file or a zip file containing one or more audio files that you want to transcribe. For each successful POST you will receive a requestid.
If you have a callback endpoint set up, you will receive results at that endpoint as soon as V‑Cloud processing of your audio file is finished. By default, you will always receive a zip file of the results if you uploaded a zip file.
Tip
The callback mechanism is the recommended way to receive transcription results, since it provides the shortest turnaround time. Because no subsequent request is required to retrieve results, using callbacks is the most efficient way to use V‑Cloud.
Uploading and downloading zip files is recommended to minimize network bandwidth consumption.
You may also use the requestid in a GET call which will return a secure URL for you to download the results. You will only receive a URL if the files from that request are done processing.
Tip
Uploading and downloading zip files is recommended to minimize network bandwidth consumption. V‑Cloud has a limit of 250MB per /transcribe POST, which allows for more than two hours of uncompressed 16bit 8KHz 2-channel PCM audio. Voci recommends compressing audio with zip to reduce file size and network bandwidth requirements. Using zip for PCM audio typically allows call lengths of four hours or more.
Other audio formats will have other practical maximum call lengths, typically much longer. Using zip for upload results in the ASR result being zip by default. If you'd like to use a simpler response format while still saving bandwidth, use the 'outzip=false' request parameter to ensure non-compressed API output (for single files).
If not using callbacks, users should also consider imposing a limit on the number of GET calls that are being made in parallel to the V‑Cloud API. A recommended limit is 10-20 simultaneous calls. This helps smooth network load by minimizing the number of network connections that must be open simultaneously.