المطورون

واجهة API لضغط الصور

اضغط JPG وPNG وWebP وAVIF عبر واجهة API لضغط الصور من Bitinz. صور أصغر في سير عملك، مع حصة شهرية مجانية لكل حساب.

المصادقة

أنشئ مفتاح API في لوحة التحكم، ثم استخدم مصادقة HTTP Basic (اسم المستخدم api، وكلمة المرور = المفتاح) أو أرسل Authorization: Bearer <key>.

curl --user api:YOUR_API_KEY ...
# or
curl -H "Authorization: Bearer YOUR_API_KEY" ...

ضغط صورة

أرسل الصورة بطريقة POST في جسم الطلب إلى /api/v1/shrink. معاملات الاستعلام الاختيارية: level (fast / default / best) وfilename.

curl -i --user api:YOUR_API_KEY \
  --data-binary @photo.jpg \
  "https://bitinz.com/api/v1/shrink?level=default&filename=photo.jpg"

الاستجابة

تُرجع الطلبات الناجحة عادةً 201 مع status بقيمة done. يشير ترويسة Location وoutput.url إلى التنزيل. وCompression-Count هو استخدامك هذا الشهر.

HTTP/1.1 201 Created
Location: https://bitinz.com/api/v1/results/<id>/download
Compression-Count: 1

{
  "id": "<id>",
  "status": "done",
  "input":  { "size": 2277375, "type": "image/jpeg" },
  "output": { "size": 992450, "type": "image/jpeg", "ratio": 0.436,
              "url": "https://bitinz.com/api/v1/results/<id>/download" },
  "unchanged": false,
  "expiresAt": "2026-10-02T12:00:00Z"
}

مقبول وفي الانتظار: 202

عند طول قائمة الانتظار قد تُرجَع 202 Accepted مع status بقيمة pending. يشير Location إلى حالة المهمة لا إلى التنزيل. احتفظ بهذا الرابط واستعلم عنه بدلًا من إرسال الصورة مرة أخرى.

HTTP/1.1 202 Accepted
Location: https://bitinz.com/api/v1/results/<id>

{
  "id": "<id>",
  "status": "pending",
  "input": { "size": 2277375 },
  "expiresAt": "2026-10-02T12:00:00Z"
}

الاستعلام عن حالة المهمة

أرسل GET /api/v1/results/{id} إلى الرابط المُعاد في Location كل 1–2 ثانية. تعني pending أن المهمة في الانتظار (ويحدد queuePosition موضعها الحالي)؛ وتعني processing أن الضغط جارٍ. عندما تصبح status بقيمة done، نزّل من downloadUrl. وتعني failed أن المهمة لم تكتمل؛ إذ يحدد failure الفئة ويشرح note السبب.

curl "https://bitinz.com/api/v1/results/<id>"

{
  "id": "<id>",
  "status": "done",
  "available": true,
  "downloadUrl": "/api/v1/results/<id>/download",
  "outputSize": 992450,
  "unchanged": false
}

تنزيل النتيجة

يمكن تنزيل النتائج حتى انتهاء صلاحيتها؛ وبعد ذلك يُرجع الرابط 410.

curl -o photo.min.jpg "https://bitinz.com/api/v1/results/<id>/download"

رموز الأخطاء

{ "error": { "code": "...", "message": "..." } }

401 unauthorized / invalid_key	المفتاح مفقود أو غير معروف أو مُبطل
413 too_large	الصورة تتجاوز حد الحجم
415 unsupported_image	المسار المتزامن: ليست صورة PNG أو JPEG أو WebP أو AVIF مدعومة
422 image_too_large	المسار المتزامن: عدد بكسلات الصورة يتجاوز ما يمكن للخدمة معالجته
failed / unsupported	تُبلغ المهام في قائمة الانتظار عن الصور غير المدعومة في النتيجة بالقيمتين status: failed وfailure: unsupported
failed / too_large	تُبلغ المهام في قائمة الانتظار عن الصور التي تتجاوز حد المعالجة بالقيمتين status: failed وfailure: too_large
429 quota_exceeded	استُنفدت الحصة الشهرية
503 busy	الخادم مشغول، حاول مرة أخرى بعد قليل