Программный интерфейс

HTTP-интерфейс конвертера

Версионированный контур /api/v1 использует те же движки и очередь, что и сайт. Он доступен только на платном тарифе по Bearer-ключу; обмен — JSON в UTF-8, состояние задания опрашивает клиент. Браузерная конвертация остаётся доступной без оплаты.

Fileto открывает программные маршруты /api/v1 только платному аккаунту с активной подпиской. Сервисный процесс передаёт Authorization: Bearer в каждом запросе, а ключи обслуживаются на отдельной странице кабинета. Обычная работа через сайт остаётся без ключа.

Сводка

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

Эксплуатационная схема

Поток пакетного обработчика

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

Операция 1На старте процесса прочитайте каталоги форматов и направлений. Значение available отражает текущее состояние узла, поэтому его полезнее проверять перед партией, чем навечно сохранять в коде.
Операция 2Отправляйте входные объекты multipart-полями file и сохраните вернувшиеся идентификаторы. Они принадлежат тому же домену и аккаунту, который затем создаёт задание.
Операция 3POST задания быстро отвечает 202. Освободите HTTP-поток своего приложения и перенесите дальнейший опрос в очередь или планировщик; готовность определяется полями статуса, а не временем ожидания.
Операция 4Получив отдельные файлы или общий ZIP, удалите задание явным DELETE. Такой порядок сокращает срок хранения рабочих данных и не заставляет ждать автоматическую уборку.

Последовательность вызовов

Передайте содержимое — POST /api/v1/files. Ответ содержит идентификаторы принятых файлов и перечень форматов, достижимых из каждого.
Поставьте задание — POST /api/v1/conversions: идентификатор направления, идентификаторы файлов, значения параметров. Управление возвращается до начала обработки.
Читайте состояние — GET /api/v1/conversions/{id}. Рекомендуемый интервал опроса: 1 с в начале с нарастанием до 3 с; тот же алгоритм применяет интерфейс сайта.
Выгрузите результат — 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 — обычно час. Создание задания продлевает нужные источники, а окончательная граница для платного потока приезжает как job.expiresAt и составляет 24 часа.

Запрос

curl -X POST https://fileto.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://fileto.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://fileto.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 содержит sizeBytes вместе с адресом архива.

Поле 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 со всеми результатами.

Берите URL непосредственно из ответа задания: так параметр target уже заполнен без ручной склейки строк. Пустой target допустим для готового ZIP или единственного результата; при нескольких кандидатах сервер возвращает 400 и просит сделать выбор.

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

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

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

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

Ответы метода не кешируются. По истечении срока хранения возвращается expired; пустое тело в этом случае не отдаётся.

DELETE/api/v1/conversions/{id}

Досрочное удаление файлов задания до срабатывания уборщика.

Запрос

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

Ответ 200

{ "ok": true }

Штатный порядок для интеграции: выгрузили результат — удалите задание. Ссылка становится недействительной немедленно, дожидаться уборщика не требуется.

GET/api/v1/formats

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

Запрос

curl https://fileto.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://fileto.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://fileto.ru/api/health

Ответ 200

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

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

Коды ошибок

Форма ошибки одна для всех методов. Поле code предназначено программе и входит в закрытый перечень, поле message — текст на русском без внутренних подробностей, пригодный для показа пользователю без обработки.

Проверка доступа предшествует чтению тела каждого /api/v1-запроса. Отсутствующий, просроченный, неверный или отозванный ключ, как и завершившаяся подписка, дают одинаковый 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	Сигнатура содержимого не соответствует исходному формату направления — например, PNG подан в задание heic-to-jpg.
`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.
Программный интерфейс входит только в платный тариф Fileto за 299 ₽ в месяц: один файл — до 512 МБ. Браузер без входа принимает до 5 МБ, бесплатный аккаунт — до 64 МБ; оба уровня не имеют доступа к /api/v1.

Требуется иной предел, отсутствующее направление или предсказуемая доступность под нагрузкой — напишите на mail@fileto.ru. Реестр направлений расширяется одной записью, поэтому предметный запрос обычно выполним.