Если вы программист

Как обратиться к конвертеру из программы

Всё, что делает страница конвертера, можно сделать из своей программы через /api/v1. Для этого нужны платный тариф и Bearer-ключ; ответы приходят в JSON. На самом сайте конвертер остаётся бесплатным и работает без регистрации.

Команды /api/v1 работают у Fileza только после оплаты тарифа. Скопируйте ключ в личном кабинете и добавляйте его как Authorization: Bearer. Для ручного перевода файла ничего покупать не надо: конвертер на странице по-прежнему открыт без API-ключа.

Коротко

Куда обращаться: https://fileza.ru/api/v1
Нужен ли ключ: Да: Authorization: Bearer <API_KEY>, только платный тариф
Что приходит в ответ: JSON; сам готовый файл скачивается как обычный файл
Сколько живёт файл: Столько же, сколько на сайте: 24 часа
Сколько можно прислать: До 512 МБ на файл и до 50 файлов за раз

Что за чем

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

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

Практический маршрут

Рецепт первого рабочего скрипта

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

Сначала спросите у каталога, есть ли нужный перевод и стоит ли у него available: true. Заодно посмотрите допустимый вес файла и названия настроек.
Отправьте файл, запомните его id, затем передайте этот номер в fileIds. Номер с другого сайта или другого аккаунта не подойдёт.
Не ждите готовый файл внутри POST-запроса: код 202 говорит только «принято». Периодически запрашивайте задание, пока оно не станет завершённым или не сообщит об ошибке.
Скачайте результат по готовой ссылке из JSON и сразу удалите задание. Если сервис просит подождать через Retry-After, выдержите эту паузу перед новой попыткой.

POST/api/v1/files

Забирает файлы, сам определяет, что это за файлы, и выдаёт им номера.

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

Сервис смотрит внутрь файла, а не на его название. Файл scan.jpg, внутри которого на самом деле PNG, будет опознан как PNG. Если распознать не удалось, поле format равно null, а список targets пустой — переводить нечего.

У только что принятого файла собственные часы: поле files[].expiresAt обычно указывает час вперёд. Как только создано задание, смотрите уже на job.expiresAt; платный вариант хранит работу 24 часа.

Запрос

curl -X POST https://fileza.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://fileza.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://fileza.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 перестаёт быть null. Для пачки ZIP описывается полем archive: там находятся размер архива и ссылка, которую можно сразу отдать curl.

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

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

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

Отдаёт готовый файл — браузер и curl сохранят его как обычную загрузку.

targetquery, необязательное: Номер файла из items[].id — придёт один результат. Слово archive — придёт ZIP со всем сразу.

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

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

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

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

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

Этот ответ не кешируется. Когда срок хранения вышел, придёт ошибка expired, а не пустой файл — так вы точно не сохраните пустышку вместо результата.

DELETE/api/v1/conversions/{id}

Убирает файлы сразу, не дожидаясь, пока это сделает уборка по расписанию.

Запрос

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

Ответ 200

{ "ok": true }

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

GET/api/v1/formats

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

Запрос

curl https://fileza.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://fileza.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://fileza.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.
Способ для программ входит только в платный тариф Fileza за 399 ₽ в месяц: файл может весить до 512 МБ. На сайте без входа можно загрузить до 5 МБ, с бесплатным аккаунтом — до 64 МБ; ключ и доступ к /api/v1 они не дают.

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