API 1.0/ru

From Aviberry API

Jump to: navigation, search

Вызовы Aviberry API можно производить с помощью запросов по методам GET и POST. Для метода GET в общем случае URL запроса выглядит следующим образом: 

http://api_key:api_pass@aviberry.com/api/v1/protocol/method?param=value

, где

  • api_key и api_pass - ключ и пароль для идентификации пользователя, вызывающего API (обязательные поля);
  • protocol - используемый протокол обмена: "json" или "xml" (обязательное поле);
  • method - имя метода для вызова (обязательное поле);
  • param и value - имя и значение передаваемого методу параметра.

Таким образом, если вызов идет по методу GET, то имя вызываемого метода и список передаваемых ему параметров включается в сам URL запроса. Для метода POST URL запроса будет выглядеть немного иначе: 

http://api_key:api_pass@aviberry.com/api/v1/protocol/

В этом случае имя вызываемого метода и передаваемые ему параметры кодируются в теле самого POST запроса. Для протокола JSON-RPC в теле запроса должен быть JSON-encoded объект с закодированными согласно стандарту методом и параметрами вызова, а для протокола XML-RPC - XML-encoded объект с теми же, закодированными согласно стандарту, методом и параметрами вызова. В зависимости от того, по какому протоколу сделан вызов, будет получен ответ от сервера в соответствующем формате. Все передаваемые строковые данные должны быть в кодировке UTF-8, если не указано иное.

Ключ и пароль для доступа к API генерируются и перегенерируются в любой момент самим пользователем на странице своего аккаунта.


Contents


Методы API

Все методы API имеют имена в стиле camelCase, и именно в таком виде они должны быть указаны при вызове: в URL запроса для метода GET и в теле запроса для метода POST. При вызовах API по методу GET все значения параметров должны быть закодированы соответственно стандарту.

Параметры, передаваемые методам, могут быть следующих типов: строка, массив или объект. Параметры, являющиеся объектами, допускают дополнительные уровни вложенности, т.е. могут в качестве значений своих свойств иметь подобъекты. Все методы API в качестве результата своей работы, возвращают объекты, содержащие результаты вызова: JSON-объект для JSON-RPC или XML-структура для XML-RPC.

Под "объектом" следует понимать некий ассоциативный массив, т.е. набор пар ключ=значение. В зависимости от протокола запроса такой "объект" должен быть представлен или как JSON-объект для JSON-RPC, или XML-структура для XML-RPC.

Для вызовов с помощью метода GET "объект" должен передаваться по соглашению, согласно которому в URL должно быть закодировано (придерживаясь специальной нотации) каждое свойство объекта, значение которого необходимо установить, и каждый такой элемент в этот момент выступает как отдельный параметр: 

object[property]=value
object[property][subproperty]=value
object[property][subproperty][subsubproperty]=value
и т.д.

, где символы [ и ] являются обязательными элементами синтаксиса. Далее по тексту, указания на свойства каких-либо объектов будут делаться также, придерживаясь этого синтаксиса.

Под "массивом" следует понимать обычный массив, элементы которого последовательно пронумерованы начиная с 0. В зависимости от протокола запроса такой "массив" должен быть представлен или как JSON-массив для JSON-RPC, или XML-массив для XML-RPC.

Для вызовов с помощью метода GET "массив" должен передаваться по соглашению, согласно которому в URL должен быть закодирован (придерживаясь специальной нотации, представленной ниже) каждый элемент массива, значение которого необходимо установить, и каждый такой элемент в этот момент выступает как отдельный параметр: 

object[]=value // object[0]
object[]=value // object[1]
object[]=value // object[2]
и т.д.

, где символы [ и ] являются обязательными элементами синтаксиса.

Для вызовов с помощью метода GET булево значение true может быть закодировано как '1', 'true' или 'yes'. Все остальные значения трактуются как false.

Предлагаемая реализация передачи объекта по методу GET идет в "нарушение" официальной спецификации для протокола JSON-RPC 1.1. Согласно спецификации JSON-RPC 1.1 через GET объекты не передаются вообще, но можно передать не ассоциативный одномерный массив. Для XML-RPC запросы GET не предусмотрены стандартом вообще, но оформленные описанным выше способом, будут приняты и обработаны и они. Для JSON-RPC на самом деле никакого физического "нарушения" стандарта нет, просто передаются специальным образом именуемые отдельные параметры.

Разработчики могут использовать сторонние библиотеки для вызовов Aviberry API, что освобождает их от ручного формирования тела запроса, а также обработки ответа от сервера для приведения ответа к более подходящему формату представления данных для используемого средства разработки. Ниже приведен список популярных библиотек для различных языков программирования:

PHP
JSON-RPC for PHP
XML-RPC for PHP


Используя эти или какие-либо другие библиотеки, необходимо отправлять все запросы по методу POST, т.к. естественно, что ни одна из сторонних библиотек не знает об описанном выше соглашении для передачи параметров, являющихся объектами, по методу GET. Возможность вызова функций API по методу GET предусмотрена для общей "законченности" решения и в определенных ситуациях может быть очень полезна, т.к. отправка запроса по методу GET является самым простым и быстрым способом вызвать какой-либо метод Aviberry API, не прибегая к сторонним средствам.

startConversion

Метод создает и запускает конвертацию с указанными параметрами. Возвращает объект, содержащий информацию о выполнении метода.

Сигнатура 

object startConversion(
    mixed  source_url,
    string target_url,
    object converter,
    object preview = {},
    object callback = {},
    object params = {},
    object data = {}
)

Параметры

Параметр Тип Описание
source_url mixed Ссылка на исходный видео файл или массив таких ссылок. Когда задан массив ссылок, то это означает, что все конвертированные исходные файлы будут объединены в один файл назначения, задаваемый в target_url. Такое поведение аналогично включенной функции join в настольных конвертерах. Принимаются ссылки вида: 
http|https://[user[:password]@]hostname[:port]/[path]/[filename]
ftp|ftps://[user[:password]@]hostname[:port]/[path]/[filename]
http://[user:password@]bucket.s3.amazonaws.com/[path]/[filename]

Ссылка должна быть оформлена соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded".

target_url string Ссылка, куда необходимо поместить файл, полученный в результате конвертации. Ссылка обязательно должна включать имя файла-результата. Не указание имени считается ошибкой. Именем файла считается все, что указано после последнего слеша /. Принимаются ссылки вида: 
ftp|ftps://[user[:password]@]hostname[:port]/[path]/filename
http://user:password@bucket.s3.amazonaws.com/[path]/filename
mailto:email

В последнем случае на email будет отправлено письмо с сообщением о результате конвертации и ссылкой на скачивание файла. Имя файла-результата в данном случае не указывается и будет сформировано автоматически. С момента окончания конвертации сервис aviberry.com в течение 1 суток предоставляет хостинг для файла-результата, в течение которых файл должен быть скачан. По истечении указанного периода ссылка на скачивание станет недействительной.

Ссылка должна быть оформлена соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded".

converter object Обязательный объект с настройками конвертера:
Свойство Тип Описание
format_id integer Цифровой идентификатор формата. Обязательное свойство. См. раздел Поддерживаемые форматы.
preset_id integer Идентификатор пресета, который следует использовать для формата. Пресет может быть или предустановленным , или созданным самим пользователем. См. раздел Форматы и пресеты).
preset_data string Строка JSON, которая представляет собой закодированный объект с настройками пресета. Каждый поддерживаемый формат имеет свой набор специфичных настроек, т.е. имеет свой формат пресета. См. раздел Параметры пресетов.
transform object Объект с настройками трансформации результурующего файла. Свойствами объекта являются действия, которые необходимо применить к рузультирующему файлу. См. раздел Трансформации.

Свойства объекта с настройками конвертера обрабатываются следующим образом:

  • Если указано только одно свойство converter[format_id], то исходный файл будет сконвертирован в указанный формат и в качестве пресета будет использован пресет по-умолчанию для данного формата (им является первый пресет, указанный для формата в таблице раздела Предустановленные пресеты).
  • Если указаны оба свойства converter[format_id] и converter[preset_id], то исходный файл будет cконвертирован в указанный формат, используя указанный пресет.
  • Если указаны все свойства converter[format_id], converter[preset_id] и converter[preset_data], то исходный файл будет cконвертирован в указанный формат, используя указанный пресет, но определенные настройки указанного пресета будут перекрыты указанными индивидуальными настройками.
  • Если указаны только свойства converter[format_id] и converter[preset_data], то исходный файл будет cконвертирован в указанный формат, используя только указанные индивидуальные настройки пресета.
preview object Необязательный объект с настройками предпросмотра. Предпросмотр - это картинка из середины видео файла. Объект с настройками имеет следующие свойства:
Свойство Тип Описание
width integer Желаемая ширина картинки preview в пикселях. По-умолчанию 160 пикселей.
height integer Желаемая высота картинки preview в пикселях. По-умолчанию 120 пикселей.
resize_method integer См. перечисление ResizeMethod. По-умолчанию RM_LETTERBOX, т.е. 1.
resize_quality integer Cм. перечисление ResizeQuality. По-умолчанию RQ_BEST, т.е. 1.

Любой из параметров предпросмотра может быть опущен. В этом случае будут использованы указанные значения по-умолчанию. Ссылка на картинку предпросмотра становится доступной при статусе конвертации finished (см. метод getProgress) и формируется следующим образом: preview_url = target_url + '.jpg'.

callback object Необязательный объект с настройками функции обратного вызова, которая будет вызвана после завершения конвертации. Возможные ключи и значения:
Свойство Тип Описание
url string Адрес API c функцией обратного вызова.
method string Собственно имя функции обратного вызова, которую необходимо вызвать.
protocol string Протокол, по которому необходимо сделать вызов. Значением должна быть строка "json" для вызова по протоколу JSON-RPC.

Будет сделан RPC вызов метода callback[method] с помощью POST запроса на адрес callback[url] согласно RPС протоколу указанному в параметре callback[protocol]. При вызове методу будут переданы следующие параметры:

Параметр Тип Описание
conversion object Информация о конвертации аналогичная возвращаемой методом getConversion.

Пример запроса, отправляемого по протоколу JSON-RPC: 

?
POST <URI, полученный из callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Имя хоста, полученное из callback[url]>
Content-Type: application/json
Content-Length: ...

{
    "version" : "1.1",
    "method" : "callback[method]",
    "params" : 
    {
        "conversion" : {...}
    }
}


Пример отправляемого по протоколу XML-RPC запроса: 

?
POST <URI, полученный из callback[url]> HTTP/1.1
User-Agent: api.aviberry.com
Host: <Имя хоста, полученное из callback[url]>
Content-Type: text/xml
Content-length: ...

<?xml version="1.0"?>
<methodCall>
    <methodName>callback[method]</methodName>
    <params>
        <param>
            <value>
                <struct>
                    <member>
                        <name>conversion</name>
                        <value><struct>...</struct></value>
                    </member>
                </struct>
            </value>
        </param>
    </params>
</methodCall>

params object Необязательный объект с дополнительными параметрами выполнения метода. Каждое свойство объекта соответствует какому-либо параметру. В настоящий момент определены следующие свойства/параметры:
Свойство Тип Описание
overwrite_target_file boolean Перезаписывать ли файл, "скрывающийся" за target_url, если он уже существует. 1 - перезаписывать, 0 - не перезаписывать. По-умолчанию 0, т.е. при попытке перезаписать существующий файл будет возбуждено исключение.
source_url_encoding string Кодировка переданного имени файла-источника. По умолчанию UTF-8. Более подробно о параметре смотрите в разделе О кодировках.
source_filename_encoding string Актуальная кодировка имени файла-источника, требуемая для доступа к файлу в его файловой системе. По умолчанию UTF-8. Более подробно о параметре смотрите в разделе О кодировках.
target_url_encoding string Аналогично source_url_encoding, но для target_url. По умолчанию UTF-8.
target_filename_encoding string Аналогично source_filename_encoding, но для target_url. По умолчанию UTF-8.
s3_storage_class string Класс хранилища для файлов помещаемых на Amazon S3. Возможными значениями являются STANDARD или REDUCED_REDUNDANCY. По умолчанию STANDARD.

Любой из параметров может быть опущен. В этом случае будут использованы указанные значения по-умолчанию.

data object Необязательный объект с пользовательскими данными, который будет ассоциирован с создаваемой конвертацией. Данный объект будет возвращаться в дальнейшем для конвертации при ее получении различными методами, например getConversion или getConversions. Фактически, объект содержит пользовательские данные в виде пар ключ=значение.

Возвращаемый объект

Свойство Тип Описание
conversion_id string Идентификатор созданной конвертации.

cancelConversion

Отменяет конвертацию, созданную методом startConversion. Если начался непосредственно процесс конвертирования, т.е. началось конвертирование загруженных исходных файлов, то процесс будет остановлен.

Сигнатура 

object cancelConversion(
    string conversion_id
)

Параметры

Параметр Тип Описание
conversion_id string Идентификатор конвертации, которую необходимо отменить.

Возвращаемый объект

Свойство Тип Описание
success boolean Флаг, был ли вызов успешен.

deleteConversion

Удаляет конвертацию. "Удаляет" в данном случает означает, что указанная конвертация не будет больше попадать в выдачу метода getConversions. Удалить можно только законченную или отмененную конвертацию (см. раздел Статусы конвертации). Но и все остальные законченные или отмененные конвертации, которые не были удалены пользователем, остаются доступными только в течении определенного ограниченного времени, по окончании которого они будут удалены автоматически. Сейчас такой период "доступности" установлен в одну неделю.

Сигнатура 

object deleteConversion(
    string conversion_id
)

Параметры

Параметр Тип Описание
conversion_id string Идентификатор конвертации, которую необходимо удалить.

Возвращаемый объект

Свойство Тип Описание
success boolean Флаг, был ли вызов успешен.

getConversion

Возвращает полную информацию об отдельной конвертации. Функция принимает один параметр - идентификатор конвертации, возвращаемый методом startConversion. Соответственно используемому протоколу возвращает или JSON-объект, или XML-структуру с информацией об указанной конвертации.

Сигнатура 

object getConversion(
    string conversion_id
)

Параметры

Параметр Тип Описание
conversion_id string Идентификатор конвертации, информацию о которой необходимо получить.

Возвращаемый объект

Свойство Тип Описание
conversion_id string Идентификатор конвертации, для которой возвращена информация.
source_url array Значение представляет собой source_url указанный при создании конвертации. Заметьте, что возвращается всегда массив ссылок. Т.е., если при начале конвертации в методе startConversion в параметре source_url был задан только один URL как строковый параметр, то будет возвращен массив с одним элементом.
target_url string Значение представляет собой target_url, указанный при создании конвертации.
converter object Значение представляет собой актуальный объект с настройками конвертера converter, указанный при создании конвертации. Термин "актуальный объект" здесь и далее в данном параграфе означает оригинальный объект, неиспользованные свойства которого были заменены значениями по умолчанию.
preview object Значение представляет собой актуальный объект с настройками предпросмотра preview, указанный при создании конвертации.
callback object Значение представляет собой актуальный объект с настройками функции обратного вызова callback, указанный при создании конвертации.
params object Значение представляет собой актуальный объект с настройками выполнения params, указанный при создании конвертации.
data object Объект с пользовательскими данными data, ассоциированный с конвертацией при ее создании.
status string Статус конвертации. Может иметь одно из значений указанных в разделе Статусы конвертации. Для получения более подробной информации о текущем статусе конвертации следует использовать метод getProgress.
result_url string Ссылка на результат конвертации. В зависимости от выбранного приемника она может отличаться от target_url.
preview_url string Ссылка на картинку предпросмотра.
time_created string GMT время создания и постановки конвертации в очередь. Время представляется в формате YYYY-MM-DD HH:MM:SS.
time_started string GMT время начала обработки конвертации. Время представляется в формате YYYY-MM-DD HH:MM:SS.
time_finished string GMT время завершения обработки конвертации. Время представляется в формате YYYY-MM-DD HH:MM:SS.
error_code integer Код ошибки. См. раздел Сообщения об ошибках.
error_mess string Расширенное сообщение об ошибке. См. раздел Сообщения об ошибках.

getConversions

Возвращает информацию о существующих конвертациях.

Сигнатура 

object getConversions(
    object filter = null
)

Параметры

Параметр Тип Описание
filter object Необязательный объект с настройками фильтра для отбора конвертаций. Предусмотрен для будущего использования.

Возвращаемый объект

Возвращаемый объект содержит пары ключ=значение, где ключ - это идентификатор конвертации, а значение - информация о соответствующей конвертации аналогичная той, что возвращается методом getConversion.

getProgress

После запуска конвертация проходит через ряд состояний. С помощью данной функции можно получить подробную информацию о текущем состоянии конвертации.

Сигнатура 

object getProgress(
    string|array(string) conversion_id
)

Параметры

Параметр Тип Описание
conversion_id string|array(string) Идентификаторы конвертаций, прогресс которых необходимо получить.

Возвращаемый объект

  • Если в параметр метода conversion_id была передана строка-идентификатор конвертации, то возвращается объект.
  • Если в параметр метода conversion_id был передан массив строк-идентификаторов конвертаций, то возвращается массив объектов в котором индекс - идентификатор конвертации.
Свойство Тип Описание
conversion_id string Идентификатор конвертации, для которой возвращена информация.
status string Статус конвертации. Может иметь одно из значений указанных в разделе Статусы конвертации.
percent integer Процент выполнения подзадачи от 0 до 100.
elapsed_time integer Время в секундах, прошедшее с начала конвертации, т.е. актуальное значение содержится только для статуса сonverting.
remaining_time integer Время в секундах, оставшееся до конца конвертации, т.е. актуальное значение содержится только для статуса сonverting.
error_code integer Код ошибки. См. раздел Сообщения об ошибках.
error_mess string Расширенное сообщение об ошибке. См. раздел Сообщения об ошибках.

getTraffic

Возвращает информацию о трафике пользователя.

Сигнатура 

object getTraffic()

Параметры

Отсутствуют.

Возвращаемый объект

Возвращает объект с тремя свойствами total, tariffed и purchased, каждое из которых также является объектом, содержащим информацию, соответственно, о всего использованном трафике, тарифицируемом трафике и докупленном трафике. В свою очередь, каждый из этих объектов содержит свойства used и limit, описанные ниже.

Свойство Тип Описание
limit string Лимит в байтах доступного пользователю трафика. Т.к. значение в байтах может быть достаточно большим и выходить за пределы "стандартного" integer в 4 байта, то значение возвращается как строка. Клиент сам должен преобразовать его в требуемое численное представление, если необходимо.
used string Значение в байтах уже использованного пользователем трафика. Т.к. значение в байтах может быть достаточно большим и выходить за пределы "стандартного" integer в 4 байта, то значение возвращается как строка. Клиент сам должен преобразовать его в требуемое численное представление, если необходимо.


Статусы конвертации

Статус Описание
notfound Конвертация с указанным идентификатором не найдена.
queued Конвертация поставлена в очередь обработки.
downloading Загрузка файла для конвертации.
сonverting Конвертация файла.
uploading Выгрузка результата конвертации.
finished Конвертация завершена.
canceled Конвертация отменена пользователем.


При при создании и запуске конвертация ставится в очередь (queued). По достижении своей очереди конвертация попадает на обработку. Происходит загрузка файла-источника (downloading), его конвертация (сonverting), а затем выгрузка результата на указанный ресурс (uploading). После того как результат выгружен, конвертация считается оконченной (finished).

Если на любом из этапов обработки конвертации возникнет ошибка, то конвертация сразу же считается оконченной (finished), но при этом error_code будет не нулевой и error_mess будет содержать расширенное сообщение об ошибке.

Конвертацию, находящуюся в очереди, т.е. еще не попавшую на обработку, возможно отменить. В этом случае конвертация становится отмененной (canceled).


Форматы и пресеты

Процесс конвертации заключается в перекодировании файла из текущего формата в какой-либо иной заданный формат, причем преобразование в формат назначения происходит с определенными настройками. Набор таких настроек для формата назначения называется пресетом. Для всех форматов уже изначально предустановлены один или несколько общеупотребительных пресетов, которые доступны через соответствующий идентификатор. Пользователь также имеет возможность создавать и сохранять для последующего использования свои собственные пресеты на странице своего аккаунта и использовать идентификаторы созданных пресетов в вызовах API (см. описание метода startConversion). Ниже представлены таблицы поддерживаемых форматов, предустановленных пресетов и их возможных настроек.

Поддерживаемые форматы

Идентфикатор Название Расширение файла-результата
16500 AVI (DIVX; XVID; etc) avi
16501 MPEG1;2 (DVD; SVCD; VCD) mpg
16503 WMV wmv
16505 MPEG4 (iPod; MP4) mp4
16506 3GPP (GSM) 3gp
16507 3GPP2 (CDMA) 3gp2
16508 QuickTime mov
16509 Flash flv
16511 MP3 mp3
16520 WebM webm

Предустановленные пресеты

Идентификатор Название
AVI
442 AVI - Audio-Video Interleaved
MPEG1, MPEG2
8 DVD PAL Compatible
7 DVD NTSC Compatible
3 VCD NTSC Compatible
4 VCD PAL Compatible
5 SVCD NTSC Compatible
6 SVCD PAL Compatible
891 MPEG Best Quality
WMV
1493 WMV Video
13 WMV 9 for VHS quality video
14 WMV 9 for DVD quality video (1 mbps)
15 WMV 9 for DVD quality video (2 mbps)
468 WMV HD Video (720p, 4:3)
469 WMV HD Video (1080p, 4:3)
467 WMV HD Video (720p, 16:9)
470 WMV HD Video (1080p, 16:9)
2334 Video for PowerPoint
MPEG4
446 MPEG4 Video
2336 MPEG4 Video (High Quality)
896 HD MPEG4 720p
2734 HD MPEG4 720p (High Quality)
899 HD MPEG4 1080p
3148 HD MPEG4 1080p (High Quality)
901 HD H.264 720p
3150 HD H.264 720p (High Quality)
903 HD H.264 1080p
2736 HD H.264 1080p (High Quality)
920 iPod (320x240)
2739 iPod (320x240) (High Quality)
921 iPod 5G (640x480)
2740 iPod 5G (640x480) (High Quality)
924 iPhone (480x320)
2744 iPhone (480x320) (High Quality)
934 Video for PSP
2746 Video for PSP (High Quality)
3GP
894 Mobile Phone 3GP Video (352x288)
3GP2
895 Mobile Phone 3GP2 Video (352x288)
MOV
892 MOV - QuickTime Video
Flash
533 FLV - Optimal Quality (320x240, H.264/AAC)
542 FLV - Normal Quality (384x288, H.264/AAC)
543 FLV - Best Quality (480x360, H.264/AAC)
948 FLV - H.264 Flash Video
949 FLV - H.263 Flash Video
MP3
120 Audio Only: MP3 High Quality
WebM
2335 WebM

Параметры пресетов

Далее для каждого формата представлены списки возможных параметров пресетов и значения этих параметров для предустановленных пресетов. Списки представлены в JSON-нотации.

AVI 


442

AVI - Audio-Video Interleaved
{
    [+] "VideoCodec" : 879783277,
    
        Описание. 
    
    [+] "Width" : 800,

        Описание2
    
    [+] "Height" : 480,
    
        Описание3
    
    [+] "WPerc" : 100,
    
        Описание4
    
    [+] "HPerc" : 100,
    
        Описание5
    
    [+] "FrameRate" : "25",
    
        Описание6
    
    [+] "LinkSizes" : true,
    
        Описание7
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        Описание8
    
    [+] "ResizeQuality" : RQ_BEST,
    
        Описание9
    
    [+] "VideoSAsInput" : true,
    
        Описание10
    
    [+] "AudioCodec" : -1,
    
        Описание -1 - типа нет кодека?.
    
    [+] "Freq" : FQ_44KHZ,
    
        Описание 
    
    [+] "Channels" : 2
    
        Описание13
    
}

MPEG 1, 2 


8 | 7 | 891 | 3 | 4 | 5 | 6

DVD PAL Compatible
{
    [+] "Type" : 2220022,
    
        0 - MPEG1, 2 - MPEG2. 
    
    [+] "VideoBitrate" : 4025402501150115024152415,
    
        Описание.
    
    [+] "VBRQuality" : 0,
    
        Описание.
    
    [+] "VideoSAsInput" : falsefalsetruefalsefalsefalsefalse,
    
        Описание. 
    
    [+] "Width" : 720720720352352480480,
    
        Описание.
    
    [+] "Height" : 576480576240288480576,
    
        Описание.
    
    [+] "ResizeMethod" : RM_LETTEROX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "25""29.97""25""29.97""25""29.97""25",
    
    
    [+] "AspectRatio" : AR_4_3AR_16_9AR_1_1AR_1_1AR_1_1AR_16_9AR_4_3,
    
        См. перечисление AspectRatio.
    
    [+] "IsSound" : true,
    
        Описание
    
    [+] "AudioBitrate" : 224,
    
        Описание.
    
    [+] "Frequency" : FQ_48KHZFQ_48KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZ,
    
        Описание.
    
    [+] "Channels" : 2,
    
        Описание.
    
    [+] "JointStereo" : false,
    
        Описание
    
}

WMV 


1493 | 13 | 14 | 15 | 468 | 469 | 467 | 470 | 2334

WMV Video
{
    [+] "VideoCodec" : 861293911,
    
        Описание.
    
    [+] "VideoBitrate" : -1326656999424199987247994888192000479948881920002048000,
    
        Описание. -1 = авто.
    
    [+] "VideoQuality" : 857075858585858585,
    
        Описание.
    
    [+] "VideoSAsInput" : truefalsefalsefalsefalsefalsefalsefalsefalse,
    
        Описание.
    
    [+] "Width" : 1280320640640960144012801920640,
    
        Описание.
    
    [+] "Height" : 72024048048072010807201080480,
    
        Описание.
    
    [+] "ResizeMethod" : RM_LETTEROX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "2529.9729.9729.972525252530",
    
        Описание.
    
    [+] "VideoBuffer" : 5000,
    
        Описание.
    
    [+] "ProfileNum" : 0,
    
        Описание.
    
    [+] "WMV" :

        Описание.
    
    {
        [+] "VBR" : 0,
    
            Описание.
        
        [+] "VBRMaxBitrate" : 0,
    
            Описание.
        
        [+] "VBRQuality" : 0,
    
            Описание.
        
        [+] "VidBuffer" : 5000,
    
            Описание.
        
        [+] "VBRMaxBuff" : 0,
    
            Описание.
        
    }

    [+] "AudioCodec" : 353,
    
        Описание.
    
    [+] "AudioBitrate" : 192000640006400064000192000192000192000192000192000,
    
        Описание.
    
    [+] "Frequency" : FQ_48KHZ,
    
        Описание.
    
    [+] "Channels" : 2,
    
        Описание.
    
    [+] "AudioBuffer" : 5000-1-1-150005000500050005000,
    
        Описание. -1 = авто
    
    [+] "WMA" :

        Описание.
    
    {
        [+] "IsAV" : false,
			
            Описание.
        
        [+] "VBR" : 0,
			
            Описание.
        
        [+] "VBRQuality" : 192656565192192192192192,
			
            Описание.
        
    }
}

MPEG 4 

446 | 2336 | 896 | 2734 | 899 | 3148 | 901 | 3150 | 903 | 2736 
920 | 2739 | 921 | 2740 | 924 | 2744 | 934 | 2746

MPEG4 Video
{
    [+] "VideoCodec" : C_MPEG4C_MPEG4C_MPEG4C_MPEG4C_MPEG4C_MPEG4C_H264C_H264C_H264C_H264C_H264C_H264C_H264C_H264C_H264C_H264C_H264C_H264,
    
        См. перечисление Codec.
    
    [+] "Width" : 128012809609601440144096096014401440320320640640480480640640,
    
        Описание
    
    [+] "Height" : 7207207207201080108072072010801080240240480480320320480480,
    
        Описание
    
    [+] "WPerc" : 100,
    
        Описание
    
    [+] "HPerc" : 100,
    
        Описание
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "25""25""25""25""25""25""25""25""25""25""25""25""25""25""25""25""29.97""29.97",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "MPEG4""MPEG4""MPEG4""MPEG4""MPEG4""MPEG4""H264""H264""H264""H264""H264""H264""H264""H264""H264""H264""H264""H264" : 

        
        {
	    [+] "Profile" : 24424424424424424444441111122,
    
                Описание.
            
	    [+] "Bitrate" : -1-11000000010000000150000001500000010000000100000001500000015000000512000512000100000010000001000000100000020000002000000,
    
                Описание. -1 = Auto.
            
	    [+] "Quality" : 333666622440040404,
    
                Описание.
            
	    [+] "MaxIFrameInterval" : 125150125150125150125150125150125150125150125150125150,
    
                Описание.
            
	    [+] "MaxBFrameSequence" : 020202020200000000
    
                Описание.
            
            [+] "VBR" : false
    
                Описание.
            
        }
    }

    [+] "AudioCodec" : C_ACC,
    
        См. перечисление Codec.
    
    [+] "Frequency" : FQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_48KHZFQ_48KHZFQ_44KHZFQ_44KHZFQ_44KHZFQ_44KHZ,
    
        Описание
    
    [+] "Channels" : CH_STEREO,
    
        Описание
    
    [+] "AParams" : 
    
    
    {
        [+] "ACC" : 

        
        {
	    [+] "Profile" : 2,
    
                Описание.
            
	    [+] "Bitrate" : 192192192192192192192192192192128128128128128128192192,
    
                Описание. Частота в КБит/с.
            
	    [+] "Quality" : 100
    
                Описание.
            
	}
    }

    [+] "PSPMode" : falsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsetruetrue,
    
        Описание
    
    [+] "VideoSAsInput" : truetruefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsefalsetruetrue,
    
    
    [+] "LinkSizes" : true,
    
        Описание
    
}

3GP 


894

Mobile Phone 3GP Video (352x288) 
{
    [+] "VideoCodec" : C_H263,
    
        См. перечисление Codec.
    
    [+] "Size" : 23068960,
    
        (Width << 16) | Height
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "15",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H263" : 

        
        {
	    [+] "Bitrate" : 448000,
    
                Описание.
            
	    [+] "Quality" : 30
    
                Описание.
            
	    [+] "VBR" : false,
    
                Описание.
            
	    [+] "MotionSrchRng" : 15,
    
                Описание.
            
	}
    }

    [+] "AudioCodec" : C_AMR,
    
        См. перечисление Codec.
    
    [+] "Frequency" : FQ_8KHZ,
    
        Описание
    
    [+] "Channels" : CH_MONO,
    
        Описание
    
    [+] "AParams" : 
    
    
    {
        [+] "AMR" : 

        
        {
	    [+] "Bitrate" : 12200,
    
                Описание.
            
	}
    }
}

3GP2 


895

Mobile Phone 3GP2 Video (352x288)
{
    [+] "VideoCodec" : C_H263,
    
        См. перечисление Codec.
    
    [+] "Size" : 23068960,
    
        (Width << 16) | Height
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "15",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H263" : 

        
        {
	    [+] "Bitrate" : 448000,
    
                Описание.
            
	    [+] "Quality" : 30
    
                Описание.
            
	    [+] "VBR" : false,
    
                Описание.
            
	    [+] "MotionSrchRng" : 15,
    
                Описание.
            
	}
    }

    [+] "AudioCodec" : C_AMR,
    
        См. перечисление Codec.
    
    [+] "Frequency" : FQ_8KHZ,
    
        Описание
    
    [+] "Channels" : CH_MONO,
    
        Описание
    
    [+] "AParams" : 
    
    
    {
        [+] "AMR" : 

        
        {
	    [+] "Bitrate" : 12200,
    
                Описание.
            
	}
    }
    [+] "b3GPP2Mode" : true,
    
        Описание
    
}

MOV

Flash 


533 | 542 | 543 | 948 | 949

FLV - Optimal Quality (320x240, H.264/AAC)
{
    [+] "VideoCodec" : C_H264,
    
        См. перечисление Codec.
    
    [+] "Width" : 320384480320320,
    
        Описание
    
    [+] "Height" : 240288360240240,
    
        Описание
    
    [+] "WPerc" : 100,
    
        Описание
    
    [+] "HPerc" : 100,
    
        Описание
    
    [+] "ResizeMethod" : RM_LETTERBOX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "15""25""25""25""25",
    
    
    [+] "VParams" : 
    
    
    {
        [+] "H264" : 

        
        {
            [+] "AvcC" : true,
    
                Описание.
            
	    [+] "Profile" : 2,
    
                Описание.
            
	    [+] "Bitrate" : 51200076800010000001200000128000,
    
                Описание.
            
	    [+] "Quality" : 000015,
    
                Описание.
            
	    [+] "MaxIFrameInterval" : 125,
    
                Описание.
            
	    [+] "MaxBFrameSequence" : 0
    
                Описание.
            
	}
    }

    [+] "Frequency" : 44100,
    
        Описание
    
    [+] "Channels" : CH_MONOCH_STEREOCH_STEREOCH_STEREOCH_STEREO,
    
        Описание
    
    [+] "AudioBitrate" : 64128160128128,
    
        Описание
    

    [+] "VideoSAsInput" : falsefalsefalsetruetrue,
 
    
    [+] "LinkSizes" : true,
    
        Описание
    
    [+] "IsSound" : true,
    
        Описание
    
}

MP3 


120

Audio Only: MP3 High Quality
{
    [+] "Frequency" : 0,
    
        Описание
    
    [+] "Channels" : CH_AUTO
    
        Описание13
    
    [+] "Bitrate" : 320
    
        Описание13
    
    [+] "StereoMode" : 2
    
        Описание13
    
    [+] "VBR" : -1
    
        Описание13
    
}

WebM 


2335

WebM
{
    [+] "VideoBitrate" : 1000000,
    
        Описание.
    
    [+] "VideoQuality" : 1,
    
        Описание.
    
    [+] "VideoSAsInput" : true,
    
        Описание.
    
    [+] "Width" : 240,
    
        Описание.
    
    [+] "Height" : 320,
    
        Описание.
    
    [+] "ResizeMethod" : RM_LETTEROX,
    
        См. перечисление ResizeMethod.
    
    [+] "ResizeQuality" : RQ_BEST,
    
        См. перечисление ResizeQuality.
    
    [+] "FrameRate" : "25",
    
        Описание.
    
    [+] "Audio" : true,
    
        Описание
    
    [+] "AudioBitrate" : 128000,
    
        Описание.
    
    [+] "Frequency" : FQ_44KHZ,
    
        Описание.
    
    [+] "Channels" : 2,
    
        Описание.
    
}

Трансформации

В процессе конвертирования файла возможно выполнить над ним некоторые преобразования для получения более приемлемых или даже расширенных параметров получаемого видео. Например, можно обрезать видео, изменить контрастность, наложить на получаемое видео "водяной знак" и др. Все возможные трансформации и их параметры перечислены ниже. Трансформация задается в методе startConversion.

Вырезание

Вырезает из видео указанный фрагмент. Имя операции, которое следует использовать для настройки, - cut. Формат задания параметров операции: 

start_interval units, end_interval units
Параметр Тип Описание
start_interval integer Интервал, с которого начинается вырезаемый фрагмент. Если параметр опущен, то фрагмент будет вырезан с начала. Длина интервала определяется параметром units.
end_interval integer Интервал, на котором заканчивается вырезаемый фрагмент. Если параметр опущен, то фрагмент будет вырезан до конца файла. Длина интервала определяется параметром units.
units string Единица измерения интервала. Может принимать следующие значения: 'h' (часы), 'm' (минуты), 's' (секунды), 'ms' (миллисекунды).

Как минимум хотя бы один из приведенных параметров должен быть указан при настройке операции. Интервалы могут быть составными. Примеры определения: 

converter[transform][cut] = '1000,10s' // Вырежет 9 сек видео, начиная с 1 сек файла.
converter[transform][cut] = '1m,'      // Вырежет фрагмент, начиная с 1 мин и до конца файла.
converter[transform][cut] = ',10m17s'  // Вырежет 10 мин 17 сек сек видео с начала файла.


Разделение

Разделяет видео на фрагменты равной продолжительности или равного размера. Имя операции, которое следует использовать для настройки, - split. Формат задания параметров операции: 

amount units
Параметр Тип Описание
amount integer Продолжительность или размер фрагмента, на который делится видео. Как именно трактуется параметр, зависит от параметра units.
units string Единица измерения параметра amount. Может принимать следующие значения: 'h' (часы), 'm' (минуты), 's' (секунды), - тогда amount трактуется как продолжительность файла-фрагмента, или: 'gb' (гигабайты), 'mb' (мегабайты), 'kb' (килобайты), - тогда amount трактуется как размер файла-фрагмента.

Оба параметра обязательны для указания. Если задается разделение по продолжительности, то минимально возможной частью является 1 минута ('1m' = '60s'). Если по размеру, то минимально возможной частью является 10 Мб ('10mb' = '1024kb').

Интервал или размер могут быть составными. Примеры определения: 

converter[transform][split] = '1m30s' // Разделит видео на фрагменты продолжительностью полторы минуты.
converter[transform][split] = '1h'   // Разделит видео на фрагменты продолжительностью 1 час.
converter[transform][split] = '50mb'   // Разделит видео на фрагменты размером 50 Мб.


Обрезание

Обрезает кадр на указанные отступы. Имя операции, которое следует использовать для настройки, - сrop. Формат задания параметров операции: 

top, right, bottom, left

или 

padding
Параметр Тип Описание
top float Отступ для обрезки сверху. Относительная величина, которая задается как отношение величины отступа к высоте кадра. По умолчанию 0.0.
right float Отступ для обрезки справа. Относительная величина, которая задается как отношение величины отступа к ширине кадра. По умолчанию 0.0.
bottom float Отступ для обрезки снизу. Аналогично top. По умолчанию 0.0.
left float Отступ для обрезки слева. Аналогично right. По умолчанию 0.0.
padding float Одинаковый отступ для обрезки сверху, справа, снизу и слева.

При использовании первого формата как минимум хотя бы один из указанных параметров должен быть задан при настройке операции. Опущенные параметры принимают указанные значения по умолчанию. При использовании второго формата единственный параметр является обязательным. Примеры определения: 

converter[transform][crop] = '0.2,0.1,0.2,0.1' // Обрежет кадр сверху и снизу по 20%, справа и слева по 10% от исходного размера.
converter[transform][crop] = ',0.1,,0.1'       // Обрежет кадр справа и слева по 10% от исходного размера.
converter[transform][crop] = '0.2,0.1,,'       // Обрежет кадр сверху на 20% и справа на 10% от исходного размера.
converter[transform][crop] = '0.1'             // Обрежет кадр по 10% со всех сторон.


Поворот

Осуществляет поворот видео. Имя операции, которое следует использовать для настройки, - rotate. Формат задания параметров операции: 

mode
Параметр Тип Описание
mode string Способ поворота. Может принимать следующие значения: 'cw' (clockwise) - поворот по часовой стрелке на 90°, 'ccw' (counterclockwise) - поворот против часовой стрелки на 90°, 'usd' (upside down) - поворот на 180°.

Пример определения: 

converter[transform][rotate] = 'cw' // Поворачивает видео на 90 градусов по часовой стрелке.

Водяной знак

Накладывает на видео "водяной знак". Водяным знаком может быть или изображение, или текст, или оба они сразу. Имя операции, которое следует использовать для настройки, - watermark. Для настройки водяного знака отдельно задаются параметры изображения, параметры текста и общие параметры знака.

Настройка изображения. Имя свойства операции, которое следует использовать для настройки, - image.

Параметр Тип Описание
image string Ссылка на файл изображения. Обязательный параметр. Принимаются ссылки вида: 
http|https://[user[:password]@]hostname[:port]/[path/][filename]
ftp|ftps://[user[:password]@]hostname[:port]/[path/][filename]
http://[user:password@]bucket.s3.amazonaws.com/[path/][filename]

Ссылка должна быть оформлена соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded".

size string Формат задания размера: 
scale, aspect
Параметр Тип Описание
scale float Коэффициент масштабирования блока. Относительная величина, которая задается как отношение конечной величины блока к его начальной величине. Под блоком следует понимать область, занимаемую изображением или текстом. Например, коэффициент 2.0 означает увеличение блока вдвое. Необязательный параметр. По умолчанию 1.0.
aspect mixed Отношение ширины блока к его высоте. Под блоком следует понимать область, занимаемую изображением или текстом. Необязательный параметр. По умолчанию 0.0, т.е. изображение сохраняет оригинальные пропорции. Значение может быть задано как число с дробной точкой или как строка соотношения. Например, в качестве значения параметра можно указать или 1.333, или '4:3'.
position string Формат задания позиции: 
vertical, horizontal

или 

align
Параметр Тип Описание
vertical float Отступ от верхнего (при положительном значении) или нижнего (при отрицательном значении) края кадра до центра блока. Относительная величина, которая задается как отношение величины отступа к высоте кадра. Под блоком следует понимать область, занимаемую изображением или текстом. Например, коэффициент 0.1 означает отступ в 10% сверху, -0.1 означает отступ в 10% снизу. Необязательный параметр. По умолчанию 0.0.
horizontal float Отступ от левого (при положительном значении) или правого (при отрицательном значении) края кадра до центра блока. Относительная величина, которая задается как отношение величины отступа к ширине кадра. Под блоком следует понимать область, занимаемую изображением или текстом. Например, коэффициент 0.1 означает отступ в 10% слева, -0.1 означает отступ в 10% справа. Необязательный параметр. По умолчанию 0.0.
align string Выравнивание блока относительно кадра. Под блоком следует понимать область, занимаемую изображением или текстом. Возможные значения 'top', 'top_right', 'right', 'bottom_right', 'bottom', 'bottom_left', 'left', 'top_left', 'center'.

При использовании первого формата как минимум хотя бы один из указанных параметров должен быть задан при настройке операции. Опущенный параметр принимает указанное значение по умолчанию. При использовании второго формата единственный параметр является обязательным.

Настройка текста. Имя свойства операции, которое следует использовать для настройки, - text.

Параметр Тип Описание
text string Текст для использования в качестве водяного знака. Обязательное поле.
size string Аналогичен параметру size для изображения.
position string Аналогичен параметру position для изображения.
font string Формат задания шрифта 
face, style, size, color
Параметр Тип Описание
face string Имя гарнитуры шрифта. Необязательный параметр. По умолчанию 'Arial'.
style string Стиль шрифта. Возможные значения: 'regular', 'bold', 'italic', 'bold_italic'. Необязательный параметр. По умолчанию 'regular'.
size float Размер шрифта. Относительная величина, которая задается как отношение размера шрифта к размеру кадра. Необязательный параметр. По умолчанию 0.05.
color string Цвет текста в формате RGB, где каждая составляющая цвета задана шестнадцатиричным числом. Необязательный параметр. По умолчанию '000000' (черный цвет).

Настройка общих параметров. Каждый общий параметр трактуется как отдельное свойство операции. Список общих параметров представлен ниже.

Параметр Тип Описание
transparency float Прозрачность водяного знака. Может принимать значения от 0.0 (непрозрачно) до 1.0 (прозрачно). По умолчанию 0.0.

Любые необязательные параметры могут быть опущены. В этом случае они принимают указанные значения по умолчанию. Пример определения: 

converter[transform][watermark][image][image] = 'http://example.org/watermark.png' // Задает в качестве водяного знака указанную картинку.
converter[transform][watermark][image][size] = '1.5,4:3' // Увеличивает картинку на 50% и устанавливает соотношение ее сторон 4:3 (1.333).
converter[transform][watermark][image][position] = '-0.2,0.3' // Смещает картинку на 20% снизу и 30% слева.
converter[transform][watermark][text][text] = 'My Watermark' // Задает в качестве водяного знака указанный текст.
converter[transform][watermark][text][size] = '2' // Увеличивает текст в 2 раза и соотношение сторон текстового блока оставляет неизменным.
converter[transform][watermark][text][position] = 0.9,0.9 // Смещает текст к правому нижнему углу кадра.
converter[transform][watermark][text][font] = ',italic,,ff0000' // Задает для текста наклонное начертание и красный цвет.
converter[transform][watermark][transparency] = '0.5' // Делает водяной знак прозрачным на половину.

Коррекция изображения

Осуществляет общую корректировку изображения. Имя операции, которое следует использовать для настройки, - adjust. Операция состоит из набора подопераций, которые трактуются как отдельные свойства операции и представлены ниже.

Параметр Тип Описание
magic_enhance boolean По умолчанию false.
auto_contrast boolean Автоматическая настройка контраста. По умолчанию false.
auto_whitebalance boolean Автоматическая настройка баланса белого. По умолчанию false.
deblocking boolean По умолчанию false.
deinterlacing boolean Убрать черезстрочность. По умолчанию false.
brightness integer Яркость. Возможные значения от -70 до 70. По умолчанию 0.
сontrast integer Контраст. Возможные значения от 128 до 384. При значении 256 контраст не меняется. По умолчанию 256.
hue integer Оттенок. Возможные значения от -180 до 180. При значении 0 оттенок не меняется.
saturation integer Насыщенность. Возможные значения от -100 до 100. При значении 0 насыщенность не меняется.

Пример определения: 

converter[transform][adjust][deinterlacing] = true // Убирает черезстрочность.
converter[transform][adjust][contrast] = 300    // Задает контраст.

Перечисления

ResizeMethod

Значение Название Описание
0 RM_STRETCH Не сохраняет aspect-ratio, вся исходная картинка попадает в кадр без полей.
1 RM_LETTERBOX Сохраняет aspect-ratio, вся исходная картинка попадает в кадр, добавляются чёрные поля.
2 RM_CROP Сохраняет aspect-ratio, в кадр попадает часть картинки без полей.

ResizeQuality

Значение Название Описание
0 RQ_NORMAL Аппроксимация по ближнему (плохое качество).
1 RQ_BEST Билинейная аппроксимация (лучшее качество).

Codec

Значение Название Описание
"mp4v" C_MPEG4 MPEG4 в Wikipedia
"s263" C_H263 H.263 в Wikipedia
"avc1" C_H264 H.264 в Wikipedia
"mp4a" C_AAC AAC в Wikipedia
"samr" C_AMR AMR в Wikipedia

Frequency

Значение Название Описание
48000 FQ_48KHZ Частота 48000 Гц.
44100 FQ_44KHZ Частота 44100 Гц.
32000 FQ_32KHZ Частота 32000 Гц.
24000 FQ_24KHZ Частота 24000 Гц.
22050 FQ_22KHZ Частота 22050 Гц.
16000 FQ_16KHZ Частота 16000 Гц.
12000 FQ_12KHZ Частота 12000 Гц.
11025 FQ_11KHZ Частота 11025 Гц.
8000 FQ_8KHZ Частота 8000 Гц.
6000 FQ_6KHZ Частота 6000 Гц.

Channels

Значение Название Описание
0 CH_AUTO Автоматически.
1 CH_MONO Моно (1 канал).
2 CH_STEREO Стерео (2 канала).

AspectRatio

Значение Название Описание
0 AR_1_1 1 : 1
1 AR_221_1 2.21 : 1
2 AR_4_3 4 : 3
3 AR_16_9 16 : 9

О кодировках

Имена файлов

Рассмотрим подробнее метод API startConversion. Все сказанное далее не является проблемой, если имена файлов содержат только символы латиницы. Но, если в именах используются национальные символы, то требуемый результат может быть и не получен, т.е. не удастся создать конвертацию.

Рассмотрим для примера обработку source_url, т.е. обработку имени файла-источника. Как уже было сказано при описании метода, имя файла-источника должно быть оформлено соответственно стандарту, т.е. все спецсимволы должны быть "percent-encoded". Cервис после получения этого параметра выполнит обратное преобразование и получит "стандартное" имя файла-источника, которое и будет использовать в дальнейшей работе.

Например, дальнейшей работой является определение того, что файл-источник существует на самом деле. Для этого будет использовано уже это новое, преобразованное имя. Но, вполне может статься, что имя файла-источника в файловой системе сервера, на котором он хранится, находится в другой кодировке, чем переданное имя. Тогда, используя полученное имя, сервис не сможет определить наличие файла даже существующего на самом деле.

С помощью пары соответствующих параметров source_url_encoding и source_filename_encoding для файла-источника можно точно сказать сервису, что "переданное методу имя фала-источника сейчас в кодировке source_url_encoding, но для того, чтобы получить доступ к файлу в файловой системе сервера, на котором он хранится, нам нужно имя файла-источника в кодировке source_filename_encoding (актуальной кодировке)". Т.е. возможно задать некое "правило" преобразования переданного имени файла-источника, и сервис выполнит это преобразование.

Рассмотрим конкретный пример. Допустим, на некоем FTP сервере ftp.example.com, в его корне, находится файл пример.flv (русские символы в названии), созданный изначально в Windows. Верным URL этого файла для передачи сервису является ftp://ftp.example.com/%EF%F0%E8%EC%E5%F0.flv. Допустим, что есть HTML форма, на которой пользователь может сам вводить имя файла и некий пользователь указывает этот самый файл. Пользователь - это не компьютер - и он вместо ftp://ftp.example.com/%EF%F0%E8%EC%E5%F0.flv может набрать просто ftp://ftp.example.com/пример.flv и будет прав :-). И если кодировка страницы с формой UTF-8, то URL файла полученного с формы примет вид ftp://ftp.example.com/%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.flv. Если данный URL передать в качестве файла-источника при создании конвертации, то сервис вернет ошибку, что такого файла не существует, т.к. на самом деле в файловой системе сервера лежит именно файл %EF%F0%E8%EC%E5%F0.flv. Для успешного создания конвертации необходимо или пользователю API самому перекодировать полученное из формы имя файла в актуальную кодировку, или же при создании конвертации задать дополнительные параметры. В данном примере установить source_filename_encoding в Windows-1251.

Заданное "правило" преобразования имени файла-источника срабатывает только если пара параметров source_url_encoding и source_filename_encoding установлена в различные значения. При одинаковых значениях, никакого преобразования не выполняется, т.е. данные параметры игнорируются, а сервисом используется имя файла-источника именно в том виде, в каком ему передано. Данное поведение, является поведением по умолчанию, т.к. оба параметра по умолчанию установлены в UTF-8.

Для файла-результата все аналогично сказанному для файла-источника. Список поддерживаемых кодировок представлен в приложении.

Таким образом, основное правило при передаче имени файла-источника или имени файла-результата, содержащего национальные символы: "percent-encoded" должно быть имя файла в актуальной кодировке для файловой системы, на которой данный файл хранится. Если по какой-то причине это не так, то пользователь API или сам должен получить имя файла в актуальной кодировке и передать уже его, или должен использовать описанные здесь соответствующие параметры метода startConversion для того, чтобы указать сервису правило получения имени файла в актуальной кодировке из переданного имени.

Поддерживаемые кодировки

byte2be UCS-4BE UTF-8 ISO-2022-JP-MS ISO-8859-10 UHC
byte2le UCS-4LE UTF-7 Windows-1252 ISO-8859-13 ISO-2022-KR
byte4be UCS-2 UTF7-IMAP ISO-8859-1 ISO-8859-14 Windows-1251
byte4le UCS-2BE ASCII ISO-8859-2 ISO-8859-15 CP866
BASE64 UCS-2LE EUC-JP ISO-8859-3 ISO-8859-16 KOI8-R
UUENCODE UTF-32 SJIS ISO-8859-4 EUC-CN ArmSCII-8
HTML-ENTITIES UTF-32BE eucJP-win ISO-8859-5 CP936
Quoted-Printable UTF-32LE SJIS-win ISO-8859-6 HZ
7bit UTF-16 CP51932 ISO-8859-7 EUC-TW
8bit UTF-16BE JIS ISO-8859-8 BIG-5
UCS-4 UTF-16LE ISO-2022-JP ISO-8859-9 EUC-KR

Сообщения об ошибках

Все сообщения об ошибках одинаковы как для вызовов по протоколу JSON-RPC, так и для вызовов по протоколу XML-RPC.

Код Описание
-32768 .. -32000 Ошибки протокола.
0 Ошибки нет, результат доступен для использования.
1 .. 32000 Ошибки приложения.

Ошибки протокола

Код Описание
-32700 Ошибка разбора полученных данных.
-32600 Полученные данные не представляют собой валидный запрос.
-32601 Запрошенный метод не существует или недоступен.
-32602 Метод запрошен с неверными параметрами.
-32000 Внутренняя ошибка.

Ошибки приложения

Ниже дано краткое значение ошибок приложения. В действительности многие сообщения более многословны, с более конкретными указаниями причин их появления.

Код Описание
1 Не авторизованный доступ к API.
2 Неверное значение параметра.
3 Аккаунт неактивен.
4 Превышен лимит.
5 Превышен трафик.
6 Некорректный выходной формат.
7 Файл не существует.
8 Файл уже существует.
9 Не авторизованный доступ к файлу.
10 Не верный логин или пароль при доступе к файлу.
11 Ошибка обратного вызова.
12 Ошибка загрузки файла.
13 Ошибка конвертера.
14 Ошибка выгрузки файла.
15 Неизвестный дополнительный параметр.
16 Неизвестный размер файла.
17 Размер файла превысил допустимый лимит.
32000 Внутренняя ошибка.
Languages Язык: 

English  • Русский

Retrieved from "http://api.aviberry.com/API_1.0/ru"
Views
Personal tools
In other languages