Sign up

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:
ParameterDefaultDescription
key- - Your API key. Mandatory parameter.
q- - text to search. Mandatory parameter if query_type != match_all.
lang- - media language to search for.
formatjson - output format. Possible values: json, jsonp.
callback- - callback name to be used in JSONP output.
length_min1 - minimal subtitle length in characters.
length_max300 - maximum subtitle length in characters.
duration_min1 - minimal audio fragment length (in seconds), corresponding to the subtitle found.
duration_max100 - maximum audio fragment length (in seconds), corresponding to the subtitle found.
from0 - order number of the record to start results output with (to be used for pagination).
size10 - maxumum number of results in a response (to be used for pagination). Minimal value: 1, maximum value: 100.
random_sort0 - set to 1 to return results in a random order.
query_type0 - if set to match_all, all records will be returned, regardless the value of q parameter.

Request example with all parameters:
http://voicecup.com/api?q=father&key=YOUR_API_KEY&l=en&from=10&size=15&length_min=15&length_max=50&duration_min=5&duration_max=25&format=jsonp
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 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:
{
"res":"ok",
"from":0,
"size":10,
"length_min":15,
"length_max":50,
"duration_min":5,
"duration_max":25,
"quota_daily_used":217,
"quota_daily":100,
"lang":"esp",
"time":389",
"query":"mando,
"hits_total":1,
   "hits":[

{
"id":"55a8c5ec312f9108fc57731c",
"filename_audio":"snL4Nqla_2_esp",
"title":"Flight of the Navigator",
"lang":"esp",
"start_precise":3909.125,
"end_precise":3914.250,
"duration_precise":5.125,
"start":3909,
"end":3914,
"duration":5,
"length":36,
"body":"Eres un mentiroso. Asumiré el mando.",
"highlight": {
"body":["Eres un mentiroso. Asumiré el [hl]mando[/hl]."]
}

   ]

     }


Note that the highlight field won't be there if query_type=match_all.

Example of a response with an error message:
{ "res": "error", "errors": ["Quota exceeded"] }

Play API

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

<audio controls="true" preload="none" controlsList="nodownload">
<source src="https://voicecup.com/play?key=YOUR_API_KEY&filename=snL4Nqla_2_esp&filetype=mp4&start=3909.125&duration=5.125&subs_id=55a8c5ec312f9108fc57731c" type="audio/mp4">
<source src="https://voicecup.com/play?key=YOUR_API_KEY&filename=snL4Nqla_2_esp&filetype=webm&start=3909.125&duration=5.125&subs_id=55a8c5ec312f9108fc57731c" type="audio/webm">
</audio>

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