Для разработчиков

REST API конвертера

Версионированный API /api/v1 использует тот же конвейер, что и сайт: загрузили файл, создали задание, дождались статуса, забрали результат. Он доступен только на платном тарифе и требует Bearer-ключ; конвертер в браузере по-прежнему работает без оплаты.

Версионированный контур /api/v1 включён только у действующей платной подписки. Каждый вызов подписывается заголовком Authorization: Bearer; ключ можно выпустить или отозвать в кабинете. Веб-конвертер работает отдельно и ключа не требует.

Рекомендованный порядок

Контракт для backend-интеграции

Ниже — не просто перечень URL, а границы жизненного цикла задания. Интеграции проще сопровождать, если справочник направлений, очередь и выдачу результата считать разными этапами.

Держите Bearer-ключ в серверном хранилище секретов и не встраивайте его в клиентский JavaScript. Отозванный ключ сразу перестаёт проходить общую границу /api/v1.
Перед постановкой работы сверяйте available, maxFileSizeBytes и определения options. Так выключенное направление или неверная настройка обнаружатся до загрузки пакета.
Ответ 202 означает, что задание принято в очередь, а не завершено. Опросите состояние с паузой, дождитесь конечного статуса и берите адрес результата из downloadUrl.
После успешной передачи файла вызывайте DELETE для задания. При 429 учитывайте Retry-After: немедленные повторы только расходуют квоту и создают лишнюю нагрузку.

Основное

Базовый адрес: https://convertare.ru/api/v1
Авторизация: Платный тариф; Authorization: Bearer <API_KEY>
Формат ответов: JSON в кодировке UTF-8; скачивание результата — двоичный поток
Срок жизни файлов: 24 часа после создания задания
Предел загрузки: 512 МБ на файл, до 50 файлов в задании

Порядок работы

Загрузите один или несколько файлов — POST /api/v1/files. В ответ придут идентификаторы файлов и список форматов, в которые их можно преобразовать.
Создайте задание — POST /api/v1/conversions: направление, идентификаторы файлов и настройки. Ответ приходит сразу, до начала обработки.
Опрашивайте состояние — GET /api/v1/conversions/{id}. Разумный интервал: секунда в начале с увеличением до трёх — так работает и сам сайт.
Заберите результат — GET /api/v1/conversions/{id}/download. Для пакетного задания доступен архив со всеми файлами сразу.

Конвертация никогда не выполняется внутри HTTP-запроса: задание попадает в очередь, и запрос на создание возвращается немедленно. Не держите соединение открытым в ожидании результата — опрашивайте статус. Во все запросы к /api/v1 передавайте заголовок Authorization с Bearer-ключом.

POST/api/v1/files

Принимает файлы, определяет их формат по сигнатуре и возвращает идентификаторы.

filemultipart/form-data, обязательное: Содержимое файла. Поле можно повторить несколько раз — файлы загрузятся одним запросом.

Формат определяется по содержимому, а не по расширению: файл с именем scan.jpg, внутри которого PNG, будет опознан как PNG. Поле format равно null, если формат не распознан; в этом случае targets пуст.

Поле files[].expiresAt относится к загрузке, которая ещё не стала заданием: штатно это час. После POST /api/v1/conversions источником истины становится job.expiresAt; для платного тарифа срок равен 24 часа.

Запрос

curl -X POST https://convertare.ru/api/v1/files \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo.heic"

Ответ 201

{
  "files": [
    {
      "id": "u7Kx0Qm3Zt9pR1sVfLbN2a",
      "originalName": "photo.heic",
      "sizeBytes": 2411520,
      "format": {
        "id": "heic",
        "slug": "heic",
        "name": "HEIC",
        "fullName": "High Efficiency Image Coding",
        "category": "image",
        "extensions": ["heic"],
        "mimeTypes": ["image/heic", "image/heic-sequence"],
        "summary": "Формат снимков iPhone: кадр, сжатый кодеком HEVC в контейнере HEIF, — вдвое легче JPEG при том же качестве."
      },
      "targets": [
        {
          "id": "jpg",
          "slug": "jpg",
          "name": "JPG",
          "fullName": "Joint Photographic Experts Group",
          "category": "image",
          "extensions": ["jpg", "jpeg"],
          "mimeTypes": ["image/jpeg"],
          "summary": "Самый распространённый формат фотографий: сжатие с потерями даёт небольшой файл при хорошей картинке."
        }
      ],
      "expiresAt": "2026-08-16T10:12:40.000Z"
    }
  ]
}

POST/api/v1/conversions

Создаёт задание и ставит его в очередь. Отвечает статусом 202 до начала обработки.

conversionIdstring, обязательное: Идентификатор направления вида heic-to-jpg. Список — в ответе GET /api/v1/conversions.
fileIdsstring[], обязательное: Идентификаторы ранее загруженных файлов. Несколько файлов допустимы, если у направления batch: true.
optionsobject, необязательное: Настройки направления: ключ — идентификатор настройки, значение — число, строка или логическое. Недопустимое значение возвращает ошибку, а не подставляет умолчание.

Запрос

curl -X POST https://convertare.ru/api/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversionId": "heic-to-jpg",
    "fileIds": ["u7Kx0Qm3Zt9pR1sVfLbN2a"],
    "options": { "image.quality": 90, "image.stripMetadata": true }
  }'

Ответ 202

{
  "job": {
    "id": "Qd4vT8nH2sLpXw0Ymc6Rbe",
    "conversionId": "heic-to-jpg",
    "status": "queued",
    "options": {
      "image.quality": 90,
      "image.background": "white",
      "image.keepAspect": true,
      "image.stripMetadata": true
    },
    "items": [
      {
        "id": "K9r2LsPq7Wt1Ub3Ndf5Gxa",
        "jobId": "Qd4vT8nH2sLpXw0Ymc6Rbe",
        "sourceFileId": "u7Kx0Qm3Zt9pR1sVfLbN2a",
        "status": "queued",
        "resultName": null,
        "resultSizeBytes": null,
        "errorCode": null,
        "errorMessage": null,
        "startedAt": null,
        "finishedAt": null,
        "durationMs": null,
        "downloadUrl": null
      }
    ],
    "archive": null,
    "createdAt": "2026-08-16T09:12:44.318Z",
    "updatedAt": "2026-08-16T09:12:44.318Z",
    "expiresAt": "2026-08-17T09:12:44.318Z"
  }
}

GET/api/v1/conversions/{id}

Возвращает текущее состояние задания и его элементов.

Поле status принимает значения queued, processing, completed, failed и expired. Других значений не бывает: задание создаётся сразу в очереди, загруженный файл до этого живёт отдельной сущностью POST /api/v1/files. У каждого элемента задания свой статус: часть файлов пакета может обработаться, а часть — нет, тогда у неудачных заполнены errorCode и errorMessage.

Запрос

curl https://convertare.ru/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe \
  -H "Authorization: Bearer $API_KEY"

Ответ 200

{
  "job": {
    "id": "Qd4vT8nH2sLpXw0Ymc6Rbe",
    "conversionId": "heic-to-jpg",
    "status": "completed",
    "options": {
      "image.quality": 90,
      "image.background": "white",
      "image.keepAspect": true,
      "image.stripMetadata": true
    },
    "items": [
      {
        "id": "K9r2LsPq7Wt1Ub3Ndf5Gxa",
        "jobId": "Qd4vT8nH2sLpXw0Ymc6Rbe",
        "sourceFileId": "u7Kx0Qm3Zt9pR1sVfLbN2a",
        "status": "completed",
        "resultName": "photo.jpg",
        "resultSizeBytes": 842019,
        "errorCode": null,
        "errorMessage": null,
        "startedAt": "2026-08-16T09:12:45.002Z",
        "finishedAt": "2026-08-16T09:12:46.242Z",
        "durationMs": 1240,
        "downloadUrl": "/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe/download?target=K9r2LsPq7Wt1Ub3Ndf5Gxa"
      }
    ],
    "archive": null,
    "createdAt": "2026-08-16T09:12:44.318Z",
    "updatedAt": "2026-08-16T09:12:46.301Z",
    "expiresAt": "2026-08-17T09:12:44.318Z"
  }
}

Готовый элемент получает собственный downloadUrl. У пакетной работы после сборки ZIP archive меняется с null на объект с размером и отдельным адресом скачивания.

Поле archive у готового пакетного задания

"archive": {
  "sizeBytes": 1672148,
  "downloadUrl": "/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe/download?target=archive"
}

GET/api/v1/conversions/{id}/download?target=<itemId|archive>

Отдаёт готовый файл потоком с заголовком Content-Disposition: attachment.

targetquery, необязательное: Идентификатор элемента задания (поле items[].id) — вернётся один файл. Значение archive — ZIP со всеми результатами задания.

Надёжнее использовать items[].downloadUrl или archive.downloadUrl из свежего ответа статуса. Параметр target можно опустить только для собранного архива либо одного готового результата; неоднозначный выбор отвечает ошибкой 400.

Один результат

curl -o photo.jpg \
  -H "Authorization: Bearer $API_KEY" \
  "https://convertare.ru/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe/download?target=K9r2LsPq7Wt1Ub3Ndf5Gxa"

Весь пакет одним архивом

curl -o results.zip \
  -H "Authorization: Bearer $API_KEY" \
  "https://convertare.ru/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe/download?target=archive"

Ответы этого адреса не кешируются. После истечения срока хранения запрос вернёт ошибку expired, а не пустой файл.

DELETE/api/v1/conversions/{id}

Удаляет файлы задания досрочно, не дожидаясь автоматической уборки.

Запрос

curl -X DELETE https://convertare.ru/api/v1/conversions/Qd4vT8nH2sLpXw0Ymc6Rbe \
  -H "Authorization: Bearer $API_KEY"

Ответ 200

{ "ok": true }

Хорошая привычка для интеграций: забрали результат — удалите задание. Ссылка на скачивание перестаёт работать сразу.

GET/api/v1/formats

Полный список форматов каталога — тот же, что на странице «Все форматы».

Запрос

curl https://convertare.ru/api/v1/formats \
  -H "Authorization: Bearer $API_KEY"

Фрагмент ответа 200

{
  "formats": [
    {
      "id": "heic",
      "slug": "heic",
      "name": "HEIC",
      "fullName": "High Efficiency Image Coding",
      "category": "image",
      "extensions": ["heic"],
      "mimeTypes": ["image/heic", "image/heic-sequence"],
      "summary": "Формат снимков iPhone: кадр, сжатый кодеком HEVC в контейнере HEIF, — вдвое легче JPEG при том же качестве.",
      "url": "/heic/",
      "popularity": 85,
      "binary": true,
      "multipage": true,
      "transparency": true,
      "lossy": true,
      "group": null,
      "aliases": [],
      "targets": ["jpg", "png", "pdf", "webp"],
      "sources": []
    }
  ]
}

GET/api/v1/conversions?from=&to=&category=

Направления конвертации с ограничениями, настройками и признаком доступности.

fromquery, необязательное: Идентификатор исходного формата: from=heic вернёт все направления из HEIC.
toquery, необязательное: Идентификатор целевого формата. Вместе с from даёт одно направление.
categoryquery, необязательное: Раздел каталога: image, document, video, audio, spreadsheet, ebook, archive, vector, data, font.

Поле available учитывает и переключатель администратора, и наличие программы-движка на сервере. Если оно равно false, задание создать не получится — запрос вернёт conversion_disabled или engine_unavailable.

Запрос

curl "https://convertare.ru/api/v1/conversions?from=json&to=yaml" \
  -H "Authorization: Bearer $API_KEY"

Ответ 200

{
  "conversions": [
    {
      "id": "json-to-yaml",
      "from": {
        "id": "json",
        "slug": "json",
        "name": "JSON",
        "fullName": "JavaScript Object Notation",
        "category": "data",
        "extensions": ["json"],
        "mimeTypes": ["application/json", "text/json", "application/x-json"],
        "summary": "Текстовый формат структурированных данных — стандарт де-факто для веб-API и настроек."
      },
      "to": {
        "id": "yaml",
        "slug": "yaml",
        "name": "YAML",
        "fullName": "YAML Ain't Markup Language",
        "category": "data",
        "extensions": ["yaml", "yml"],
        "mimeTypes": ["application/yaml", "text/yaml", "application/x-yaml", "text/x-yaml"],
        "summary": "Формат данных, рассчитанный на чтение человеком: структура задаётся отступами, а не скобками."
      },
      "url": "/json-to-yaml/",
      "title": "Конвертер JSON в YAML",
      "batch": true,
      "maxFileSizeBytes": 33554432,
      "available": true,
      "options": []
    }
  ]
}

GET/api/health

Принимает ли узел трафик прямо сейчас.

Запрос

curl https://convertare.ru/api/health

Ответ 200

{
  "ok": true,
  "status": "ok"
}

Ответ намеренно короткий: ok и status (ok или degraded), код 200 или 503. Недоступность отдельного движка сервис не выключает — ok становится false только при неисправности базы или очереди; доступность конкретного направления показывает поле available в GET /api/v1/conversions. Состав сервера — версии движков, окружение, драйверы — публично не отдаётся: эти подробности видны только с самой машины и администратору в панели.

Ошибки

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

Любой метод /api/v1 сначала проверяет платный Bearer-ключ. Нет заголовка, ключ неверен, отозван или подписка закончилась — обработчик не запускается, ответ имеет статус 401 и заголовок WWW-Authenticate.

Ответ без действующего Bearer-ключа

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Conversion API", charset="UTF-8"
Cache-Control: private, no-store, max-age=0
Vary: Authorization
Content-Type: application/json; charset=utf-8

{
  "error": {
    "code": "unauthorized",
    "message": "Для программного API нужен действующий ключ платного тарифа в заголовке Authorization: Bearer."
  }
}

Тело ответа при ошибке

{
  "error": {
    "code": "file_too_large",
    "message": "Файл больше допустимого размера. Уменьшите его или разбейте на части."
  }
}

Коды ошибок, типичный HTTP-статус и значение
Код	HTTP	Когда возникает
`unauthorized`	401	Заголовок Authorization отсутствует, Bearer-ключ неверен или отозван либо платная подписка больше не действует.
`invalid_request`	400	JSON-тело не соответствует схеме метода, слишком велико или не может быть разобрано.
`unsupported_conversion`	400	Такой пары форматов в реестре нет. Сверьте conversionId с ответом GET /api/v1/conversions.
`conversion_disabled`	403	Направление существует, но выключено администратором. Появится в ответе как available: false.
`engine_unavailable`	503 / 507	Программа, выполняющая преобразование, не установлена или не отвечает. Повторять запрос бессмысленно до восстановления.
`file_too_large`	413	Файл больше предела для своей категории. Предел направления возвращается в maxFileSizeBytes.
`invalid_file`	400	Файл не читается: пустое тело, обрезанная загрузка, неизвестная структура.
`format_mismatch`	415	Сигнатура файла не совпадает с форматом направления: например, в задание heic-to-jpg подан PNG.
`corrupted_input`	422	Файл распознан, но повреждён внутри — движок не смог его разобрать.
`timeout`	504	Обработка не уложилась в отведённое направлению время. Уменьшите файл или разбейте задание.
`engine_failed`	500	Движок завершился ошибкой. Подробности пишутся в журнал сервера, наружу не отдаются.
`empty_output`	500	Результат оказался пустым — обычно это следствие повреждённого или нестандартного исходника.
`internal_error`	500	Непредвиденный сбой сервиса. Имеет смысл повторить позже.
`rate_limited`	429	Превышена частота загрузок или число одновременных заданий с одного клиента.
`expired`	410	Срок хранения истёк: файлы задания уже удалены с сервера.
`not_found`	400 / 404 / 409	Задания или результата с таким идентификатором нет — либо он уже удалён.

HTTP-статус указан как ориентир — опирайтесь на поле code. Ошибка одного файла в пакетном задании не отменяет остальные: задание завершится, а у неудачного элемента будут заполнены errorCode и errorMessage.

Ограничения

Общий потолок загрузки — 512 МБ на файл. Предел конкретного направления меньше или равен ему и возвращается в поле maxFileSizeBytes; таблица по разделам каталога есть в условиях использования.
До 50 файлов в задании, до 10 одновременных заданий и до 60 загрузок в час с одного клиента. Час считается скользящим окном. При превышении приходит rate_limited: в тексте ошибки указано, через сколько минут освободится слот, то же значение в секундах — в заголовке Retry-After. Ждите его, а не повторяйте запрос в цикле.
Файлы и результаты удаляются через 24 часа после создания задания. Ссылки на скачивание после этого возвращают expired.
Программный API входит только в платный тариф Convertare за 199 ₽ в месяц и принимает файлы до 512 МБ. В браузере предел без входа — 5 МБ, у бесплатного аккаунта — 64 МБ; эти варианты не дают доступа к /api/v1.

Нужен другой лимит, свой формат или стабильный доступ под нагрузкой — напишите на hello@convertare.ru. Каталог направлений расширяется записью в реестре, поэтому конкретная просьба обычно выполнима.