Методы картинок
| Метод | Адрес | Кто вызывает | Начинает сессию |
|---|---|---|---|
| Уменьшенная копия по ID файла | GET /api/image/{resizeType}/{width}/{height}/{imageId} | гость и вошедший | нет |
| Уменьшенная копия по пути или URL | GET /api/image/{resizeType}/{width}/{height}?imagePath=... | гость и вошедший | нет |
Содержимое папки в /upload/ | GET /api/image/directory?path=/upload/... | гость и вошедший | нет |
Ресайз: тип и размер
resizeType — тип масштабирования:
| Тип | Что делает |
|---|---|
exact | масштабирует в прямоугольник width x height с сохранением пропорций, обрезая лишнее |
proportional | масштабирует с сохранением пропорций, размер ограничивается width x height |
proportionalAlt | то же, но за ширину берётся максимум из высоты и ширины; лучше обрабатывает вертикальные картинки |
width и height — размеры в пикселях, целые числа. Ответ — не JSON, а содержимое картинки с заголовками кеша браузера, поэтому адрес подставляется прямо в src.
По ID файла
ID файла Битрикса (например, из полей элемента):
<img src="https://example.ru/api/image/exact/200/200/1024"> curl -o preview.jpg "https://example.ru/api/image/exact/200/200/1024" По пути или URL
Когда ID файла нет, адрес передаётся параметром imagePath: путь на сайте (/upload/...) или полный URL.
<img src="https://example.ru/api/image/proportional/400/400?imagePath=/upload/iblock/abc/photo.jpg"> Исходник — JPEG, PNG или WebP. Внешний URL принимается только с хоста сайта, хоста папки UPLOAD или из списка разрешённых хостов (адреса локальной сети запрещены всегда).
Ошибки ресайза
{
"success": false,
"error": "Неизвестный тип ресайза: exact, proportional или proportionalAlt"
} | Статус | Когда |
|---|---|
| 400 | resizeType не exact, не proportional и не proportionalAlt (ресайз по пути); исходник не JPEG, PNG и не WebP |
| 403 | URL с хоста, которого нет в списке разрешённых |
| 404 | по адресу нет файла или он не картинка |
Каталог загрузок
GET /api/image/directory?path=/upload/brand/ — файлы папки для выбора в редакторе контента. Путь должен начинаться с /upload/ и лежать глубже самого /upload/: параметр path нужно передавать всегда (без него берётся сам /upload/ и ответ — 403). Выход через .. тоже запрещён (403).
{
"data": {
"0a1": ["/upload/iblock/0a1/upat2ucqeplyti3owxgl2y6tw6vt2qai.jpg"],
"0a2": ["/upload/iblock/0a2/a35rt5u0ozf3kopunldixcaz2af5wuvt.jpg"]
}
} Файлы папки — массив путей, вложенные папки — ключи с массивами их файлов. Глубина — 2 уровня: файлы папки и файлы вложенных папок; у папок третьего уровня остаются только названия (пустой массив). Если папки нет, data = []. Результат кешируется.
Где настраиваются хосты и файлы картинок
Настройки модуля -> вкладка «Основное»:
| Опция | На что влияет |
|---|---|
| «Хост папки UPLOAD, если файлы отдаются с другого адреса» | картинки с этого хоста ресайз считает своими |
| «Сайты, с которых /api/image может брать внешние картинки» | список хостов для внешних URL; допустимы маски, см. Маски хостов картинок |
| «Типы файлов в списке /api/image/directory» | расширения файлов, которые видны в каталоге |
Размеры картинок в ответах инфоблоков (анонс, детальная, MORE_PHOTO) задаются не здесь, а в наборе элемента: Состав ответа.
Ограничения ресайза
- Адреса ресайза по пути принимают путь только параметром
imagePath. - Часть ошибок приходит телом
{errors: [...]}, часть —{success: false, error: текст}(например, 403 каталога приходит в первой форме): читайте текст изerrorилиerrors[0].message.
Что почитать после картинок
- Состав ответа: размеры картинок набора
- Настройки модуля