دليل الترحيل من واجهة remove.bg API

1

اقرأ هذا أولًا

الأمور الأربعة غير المتطابقة.

القيمة الافتراضية لـ size هي preview، كما في remove.bg — لكن preview هنا صورة مجانية بعلامة مائية حتى 640 px (remove.bg: 0.25 ميجابكسل بلا علامة مائية). وأي تكامل لا يضبط size أبدًا سيحصل على معاينات بعلامة مائية؛ مرّر size=auto أو فئة مدفوعة للحصول على النتيجة بلا علامة مائية.
نحن لا ندّعي توافقًا على مستوى SDK. اجتاز ثلاثة عملاء من أطراف ثالثة اختباراتنا في 22 سبتمبر 2026 — حزمة removebg على PyPI، وحزمة remove.bg الرسمية على npm، و removebg-cli — لكننا لا نختبرها ضد الانحدار إصدارًا بإصدار؛ عملاء HTTP المكتوبون يدويًا هم المسار الذي ندعمه.
تُقبَل shadow_type و shadow_opacity و add_shadow و semitransparency ويُتحقَّق منها، لكنها لا تغيّر المُخرَج إطلاقًا — كما في remove.bg مع الأهداف غير السيارات؛ ولا يوجد نموذج مخصّص للسيارات.
يُحتسب كل استدعاء صورةً واحدة ضمن حدّ مفتاحك البالغ 40 صورة في الدقيقة — بينما يسمح remove.bg بـ 500. تعامَل مع 429 عبر Retry-After، أو تواصل معنا لرفع الحد.

2

قبل وبعد

الطلب نفسه موجَّهًا إلى كل خدمة.

remove.bg

1curl -X POST "https://api.remove.bg/v1.0/removebg" \2  -H "X-Api-Key: REMOVEBG_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png

PixMiller

1curl -X POST "https://api.pixmiller.com/v1.0/removebg" \2  -H "X-Api-Key: PIXMILLER_KEY" \3  -F "[email protected]" \4  -F "size=auto" \5  -o out.png6# 200 OK → image bytes, written straight to out.png7# X-Credits-Charged: 1   X-Width: 1200   X-Height: 1600   X-Type: product

3

دعم المعاملات

المعامل	الحالة	ملاحظات
`image_file`	مطابق	رفع multipart. JPG / PNG / WebP، حتى 20 MB (remove.bg: 22 MB).
`image_url`	مطابق	عنوان URL عام للصورة، نجلبه من جهتنا بالحد نفسه البالغ 20 MB.
`image_file_b64`	مطابق	صورة مُرمَّزة بـ Base64 في جسم الطلب، تمامًا كما في remove.bg.
`size`	مختلف	القيم نفسها، والقيمة الافتراضية نفسها (preview)، وحدود الميجابكسل نفسها — لكن preview هنا صورة مجانية بعلامة مائية حتى 640 px، لا 0.25 ميجابكسل بلا علامة مائية. وتكلّف medium / hd / 4k / full / 50MP رصيدًا واحدًا لكل منها؛ أما auto فيستخدم الفئة المدفوعة ما دام هناك رصيد.
`format`	مطابق	auto / png / jpg / webp / zip — ويحتوي zip على color.jpg و alpha.png كما في remove.bg. وتُعيد Accept: application/json غلاف base64. ومخرجات PNG محدودة بـ 10 ميجابكسل.
`type, type_level`	مختلف	مقبول؛ ويُربَط type بنماذجنا الخاصة. وتُبلغ X-Type عن فئة عامة — person أو product أو animal أو car أو other — كما تُعيد type_level=2 و latest الفئات العامة نفسها.
`crop, crop_margin`	مطابق	يقصّ حول الهدف بصيغة الهوامش نفسها وبالحد الأقصى نفسه 50% / 500 px.
`roi`	مطابق	منطقة الاهتمام بالبكسل أو بالنسبة المئوية، كما في remove.bg.
`scale, position`	مطابق	حجم الهدف (10%–100% أو original) وموضعه، كما في remove.bg.
`channels`	مطابق	rgba (الافتراضي) أو alpha للقناع وحده.
`bg_color`	مطابق	شفافة افتراضيًا؛ قيمة ست عشرية من 3 / 4 / 6 / 8 خانات مع # أو بدونه، أو اسم لون.
`bg_image_file, bg_image_url`	مطابق	يُحجَّم ليغطي المُخرَج ويُتوسَّط؛ ولا يمكن دمجه مع bg_color.
`add_shadow, shadow_type, shadow_opacity`	بلا أثر	يُتحقَّق منها وفق قيم remove.bg، لكن لا يُرسَم أي ظل إطلاقًا.
`semitransparency`	بلا أثر	مقبول؛ المناطق شبه الشفافة تُعالَج تلقائيًا دائمًا.

يُتحقَّق من كل معامل وفق نطاقات القيم الخاصة بـ remove.bg، فتؤدي أي قيمة غير صالحة إلى 400 invalid_parameter بدلًا من تجاهلها بصمت — تمامًا كما يستجيب remove.bg.

4

ما يختلف سلوكه

رمز الحالة 200 OK مع بايتات الصورة، تمامًا كما في remove.bg — والشيفرة التي تتحقّق من == 200 تظل تعمل. (نقطة نهاية PixMiller الأصلية /api/v1/remove تُجيب بالرمز 201 مع JSON؛ أما مسار التوافق هذا فلا يفعل ذلك عن قصد.)

جسم الاستجابة بايتات الصورة، تمامًا كما في remove.bg. أرسل Accept: application/json للحصول على غلاف base64 الخاص بـ remove.bg بدلًا منها، أو استخدم format=zip للحصول على color.jpg مع alpha.png.

Response headers تُعاد كل الترويسات التالية: X-Credits-Charged و X-Width و X-Height و X-Type و X-Foreground-Top / -Left / -Width / -Height و X-RateLimit-Limit / -Remaining / -Reset. أما X-Type فهي فئة عامة (person / product / animal / car / other) وليست مفردات remove.bg الأدقّ.

الأخطاء تستخدم الأخطاء شكل JSON:API الخاص بـ remove.bg: {"errors":[{"title":"…","code":"…"}]} — أي مصفوفة، لذا يُقرأ errors[0].title كما كان تمامًا. المفتاح المفقود يعني 403 auth_failed والمفتاح الخاطئ 403 invalid_api_key، والرصيد الفارغ 402، والخنق 429.

أرصدة preview مجانية؛ وتكلّف كل فئة مدفوعة رصيدًا واحدًا لكل صورة، ولا يُخصم الرصيد إلا بعد جلب النتيجة، لذا لا يكلّف الاستدعاء الفاشل رصيدًا أبدًا. ولا توجد حصة شهرية مجانية.

حد المعدّل 40 صورة في الدقيقة لكل مفتاح (remove.bg: 500). يُحتسب كل استدعاء صورةً واحدة، وتعكس X-RateLimit-Limit / -Remaining / -Reset هذه الحصة المحسوبة بالصور؛ وتعامَل مع 429 عبر Retry-After.

5

التحقّق من رصيدك

تُبلغ نقطة نهاية الحساب عن رصيد المفتاح المتبقي ضمن data.attributes.credits، لذا يحتفظ أي فحص للرصيد مكتوب لأجل remove.bg بشكله نفسه. ولا توجد حصة شهرية مجانية، لذا تكون free_calls دائمًا 0.

GET /v1.0/account

1curl "https://api.pixmiller.com/v1.0/account" \2  -H "X-Api-Key: PIXMILLER_KEY"

6

الأخطاء

400 invalid_parameter قيمة خارج نطاق remove.bg لـ size / format / crop / scale / … أو مصدر صورة مفقود؛ ويذكر الحقل title اسم المعامل.

400 file_too_large حجم صورة الإدخال يتجاوز 20 MB.

400 unknown_foreground تعذّر العثور على أي عنصر أمامي في الصورة.

402 insufficient_credits طُلبت فئة مدفوعة لكن الرصيد فارغ. لا يُخصم شيء.

403 auth_failed / invalid_api_key ترويسة X-Api-Key مفقودة (auth_failed) أو خاطئة (invalid_api_key) — الرمز 403 كما في remove.bg، لا 401.

429 rate_limit_exceeded تم تجاوز حد المعدّل. أعد المحاولة بعد المدة المذكورة في ترويسة Retry-After.

502 result_fetch_failed تعذّر جلب النتيجة من التخزين. لم يُخصم شيء — أعد إرسال الطلب.

رمز الحالة هو ما يحمل المعنى، وتستخدم الشيفرة مفردات remove.bg نفسها — لذا يظل أي تفريع على errors[0].code يعمل.

بديل remove.bg تواصل معنا