Изображения

Чтобы преобразовать изображение, необходимо сделать запрос к файлу с параметрами. Сервис создаст новый файл, отправит его ответом на запрос и сохранит в ваше хранилище.

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

Пример:

// создать новое изображение с шириной 100px с сохранением пропорций
https://api.defaultuploader.com/v1/image/upload/token/sample.jpg?w=100

width

alias: w

Создает изображение с заданной шириной с правильными пропорциями.

min 0, max 5000

w=100

w=200

w=300

height

alias: h

Создает изображение с заданной высотой с правильными пропорциями.

min 0, max 5000

h=100

h=200

h=300

format

alias: f

Изменяет формат изображения.

Поддерживаемые форматы
JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG, HEIC

auto Скоро

Автоматическое определение поддержки браузером современных форматов изображений.

quality

alias: q

min 0, max 100 значение по умолчанию = 75

Изменить качество изображения.

q=100

q=1

dpr

1, 2 — по умолчанию 1

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

w=100&dpr=1

w=100&dpr=2

animated

alias: a

animated=0

Отключить анимацию у giff или webp

animated=0

fit

Как следует изменить размер/обрезать изображение, чтобы оно соответствовало целевому размеру(ам).

cover, contain, fill, inside, outside

h=200&w=500&fit=contain

h=200&w=500&fit=cover

h=200&w=500&fit=fill

h=200&w=500&fit=inside

h=200&w=500&fit=outside

bg

Устанавливает цвет фона при использовании fit=contain. Пустое пространство вокруг изображения заполняется указанным цветом вместо чёрного.

Формат: 6-символьный hex-цвет без #
Пример: bg=ffffff, bg=1a1a2e

h=200&w=500&fit=contain&bg=228be6

PWA Splash Screen

Используйте bg вместе с fit=contain для генерации splash screen из одного логотипа. Фон будет заполнен цветом вашего бренда.

pad

Добавляет отступ вокруг изображения в процентах от размера канваса. Работает только с fit=contain.

min 0, max 50 (проценты)

w=512&h=512&fit=contain&pad=20&bg=228be6

PWA Maskable Icons

Maskable-иконки требуют ~20% safe zone по краям. Используйте pad=20 вместе с bg для генерации maskable-иконок из одной квадратной иконки.

func

Умный кроп. face и auto при помощи ИИ находят лицо или «интересное» место на изображении и обрезают его по центру. manual не использует детекцию и кадрирует вокруг точки фокуса, заданной через pos_x/pos_y — эта точка помещается в центр кропа, а обрамление задаётся zoom, целевым соотношением сторон из w/h и обработкой краёв через pos_edge.

face, auto, manual

h=500&w=500&func=face

h=500&w=500&func=manual&pos_x=50&pos_y=35&zoom=1.5

h=500&w=500

crop

Вырезает произвольный прямоугольник исходного изображения, в процентах — без детекции. Формат: x,y,w,h, где x/y — отступ левого верхнего угла, а w/h — размер области, каждое от 0 до 100.

x,y,w,h — каждое 0–100 (проценты); x+w ≤ 100, y+h ≤ 100

Сочетайте с w/h, чтобы затем отресайзить вырезанную область. crop не требует детекции и берёт точную область, поэтому всегда имеет приоритет над func.

crop=0,0,50,50

crop=25,25,50,50&w=400&h=400

zoom

alias: z

Опциональный параметр для «умного» кропа (func). Регулирует, насколько плотно кадр обрамляет лицо.

min 0.1, max 10, step 0.1 — по умолчанию 1

Значения больше 1 приближают (более плотный кроп вокруг лица). Значения меньше 1 отдаляют, оставляя больше пространства вокруг лица — удобно для баннеров и широких раскладок. Когда при отдалении область выходит за границы изображения, поведение задаётся параметром pos_edge.

h=600&w=600&func=face&zoom=1

h=600&w=600&func=face&zoom=2

h=600&w=600&func=face&zoom=0.6

pos_x

alias: px

Горизонтальная позиция найденного лица в итоговом кадре, в процентах. Требует func=face. При func=manual вместо этого задаёт горизонтальную точку фокуса в исходном изображении (см. func).

min 0, max 100 — по умолчанию 50 (по центру)

pos_x=0 прижимает лицо к левому краю, pos_x=100 — к правому.

func=face&w=600&h=600&pos_x=20

func=face&w=600&h=600&pos_x=50

func=face&w=600&h=600&pos_x=80

pos_y

alias: py

Вертикальная позиция найденного лица в итоговом кадре, в процентах. Требует func=face. При func=manual вместо этого задаёт вертикальную точку фокуса в исходном изображении (см. func).

min 0, max 100 — по умолчанию 38 (золотое сечение)

Если не указан, лицо располагается примерно на 38% от верха (золотое сечение), смещаясь к центру для групповых фото.

func=face&w=600&h=600&pos_y=25

func=face&w=600&h=600&pos_y=50

pos_edge

Стратегия для области, выходящей за границы исходного изображения, когда кроп выходит за его края (например, при zoom < 1 или крайних значениях pos_x/pos_y). Требует func=face или func=manual.

fill, clamp, outpaint — по умолчанию fill

• fill — сохранить заданное обрамление и добить выходящую за края область цветом bg либо прозрачностью (белым для форматов без альфа-канала, например JPEG).
• clamp — сдвинуть кроп внутрь изображения, чтобы не было полей (позиция лица может немного сместиться).
• outpaint — дорисовать недостающий фон с помощью ИИ. heavy медленнее, обрабатывается в отдельной очереди.

func=face&w=1200&h=400&zoom=0.5&pos_edge=fill

func=face&w=1200&h=400&zoom=0.5&pos_edge=clamp

Баннер из любого фото

Сочетайте func=face с zoom < 1, широкими w/h и pos_edge=fill (плюс bg), чтобы превратить портрет в широкий баннер, удерживая лицо ровно там, где нужно.

blur

Создает размытое изображение

min 0.3, max 1000

blur=10

negate

Создает “негатив” изображение

?negate

negate

normalize_lower

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

min 1, max 99

normalize_lower=65

normalize_upper

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

min 1, max 99

normalize_upper=95

saturation

Установите насыщенность изображения

min 0.1

saturation=0.1

saturation=1.5

brightness

Установите яркость изображения

min 0.1

brightness=0.1

brightness=1.5

hue

Установите яркость изображения

min 1

hue=25

lightness

Установите тон изображения

min 0.1

lightness=30

greyscale

Преобразует изображение, сделав его черно-белым

?greyscale

greyscale

radius

Скругляет края изображения

min 0 max 100

rs=5

Чтобы создать круглое изображение, нужно установить равные стороны

rs=50&w=400&h=400

remove_background

alias: rm_bg

Удаляет фон на изображении

?rm_bg

rm_bg

rm_bg&func=face&z=2&rs=50

Просто создать аватарку

Добавьте параметры удаления фона, “умный” кроп, зум и скругления краев

super_resolution скоро

С помощью ИИ увеличивает разрешение изображения

download

Заставляет браузер скачать файл вместо открытия его инлайн — устанавливает заголовок ответа Content-Disposition: attachment. Работает с любым типом медиа и сочетается со всеми параметрами трансформации. Не влияет на закэшированный файл — ETag одинаков с download и без него.

?download              — скачать с исходным именем файла
?download=report.pdf   — скачать с произвольным именем

nostore

Выполняет запрошенную трансформацию и возвращает результат, не сохраняя вариацию в хранилище. Обработанное изображение отдаётся из временного кэша воркера и при этом кэшируется CDN (заголовок Cache-Control не меняется), поэтому повторные запросы остаются быстрыми — но новый объект в бакет не записывается. Подходит для разовых или превью-трансформаций, которые не нужно сохранять.

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

?width=300&nostore=1   — изменить размер, вернуть результат, НЕ сохранять вариацию
?width=300&nostore     — то же самое (достаточно наличия параметра)