📄 سرویس عکس

سرویس عکس فیلتر را بعد از دریافت از آپ‌استریم و قبل از تحویل به کاربر اعمال می‌کند. اگر کش روی همان قانون مسیر روشن باشد، خروجی تغییریافته کش می‌شود.

نسخه فعلی 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 نادیده گرفته می‌شود

فیلتر ثابت همه درخواست‌های منطبق با آن قانون مسیر را به پردازش تصویر می‌فرستد. اگر فایل عکس نباشد، پاسخ خطا است. این حالت را فقط روی مسیری می‌گذاریم که خروجی‌اش تصویر است.

فیلترها

resize

پارامتر	الزامی	بازه	پیش‌فرض	توضیح
w	اگر percent نباشد	از ۱ تا عرض تصویر	—	عرض خروجی
h	اگر percent نباشد	از ۱ تا ارتفاع تصویر	—	ارتفاع خروجی
force	خیر	true / t ، false / f	false	اگر false باشد نسبت حفظ می‌شود و فضای خالی سیاه پر می‌شود؛ true تصویر را stretch می‌کند
percent	خیر (اگر w و h باشند)	از ۱	—	اگر با w و h دریافت شود فقط percent اعمال می‌شود
min	خیر	—	—	ضلع کوچک‌تر برابر min؛ ضلع دیگر متناسب
max	خیر	—	—	ضلع بزرگ‌تر برابر max؛ ضلع دیگر متناسب

اگر فقط یکی از w یا h دریافت شود، نسبت حفظ می‌شود.

bird.jpg?x-img=v1/resize,h_100,w_100
bird.jpg?x-img=v1/resize,h_100,w_100,force_true
bird.jpg?x-img=v1/resize,w_400
bird.jpg?x-img=v1/resize,min_100
bird.jpg?x-img=v1/resize,max_100

crop

نقطه‌ی شروع x و y؛ اندازه خروجی w و h. همه الزامی‌اند.

پارامتر	بازه
x	از ۰ تا عرض تصویر
y	از ۰ تا ارتفاع تصویر
w	از ۱ تا عرض منهای x
h	از ۱ تا ارتفاع منهای y

bird.jpg?x-img=v1/crop,x_200,y_70,w_100,h_100

rotate

چرخش ساعت‌گرد. angle الزامی است: 90، 180 یا 270.

bird.jpg?x-img=v1/rotate,angle_90

autorotate

اعمال EXIF Orientation. پارامتر ندارد.

bird.jpg?x-img=v1/autorotate

blur

بدون x,y,w,h کل تصویر مات می‌شود. با این چهار پارامتر فقط همان ناحیه.

پارامتر	الزامی	بازه	پیش‌فرض
sigma	خیر	۱ تا ۱۰۰	۱۰
x	اگر یکی از x,y,w,h باشد بقیه هم باید باشند	از ۰ تا عرض	۰
y	همان	از ۰ تا ارتفاع	۰
w	همان	از ۱ تا عرض منهای x	عرض تصویر
h	همان	از ۱ تا ارتفاع منهای y	ارتفاع تصویر

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، jpg، tiff، gif

bird.jpg?x-img=v1/format,type_png
bird.jpg?x-img=v1/format,type_webp

watermark

اگر text و image هم‌زمان بیایند فقط image اعمال می‌شود. مقدار image و text باید Base64 مناسب URL باشد.

پارامتر	الزامی	بازه	پیش‌فرض	توضیح
image	اگر text نباشد	آدرس تصویر واترمارک، Base64-URL	—	تصویر روی اصلی
x	اگر image باشد	از ۰ تا عرض	—	فاصله از چپ
y	اگر image باشد	از ۰ تا ارتفاع	—	فاصله از بالا
text	اگر image نباشد	متن، Base64-URL	—	با image نیاید
t	خیر	۰ تا ۱۰۰	۱۰۰	کدری
color	خیر	هگز RGB (0000 تا FFFF)	FFFFFF	رنگ متن
dpi	خیر	از ۰	۱۰۰
size	خیر	از ۱	۱۲	اندازه قلم

bird.jpg?x-img=v1/watermark,x_50,y_50,image_base64UrlEncoded==
bird.jpg?x-img=v1/watermark,x_50,y_50,image_base64UrlEncoded==,t_10

optimize

کیفیت خروجی، حذف متادیتا، و در صورت پشتیبانی کلاینت تبدیل به WebP. lossless پیش‌فرض روشن است و حجم را تا حدود چهار برابر بالا می‌برد.

پارامتر	الزامی	بازه	پیش‌فرض	توضیح
q	خیر	۰ تا ۱۰۰	۶۰	کیفیت
lossless	خیر	true / false	true	بدون افت؛ حجم بیشتر
bg	خیر	R-G-B هر کانال ۰ تا ۲۵۵	—	فقط وقتی خروجی 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 خوانده می‌شود.

ادامه مسیر

• سرویس عکس چگونه کار می‌کند؟
• اولین تصویر را با سرویس عکس تغییر دهید
• قوانین مسیر
• مرجع
• سوالات متداول CDN و DNS