Reference for the /request API
If you have submitted audio files for processing using V‑Spark or submitted zip files that contain audio files and optional metadata through the /transcribe API method that is described in Reference for the /transcribe API, the /request API method enables you to retrieve overall status information, short and long status/summary information in JSON format, and various results of transcribing and analyzing those audio files. The /request API is typically only directly used when you want to embed result retrieval in applications and you therefore cannot use the V‑Spark GUI and its callback server mechanism.
Important
Before you can begin interacting with V‑Spark via the REST API you must create a Folder using the V‑Spark GUI. Each Folder has associated configuration information such as the language model to use for transcription and the names of metadata fields available for filtering. See the V‑Spark Quickstart Guide and the V‑Spark Management Guide for more information. These documents are available under the Help pulldown immediately after logging into the V‑Spark GUI.
Synopsis
http://SERVER/request/ORG_SHORT/VERB?requestid=REQUESTID&token=AUTH_TOKEN
Variables used in this example command are the following:
- SERVER
The name or IP address of the computer system on which V‑Spark is installed
- ORG_SHORT
The short name of the organization that you are using. Finding that information was discussed and shown in /transcribe API Reference.
- VERB
The action that you want the
/requestAPI to perform. These verbs and the data that they return are described in the next section (DESCRIPTION).- REQUESTID
The unique identifier for the request about which you want to retrieve results or status information
- AUTH_TOKEN
The authorization token that you are using to retrieve information. Locating an authorization token for the company associated with the folder that you are uploading to is shown in V‑Spark API Permission Requirements.
Description
The /request API enables you to retrieve status information and converted content for files that you have submitted for transcription.
The items in the rest of this section refer to retrieving status information or transcription results from both zip and audio files that have been submitted for transcription. Remember that while both the /transcribe API and V‑Spark enable you to submit audio and metadata files individually, only files that have been encapsulated into a single zip file and uploaded at the same time will be associated properly.
The /request method takes the following verbs to identify the type of information that you are attempting to retrieve based on a requestid:
- status
Possible return values for this verb are the following:
- analyzing
The zip or audio file associated with the specified
requestidhas been received and is in the process of being transcribed and analyzed by V‑Spark- done
Transcription of all of the audio files in the zip or audio file associated with the specified
requestidhas completed- error
No results will ever be available. Check the contents of the zip or audio file that is associated with the specified
requestidto verify that it contains valid audio files.- received
The zip or audio file associated with the specified
requestidhas been received and the audio file(s) that it contains are in the process of being transcribed
- summary
Returns a short response in JSON format that contains the following information about the request that was identified by the specified
requestid:a
time_submittimestamp which identifies the time that the request was submitteda
time_completetimestamp which identifies the time that analyzing the contents of the zip or audio file was completedcounts of the following categories:
number of audio files that were submitted in the zip or audio file that is associated with the specified
requestidnumber of audio files that were successfully processed in the zip or audio file that is associated with the specified
requestidnumber of audio files that were successfully analyzed in the zip or audio file that is associated with the specified
requestidnumber of audio files in the zip or audio file that is associated with the specified
requestidthat generated an error when being processed or analyzed
Note
Count information is not provided for fields that are NULL.
status: the overall status of handling the zip or audio file associated with the request that is associated with the specifiedrequestid. This is the same value as returned by thestatusverb, with the same list of possible values.
- details
Returns a long response in JSON format that contains:
the information provided by the
summaryverb for the zip or audio file that was uploaded under the specifiedrequestida
filedetailssection that provides afullfilenameand the same information for each file that was part of the request that was identified by the specifiedrequestid:
- result
A zip file containing different types of data that is associated with the transcription of the zip or audio file that was uploaded under the specified
requestid. Optional Boolean parameters identify the type of data that is contained in this zip file:- json
Include the complete transcription information (transcribed text, emotion, sentiment, and so on) in JSON format for each audio file. By default, this option is "on" ("1").
- mp3
Include the mp3 version of each audio file. By default, this option is "off" ("0").
- txt
Include a text file containing the transcription of each audio file. By default, this option is "off" ("0").
If the
/requestmethod'sresultverb is called with all output formats disabled, the API call will return a 404 and the message "No file types were specified".
Content Types
statusverb returns plain text data with the "text/html" MIME typesummaryverb returns JSON-formatted data with the "application/json" MIME typedetailsverb returns JSON-formatted data with the "application/json" MIME typeresultverb returns a zip file with the "application/zip" MIME typeErrors will be returned with the "text/html" MIME type