API verto

Тот же сервис программно. Ключей и регистрации нет: предел считается по адресу, с которого пришёл запрос. Всё общение — обычный HTTP и JSON.

Основа

Адрес: https://verto.ainon.ru. Только HTTPS; обращение по http перенаправляется. Без ключа API тоже работает — как гость, с гостевыми пределами.

Ключ

Ключ нужен, чтобы сервис узнавал вас в скрипте так же, как в браузере: ваши пределы вместо гостевых, доступ к вашим модулям, задачи попадают в вашу историю. Заводится в личном кабинете и показывается один раз — сохраните сразу, восстановить его нельзя.

Передавать можно любым из двух заголовков, они равнозначны:

curl -s -H "Authorization: Bearer ainon_…" https://verto.ainon.ru/api/me
curl -s -H "X-Ainon-Key: ainon_…"          https://verto.ainon.ru/api/me

{"signed_in":true,"email":"вы@пример.рф",
 "limits":{"per_hour":60,"concurrent":2,…},
 "modules":["audio","image","video",…]}

Отзыв — в том же кабинете. Отозванный ключ перестаёт действовать в течение минуты.

GET/api/me — кем сервис вас считает и что вам сейчас можно. Полезно как первая проверка ключа.

GET/api/mine — ваши последние задачи. Только с ключом; гостю отвечает 401.

Каталог направлений

GET/api/formats

Отдаёт всё, что нужно знать перед отправкой: какие направления есть, к какому семейству относится формат, предел на размер и схему настроек. Берите список отсюда, а не зашивайте у себя — он меняется.

curl -s https://verto.ainon.ru/api/formats | jq '.routes.png'
[ "jpg", "webp", "avif", "pdf", "ico", "txt" ]

Отправить один файл

POST/api/jobs — multipart/form-data

curl -s -X POST https://verto.ainon.ru/api/jobs \
  -F "file=@photo.png" \
  -F "target=jpg" \
  -F 'settings={"quality":70,"max_side":"1280"}'

{"id":"3f9c…","token":"kEHJ…","real_ext":"png","kind":"image",
 "options":{"quality":70,"max_side":"1280"},
 "targets":["jpg","webp","avif","pdf","ico","txt"]}

Ответ 201. Поле real_ext — это тип, определённый по содержимому файла; он может отличаться от расширения в имени, и решение принимается именно по нему.

Следить за задачей

GET/api/jobs/{id}?after=N

after — номер последней полученной строки журнала: так при каждом опросе приходят только новые. Разумный шаг опроса — секунда или две.

curl -s "https://verto.ainon.ru/api/jobs/3f9c…?after=0"

{"id":"3f9c…","status":"DONE","progress":100,
 "src":"png","dst":"jpg","error":null,
 "log":[{"id":1,"ts":1790,"level":"step","text":"Принят файл photo.png"}, …],
 "download":"/download/kEHJ…","result_name":"photo.jpg",
 "result_size":51234,"expires_in":7190}

GET/download/{token} — забрать готовый файл. Отдаётся как вложение, живёт два часа.

Пакет из нескольких файлов

POST/api/batches — те же поля, но повторяющиеся: files, targets и settings идут по порядку и должны совпадать по числу (настройки можно опустить).

curl -s -X POST https://verto.ainon.ru/api/batches \
  -F "files=@a.png"  -F "targets=jpg"  -F 'settings={"quality":60}' \
  -F "files=@b.wav"  -F "targets=mp3"  -F 'settings='

{"id":"7a1b…","token":"TjtQ…","accepted":2,"total":2,
 "files":[{"ok":true,"id":"…","name":"a.png"},
          {"ok":true,"id":"…","name":"b.wav"}]}

Негодный файл не рушит пакет: он придёт с "ok": false и объяснением в error, остальные будут приняты.

GET/api/batches/{id} — состояние всех файлов разом, признак finished и ссылка archive, когда есть что складывать.

GET/download/batch/{token} — все готовые файлы одним zip. Архив собирается в момент запроса, так что его можно брать и до окончания всего пакета.

Настройки

Схема приходит в /api/formats. Каждая настройка — это либо перечисление (kind: "choice"), либо число в диапазоне (kind: "number"). Значение обязано попадать в допустимые: всё прочее отклоняется с 400 и объяснением.

curl -s https://verto.ainon.ru/api/formats | jq '.options.mp4'
[ {"key":"quality","kind":"choice","default":"normal", …},
  {"key":"resolution","kind":"choice","default":"source", …},
  {"key":"codec","kind":"choice","default":"h264", …},
  {"key":"rotate","kind":"choice","default":"0", …},
  {"key":"flip","kind":"choice","default":"none", …} ]

Присылать нужно только изменённое; пропущенное берётся по умолчанию.

Ошибки

Код ответа плюс {"detail": "объяснение по-русски"}.

Пределы

Считаются по адресу запроса, а с ключом — по вашей учётной записи. Пакет из двадцати файлов — это одна задача в часовом счёте, а не двадцать.

Ниже — гостевые значения. Свои нынешние смотрите в /api/me: они настраиваются и в таблице могут устареть.

GET/api/health — состояние сервиса и занятость хранилища; годится для проверки доступности.