Quicktate Developer Documentation
The Quicktate API allows you to seemlessly integrate our audio transcription backend into your applications. Now you can leverage our quick turnaround times and professional quality to provide audio transcription services to your customers.
Example uses
- Transcribe your PBX's voicemails into text
- Make your library of audio files searchable by sending them to be transcribed
- Use Quicktate in telephony applications to transcribe calls
- Automatically have surveillance audio transcribed into text
- Anything which requires audio files to be accurately converted to text
Technical Overview
Using our API consists of two steps. The first step is to submit your audio file into our system, along with any metadata you would like to be returned along with the transcription. This will be referred to as "Job Submission". The second step, is our system submitting the results back to you. This will be referred to as the "Result Callback"
The overall process of sucessfully transcribing an audio file is as follows:
- Submit the job into our system, using a Job Submission method of your choice
- Our system assigns a Job ID, which is returned to your application for your tracking purposes
- We transcribe the file into text
- Our servers send your application the results, through a Result Callback method of your choice
You can use the Job ID to check the status of a job at any time.
We currently offer three options for job submissions:
- XML-RPC (preferred method) - an industry standard method of exchanging data between web applications. This is the most reliable and featured way of submitting jobs to Quicktate.
- Email (in development) - email your audio files as attachments to our API email address
- FTP (in development) - Use FTP to upload your audio files, along with any metadata you would like to be returned
All three options require either attached audio data, or a URL for the system to download the audio file from. We currently accept WAV and MP3 formats.
Once you have submitted the audio using one of the above three methods, the file will be transcribed and returned to you using one of the following result callback methods.
We currently offer three options for result callbacks:
- XML-RPC (preferred method) - Our system will submit an XML-RPC request with the results of the transcription to a configurable URL
- HTTP POST - Our system will send POST data with the results of the transcription over HTTP to a URL of your choice
- Email (in development) - We will send the results to an email address of your choice
All three options return the Job ID, the transcribed text, the datetime completed, and any metadata you submitted. The metadata can be used to store any text you want, and is very useful for keeping track of submitted jobs.
Submission: XML-RPC
Methods
job.submit
- user (str) - your username
- key (str) - your 64 character API key, obtain this by contacting our support team
- audiodata (str) - Base 64 encoded audio file (or use audiourl)
- audiourl (str) - URL to download audio file from (or use audiodata)
- filetype (str) - We currently support "wav" or "mp3"
- language_id (int) - 1 for English, 2 for Spanish
- callbackurl (str) - URL for results of transcription to be posted to
- metadata (str) - Block of text you would like to be posted back to you along with the completed job
- callbackmethod (str) - select "XMLRPC", "HTTPPOST", or "EMAIL" (described above)
- callbackdest (str) - If XMLRPC or HTTPPOST, this will be the URL you want the results to be sent to (SSL recommended!). If EMAIL, specify the destination email address.
Returns:
- job_id (int)
job.status
- user (str) - your username
- key (str) - your 64 character API key, obtain this by contacting our support team
- job_id (int) - the value returned when you submitted the job into our system
Returns:
- status (int)
- result (str)
- metadata (str)
- datetime_submitted (str) - MySQL datetime format
- datetime_completed (str) - MySQL datetime format
Callback Method: XML-RPC
To use the XML-RPC callback method, set 'callbackmethod' to 'xml-rpc' when submitting the job. Set 'callbackdest' to the following format:
(domain)|(path)|80
For example, to generate an XML-RPC post to http://api.quicktate.com/xmlrpc on port 80, you would use a callbackdest of 'api.quicktate.com|/xmlrpc|80'.
When the job is complete, the following XML-RPC information will be sent to the method 'job.result'.
job.result
- job_id (int)
- result (str) - text of transcription
- metadata (str) - the metadata you submitted with the job (if any)
- datetime_submitted (str) - MySQL datetime format
- datetime_completed (str) - MySQL datetime format
Callback Method: HTTP POST
The HTTP POST callback will send POST of data to the URL of your choice. Specify the URL you would like the data to be posted to in the 'callbackdest' field when submitting your job. The following variables will be posted in a URL encoding:
- job_id (int)
- result (str) - text of transcription
- metadata (str) - the metadata you submitted with the job (if any)
- datetime_submitted (str) - MySQL datetime format
- datetime_completed (str) - MySQL datetime format
Callback Method: Email
The Email callback method will send an email to the address of your choice once the job is complete. Specify the destination email address in the 'callbackdest' field when submitting the job. The result email will be returned in the following format:
Subject: [job_id (int)]
Body: [result (str)]
----BEGIN-METADATA----
[metadata (str)]
API Questions
If you have any questions regarding implementing the API in your application, feel free to contact our friendly support team at support@quicktate.com