Documentation for Voicecup.com API

About this API
Search API parameters
Response format
Playback API
API key
Requests quota
Standalone demo
Attribution
Sites which use this API

About this API

This REST API queries an inputted word and returns an audio file which contains the word, along with the start and end positions in seconds of the media fragment where the word is found. This is done by sourcing from subtitles for movies in different languages, allowing one to retrieve pronunciation examples in real speech.
The files returned by this API can be used in an <audio> HTML5 tag.
LIVE DEMO.

Search API parameters

Sample API request with a minimal set of parameters:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father

Sample API request asking to retrieve only video and audio fragments in English:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father&lang=eng

If the language is not defined, all available content will be queried.

API request parameters:

Parameter	Default	Description
key	-	- Your API key. Mandatory parameter.
q	-	- text to search. Mandatory parameter if query_type != match_all.
lang	-	- media language to search for.
format	json	- output format. Possible values: json, jsonp.
callback	-	- callback name to be used in JSONP output.
length_min	1	- minimal subtitle length in characters.
length_max	300	- maximum subtitle length in characters.
duration_min	1	- minimal audio fragment length (in seconds), corresponding to the subtitle found.
duration_max	100	- maximum audio fragment length (in seconds), corresponding to the subtitle found.
from	0	- order number of the record to start results output with (to be used for pagination).
size	10	- maxumum number of results in a response (to be used for pagination). Minimal value: 1, maximum value: 100.
random_sort	0	- set to 1 to return results in a random order.
query_type	0	- if set to match_all, all records will be returned, regardless the value of q parameter.

Request example with all parameters: This query tells the API to search for audio and video fragments from movies in English containing the word father. Return results in JSONP format, 15 records, starting from the 10-th one. Search for subtitles not shorter than 15 and not longer than 50 characters, audio duration from 5 to 25 seconds.

Response format

The server returns the results in JSON or JSONP format (depending on the value of format field).
In case of successful request completion the res field will contain ok, otherwise - error.
In case of an error, the errors field will contain the list of errors.

Parameters returned in the server response:

res	oк in case of successful request completion, error otherwise
errors	- list of errors (if "res" is "error")
quota_daily	- daily requests quota for a given API key
quota_daily_used	- quota used today
lang	- video and audio language where the search was performed
time	- query completion time in milliseconds
query	- text to search for
hits_total	- total number of subtitles (video and audio fragments) found
hits	Contains retrieved audio and video fragments info as records with the following structure: id - record ID filename_audio - audio file name where the text being searched is pronounced title - media title lang - audio track language start_precise - speech start time (in seconds), 1 millisecond precision end_precise - speech end time (in seconds), 1 millisecond precision duration_precise - speech duration (in seconds), 1 millisecond precision start - speech start time (in seconds), 1 second precision end - speech end time (in seconds), 1 second precision duration - speech duration (in seconds), 1 second precision length - pronounced text length (in characters) body - found text highlight - found text with selected searched fragment
length_min length_max duration_min duration_max from size	- the values of these parameters are identical to the ones transmitted in the request

Example of a successfully completed request:

Example of a response with an error message:

Play API

Using the information provided by the search API described above, embed the audio fragment in the following way:


The subs_id parameter is optional, but you are advised to include it. It will help our algorithms to provide you with more detailed statistics on your account usage, e.g. which audio fragments your users play back.

The /play API endpoint returns an audio file of a specified MIME type on success and a JSON-formatted response on error.

The maximum duration of an audio fragment that can be retrieved is 15 seconds.

API key

The API key is available in your account upon registration.

You can change your API key at any time.

Requests quota

We provide a free quota of 100 daily audio playbacks (/play endpoint). If this limit is exceeded, you will see a "quota exceeded" error message in a JSON-formatted server response.

API calls for search do not affect your quota. You may make as many search API calls as you need.

You can see in your account how much time is left before the quota is restored.

If you need more quota, please contact us here.

Standalone demo

Please find a standalone demo here.

Attribution

You must provide a link to www.voicecup.com on all pages where the content obtained using this API is displayed.

Examples of links:
Pronunciation examples by Voicecup.com
Примеры произношений от Voicecup.com
Ejemplos de pronunciación por Voicecup.com

Sites where Voicecup.com API is used

On these sites you can see how this API is used in production:

www.diccionario.ru - Spanish-Russian and Russian-Spanish online dictionary
www.diclib.com - various online dictionaries