نقطة نهاية تحسين الصور البرمجية
المرجع التقني الرسمي لنقطة نهاية معالجة الصور الأساسية POST /v1/optimize.
نقطة النهاية الأساسية لتحسين الصور وتحويل تنسيقاتها وتقليص أبعادها وتعديل مقاساتها هي:
POST https://api.smallpict.app/v1/optimize
(الاسم المستعار: POST https://api.smallpict.app/v1/convert)
تنسيق الطلب (حزمة بيانات JSON)
POST /v1/optimize HTTP/1.1Host: api.smallpict.appX-API-Key: sp_sdk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0bX-Timestamp: 1716301234X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7aContent-Type: application/jsonIdempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5fمخطط نص الطلب
{ "filename": "hero-banner.jpg", "mime_type": "image/jpeg", "filesize": 1654200, "options": { "format": "avif", "quality": 80, "max_dimension": 1600, "max_width": 1920, "max_height": 1080, "lossless": false, "strip_metadata": true }}| الحقل | النوع | إلزامي | الوصف |
|---|---|---|---|
filename | string | نعم | اسم الملف الأصلي للصورة (مثل banner.png) |
mime_type | string | نعم | نوع MIME (مثل image/jpeg، image/png، image/webp) |
filesize | integer | نعم | الحجم الإجمالي للملف بالبايت (يجب أن يكون > 0) |
options.format | string | لا | التنسيق المستهدف: avif، webp، original / keep، jpg، png (افتراضي: webp) |
options.quality | integer | لا | جودة الضغط بين 1 و 100 (افتراضي: 80) |
options.max_dimension | integer | لا | تقييد تناسبي للحد الأقصى للضلع الأطول بالبكسل (مثل 1600، 1920، 2048، 2560) |
options.max_width | integer | لا | الحد الأقصى للعرض بالبكسل |
options.max_height | integer | لا | الحد الأقصى للارتفاع بالبكسل |
options.lossless | boolean | لا | تفعيل الضغط بدون فقدان (افتراضي: false) |
options.strip_metadata | boolean | لا | حذف بيانات الكاميرا الوصفية EXIF وملف الألوان (افتراضي: true) |
معلمات التحويل المباشر للصور
تقبل مسارات التحويل السحابي المباشرة معلمات الاستعلام للتحويل السريع وتعديل الحجم:
GET https://api.smallpict.app/v1/transform?url=...&format=webp&quality=80&max_dimension=1600
?format=avif|webp|original?quality=1..100?max_dimension=1600?max_width=1920?max_height=1080
استجابة الخادم (200 OK)
عند نجاح الإعداد، يُرجع SmallPict رابط رفع موقع مسبقاً آمناً ومعرّف تتبع المهمة:
{ "upload_url": "https://upload.smallpict.app/uploads/a1b2c3d4/hero-banner.jpg?signature=...", "job_id": "job-a1b2c3d4", "object_key": "uploads/a1b2c3d4/hero-banner.jpg", "status": "queued"}ارفع بايتات الصورة إلى upload_url بطلب HTTP PUT، ثم تحقق من حالة المهمة. استخدم رابط الرفع الآمن كما ورد في الاستجابة تمامًا، فهو ينتهي بعد مدة قصيرة ويصلح لهذا الرفع فقط.
التحقق من حالة المهمة
يمكن الاستعلام عن تقدم عملية التحويل عبر:
GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4
استجابة اكتمال المهمة (200 OK)
{ "job_id": "job-a1b2c3d4", "status": "completed", "url": "https://cdn.smallpict.app/opt/hero-banner.avif", "format": "avif", "bytes_saved": 1456200, "savings_percentage": 88.03, "created_at": "2026-08-23T08:00:00Z", "updated_at": "2026-08-23T08:00:01Z"}