سرویس عکس فیلتر را بعد از دریافت از آپاستریم و قبل از تحویل به کاربر اعمال میکند. اگر کش روی همان قانون مسیر روشن باشد و پاسخ قابلکش باشد، خروجی تغییریافته میتواند کش شود.
نسخه فعلی x-img برابر v1 است.
برای اولین پردازش، اولین تصویر را با سرویس عکس تغییر دهید را دنبال میکنیم.
نحو
?x-img=v1/filter1,param1_val1,param2_val2/filter2,...
| جز | جداکننده | مثال |
|---|---|---|
| نسخه | شروع رشته | v1 |
| فیلترها | / | resize سپس format |
| پارامترهای یک فیلتر | , | w_100,h_100 |
| نام و مقدار پارامتر | _ | type_webp |
نمونه:
https://example.com/images/bird.jpg?x-img=v1/resize,w_100/format,type_webp
زنجیره از چپ به راست اجرا میشود. مثال: v1/grayscale/rotate,angle_90/resize,percent_50 اول خاکستری میکند، بعد ۹۰ درجه میچرخاند، بعد هر ضلع را نصف میکند.
محل تعریف رشته
| محل | رفتار |
|---|---|
| فیلتر با QueryString | رشته فیلتر از پارامتر x-img در URL خوانده میشود |
| فیلتر ثابت | همان نحو v1/... در فیلد commands؛ x-img نادیده گرفته میشود |
فیلتر ثابت درخواستهای GET یا HEAD منطبق با آن قانون مسیر را به پردازش تصویر میفرستد. اگر فایل تصویر نباشد، پردازش انجام نمیشود و ممکن است پاسخ اصلی بدون تغییر برگردد؛ وضعیت 200 بهتنهایی تایید پردازش نیست. این حالت را فقط روی مسیری میگذاریم که خروجیاش تصویر است.
فیلترها
resize
| پارامتر | بازه | پیشفرض | توضیح |
|---|---|---|---|
w | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | ۰ | عرض هدف؛ 0 یعنی عرض تعیین نشده است. |
h | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | ۰ | ارتفاع هدف؛ 0 یعنی ارتفاع تعیین نشده است. |
percent | ۰ تا ۱۰۰ | — | درصد اندازه ورودی؛ 0 تغییری ایجاد نمیکند و مقدار بیش از 100 به 100 محدود میشود. |
min | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | — | کوچک کردن ضلع کوچکتر تا مقدار هدف، با حفظ نسبت تصویر. |
max | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | — | کوچک کردن ضلع بزرگتر تا مقدار هدف، با حفظ نسبت تصویر. |
اگر فقط یکی از w یا h تعیین شود، نسبت تصویر حفظ میشود. اگر هر دو تعیین شوند، تصویر با حفظ نسبت کوچکنمایی میشود و از مرکز برش میخورد تا ابعاد هدف را پر کند؛ فضای سیاه اضافه نمیشود. ابعاد هدف به ابعاد ورودی محدود میشوند و resize تصویر را از اندازه ورودی بزرگتر نمیکند.
پارامتر force در نحو فعلی پشتیبانی نمیشود. حالتهای w/h، percent، min و max را در یک فیلتر ترکیب نمیکنیم؛ آخرین پارامتر مربوط به یک حالت، حالت پردازش را تعیین میکند.
bird.jpg?x-img=v1/resize,w_100,h_100
bird.jpg?x-img=v1/resize,w_400
bird.jpg?x-img=v1/resize,percent_50
bird.jpg?x-img=v1/resize,min_100
bird.jpg?x-img=v1/resize,max_100
crop
x و y نقطه شروع و w و h ابعاد ناحیه برش هستند. همه اختیاریاند، مقدار پیشفرض آنها 0 و بازه هرکدام ۰ تا ۱۰٬۰۰۰٬۰۰۰ است. مقدار 0 برای w یا h یعنی استفاده از اندازه تصویر در آن محور؛ ناحیه به مرز تصویر محدود میشود. ناحیهای که کاملا بیرون تصویر باشد، تغییری ایجاد نمیکند.
bird.jpg?x-img=v1/crop,x_200,y_70,w_100,h_100
rotate
angle زاویه چرخش بر حسب درجه است؛ مقدار منفی و اعشاری هم پذیرفته میشود. پیشفرض 0 است و بازه آن از منفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰ است.
bird.jpg?x-img=v1/rotate,angle_90
autorotate
اعمال EXIF Orientation. پارامتر ندارد.
bird.jpg?x-img=v1/autorotate
blur
بدون تعیین ناحیه، کل تصویر مات میشود. پارامترهای ناحیه مستقل و اختیاریاند و به مرز تصویر محدود میشوند.
| پارامتر | بازه | پیشفرض |
|---|---|---|
sigma | ۰ تا ۱۰۰۰ | ۱٫۵ |
x و y | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | ۰ |
w و h | ۰ تا ۱۰٬۰۰۰٬۰۰۰ | ۰؛ استفاده از اندازه تصویر در همان محور |
مقدار 0 برای sigma تصویر را تغییر نمیدهد.
bird.jpg?x-img=v1/blur
bird.jpg?x-img=v1/blur,sigma_5
bird.jpg?x-img=v1/blur,x_200,y_70,w_100,h_100,sigma_20
grayscale
پارامتر ندارد.
bird.jpg?x-img=v1/grayscale
format
| پارامتر | الزامی | مقادیر | پیشفرض |
|---|---|---|---|
type | خیر | png، webp، jpeg یا jpg | jpeg |
lossless | خیر | true / false | false؛ مربوط به خروجی WebP |
bird.jpg?x-img=v1/format,type_png
bird.jpg?x-img=v1/format,type_webp
watermark
واترمارک از یک تصویر دریافت میشود. پارامتر image آدرس کامل آن تصویر با کدگذاری Base64 مناسب URL، بدون padding (=) است. واترمارک متنی و پارامترهای text، t، color، dpi و size در نحو فعلی پشتیبانی نمیشوند.
| پارامتر | الزامی | بازه | پیشفرض | توضیح |
|---|---|---|---|---|
image | بله | آدرس تصویر با Base64-URL بدون padding | — | تصویر واترمارک |
x | خیر | منفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰ | ۰ | موقعیت افقی |
y | خیر | منفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰ | ۰ | موقعیت عمودی |
bird.jpg?x-img=v1/watermark,x_50,y_50,image_aHR0cHM6Ly9leGFtcGxlLmNvbS93YXRlcm1hcmsucG5n
optimize
کیفیت خروجی، حذف متادیتا، و در صورت پشتیبانی کلاینت تبدیل به WebP. lossless برای خروجی WebP بهصورت پیشفرض خاموش است. حجم خروجی به تصویر و تنظیمات وابسته است.
| پارامتر | الزامی | بازه | پیشفرض | توضیح |
|---|---|---|---|---|
q | خیر | ۰ تا ۱۰۰ | ۷۵ | کیفیت |
lossless | خیر | true / false | false | WebP بدون افت |
bg | خیر | R-G-B هر کانال ۰ تا ۲۵۵ | 0-0-0 | فقط وقتی خروجی JPEG است و ورودی شفاف است |
اگر هدر Accept شامل image/webp باشد خروجی WebP است؛ وگرنه JPEG یا PNG.
bird.jpg?x-img=v1/optimize,q_100,lossless_true,bg_255-255-255
فرمت خروجی
- بدون
formatو بدونoptimize: WebP ورودی اگر کلاینت WebP بپذیرد WebP میماند؛ وگرنه PNG. PNG و JPEG ورودی همان فرمت میمانند. بقیه JPEG. - با
format: مقدارtype. - با
optimize: strip؛ اگر کلاینت WebP بپذیرد WebP؛ وگرنه PNG برای ورودی WebP/PNG و JPEG برای بقیه. - چند
formatیاoptimize: آخرین فیلتر معیار است. تغییر فرمت بعد از بقیهی فیلترها اعمال میشود.
پذیرش WebP از هدر Accept خوانده میشود.
