Документация к API сайта Voicecup.com
Об этом API
Параметры API поиска
Формат ответа сервера
API воспроизведения аудиофрагментов
Ключ API
Квота на количество запросов
Демо на отдельной странице
Ссылка на наш сайт
Сайты, на которых используется данный API
Об этом API
Данный API позволяет производить поиск по субтитрам к фильмам на разных языках и возвращать аудиофайл фрагмента, содержащего найденный текст, с указанием позиции начала и конца фрагмента, соответствующего найденным субтитрам.
Файлы, которые возвращает данный API, могут быть использованы в HTML5-тэге <audio>.
ДЕМО.
Параметры API поиска
Пример минимального запроса к API:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father
Пример запроса с поиском по субтитрам только на английском языке:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father&lang=eng
Если язык не указан, будет произведен поиск по субтитрам на всех доступных языках.
Параметры запроса:
| Параметр | По умолчанию | Описание |
| key | - | - Ваш ключ API. Обязательный параметр. |
| q | - | - искомый текст. Обязательный параметр, если query_type != match_all. |
| lang | - | - язык субтитров, в которых будет производиться поиск. |
| format | json | - формат, в котором будет выдан результат запроса. Возможные значения: json, jsonp. |
| callback | - | - имя процедуры, которое будет использовано при выдаче результата запроса в формате jsonp. |
| length_min | 1 | - минимальная длина искомых субтитров в символах. |
| length_max | 300 | - максимальная длина искомых субтитров в символах. |
| duration_min | 1 | - минимальная длина фрагмента аудио (в секундах), соответствующего найденным субтитрам. |
| duration_max | 100 | - максимальная длина фрагмента аудио (в секундах), соответствующего найденным субтитрам. |
| from | 0 | - порядковый номер записи, с которой начинать выдачу результатов. Используется для реализации постраничного вывода результатов поиска. |
| size | 10 | - максимальное количество результатов в ответе сервера. Минимальное значение - 1, максимальное - 100. Используется для реализации постраничного вывода результатов поиска. |
| random_sort | 0 | - если установлено 1, то результаты возвращаются в случайном порядке. |
| query_type | 0 | - если установлено match_all, то возвращаются все записи, независимо от значения параметра q. |
Пример запроса к серверу со всеми параметрами:
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
Этот запрос инструктирует API искать фрагменты аудио и видео, содержащие слово
father, в англоязычной базе. Выдать результат в формате jsonp, 15 записей, начиная с 10-й. Искать субтитры не короче 15 и не длиннее 50 символов, длительностью звучания от 5 до 25 секунд.
Формат ответа сервера
Сервер возвращает ответ в формате JSON или JSONP (в зависимости от значения параметра
format).
В случае успешного выполнения запроса параметр
res содержит значение
ok, в противном случае -
error.
В случае значения error список ошибок содержится в параметре
errors.
Параметры, возвращаемые в ответе сервера:
| res | oк в случае успешного выполнения запроса, error - в случае ошибки |
| errors | - список ошибок (если res имееь значение error) |
| quota_daily | - дневная квота запросов для данного ключа API |
| quota_daily_used | - объем использованной квоты за текущий день |
| lang | - язык видео и аудио, в которых произведен поиск |
| time | - время, за которое был исполнен запрос, в миллисекундах |
| query | - искомый текст |
| hits_total | - общее количество найденных субтитров |
| hits |
Содержит найденные субтитры в виде записей со следующей структурой:
| id | - ID записи |
| filename_audio | - имя аудиофайла, в котором содержится произношение искомого текста |
| title | - название источника |
| lang | - язык аудиодорожки, в которой найдены субтитры |
| start_precise | - время начала звучания найденных субтитров (в секундах), с точностью до 1 миллисекунды |
| end_precise | - время окончания звучания найденных субтитров (в секундах), с точностью до 1 миллисекунды |
| duration_precise | - время звучания найденных субтитров (в секундах), с точностью до 1 миллисекунды |
| start | - время начала звучания найденных субтитров (в секундах), с точностью до 1 секунды |
| end | - время окончания звучания найденных субтитров (в секундах), с точностью до 1 секунды |
| duration | - время звучания найденных субтитров (в секундах), с точностью до 1 секунды |
| length | - длина найденных субтитров (в символах) |
| body | - текст найденных субтитров |
| highlight | - текст найденных субтитров с выделенным искомым фрагментом |
|
length_min
length_max
duration_min
duration_max
from
size
| - содержание данных параметров аналогично значениям, переданным в запросе |
Пример ответа сервера при успешном выполнении запроса:
{
"res":"ok",
"from":0,
"size":10,
"length_min":15,
"length_max":50,
"duration_min":5,
"duration_max":25,
"quota_daily_used":217,
"quota_daily":500,
"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]."]
}
]
}
Обратите внимание, что поле highlight будет отсутствовать, если query_type=match_all.
Пример ответа сервера с сообщением об ошибке:
{ "res": "error", "errors": ["Quota exceeded"] }
Play API
Используя информацию, полученную из ответа сервера через API поиска, вставьте аудиофрагмент на веб-страницу следующим образом:
<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>
Параметр
subs_id можно не указывать, однако мы советуем, по возможности, добавлять его. Это поможет предоставить Вам более подробную статистику Вашего аккаунта, в т.ч. относительно того, какие именно аудиофрагменты прослушивают Ваши пользователи.
Точка API
/play в случае успешного выполнения возвращает аудиофайл с указанным в запросе типом MIME, либо, в случае ошибки -
ответ в формате JSON.
Максимальная длина аудиофрагмента, который может быть получен с использованием данного API - 15 секунд.
Ключ API
Ключ API доступен в
Вашем аккаунте сразу после
регистрации.
Вы в любой момент можете сменить ключ.
Квота на использование API
Мы предоставляем бесплатную квоту в
100 воспроизведений аудиофрагментов в день (точка API /play). При превышении лимита в ответе сервера в формате JSON будет выдаваться
сообщение об ошибке "quota exceeded".
Запросы к API для поиска (точка API /api) не влияют на Вашу квоту. Вы можете делать столько запросов для поиска, сколько Вам требуется.
В
Вашем аккаунте Вы можете видеть, сколько времени осталось до восстановления дневной квоты.
Если Вам не хватает этой квоты, пожалуйста,
напишите нам.
Демо на отдельной странице
Standalone demo здесь.
Ссылка на наш сайт
Обязательным условием использования нашего API на Ваших сайтах или в приложениях является ссылка на сайт voicecup.com на все страницах, на которых содержится контент, полученный с использованием нашего API.
Примеры ссылок:
Powered by
Voicecup.com
Examples by
Voicecup.com
Примеры от
Voicecup.com
Ejemplos por
Voicecup.com
Сайты, на которых используется данный API
На этих сайтах Вы можете посмотреть, как наш API используется на практике:
www.diccionario.ru - испанско-русский и русско-испанский словарь
www.diclib.com - онлайн-словари разных языков
