واجهة bgCut.net API

أزِل الخلفيات من تطبيقاتك أو متاجرك أو مسارات المعالجة لديك بطلب HTTPS واحد.

عنوان URL الأساسي: https://bgcut.net/api/v1 · احصل على مفتاحك من مفاتيح API.

المصادقة

يجب أن يتضمن كل طلب مفتاح API الخاص بك في ترويسة X-Api-Key. تُنشأ المفاتيح وتُلغى من حسابك، ويمكن تسمية كل مفتاح لتتمكن من تدويرها لكل تطبيق على حدة.

X-Api-Key: bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

أو يمكنك إرساله كرمز Bearer: Authorization: Bearer bgc_…

POST /remove

أرسل الصورة كملف multipart أو كرابط URL أو بترميز base64. تكون الاستجابة افتراضيًا هي الصورة الناتجة (بصيغة ثنائية).

المعاملات

المعاملالنوعالوصف
image_filefileملف الصورة (multipart/form-data). JPG وPNG وWebP وGIF وBMP وTIFF؛ بحد أقصى 25 MB / 30 MP.
image_urlstringرابط URL عام للصورة لجلبها بدلًا من رفعها.
image_file_b64stringصورة بترميز base64 (مع البادئة data: اختياريًا).
sizeauto | preview | fullpreview = حتى 640 px (يستخدم حصتك الشهرية المجانية دون رصيد)؛ full = الدقة الأصلية (رصيد واحد)؛ auto (افتراضي) = full عند توفر رصيد، وإلا preview.
formatpng | jpg | webpتنسيق الإخراج. png يحافظ على الشفافية؛ وjpg يُدمج على bg_color (الافتراضي أبيض).
modelfast | hq | portraitfast (افتراضي، ~1 ث)، hq (جودة أعلى، أبطأ)، portrait (محسَّن لصور الأشخاص).
bg_colorstringلون الخلفية بصيغة Hex، مثل ‎#ffffff. اتركه فارغًا لخلفية شفافة.
bg_blurnumberالاحتفاظ بالخلفية الأصلية مع تمويهها بهذا النصف قطر بالبكسل (1–200)، مثل 25 للحصول على مظهر الوضع البورتريه. يتجاوز bg_color.
cropbooleanقص الناتج وفق الإطار المحيط بالعنصر.
crop_marginintegerهامش إضافي بالبكسل حول العنصر عند القص (0–200).
roistringمنطقة الاهتمام ككسور x,y,w,h ‏(0–1). يفحص الذكاء الاصطناعي داخل هذا المستطيل فقط، ويصبح كل ما خارجه شفافًا.
feathernumberتنعيم الحواف بهذا النصف قطر بالبكسل (0–5).
qualityintegerجودة JPG/WebP من 50 إلى 100 (الافتراضي 92).
responsebinary | jsonbinary (افتراضي) يُرجع الصورة؛ وjson يُرجع البيانات الوصفية مع الصورة بترميز base64.

الاستجابات

تُرجع الطلبات الناجحة رمز HTTP 200 مع بايتات الصورة وهذه الترويسات:

HTTP/1.1 200 OK
Content-Type: image/png
X-Credits-Charged: 1
X-Credits-Remaining: 149
X-Free-Remaining: 5
X-Width: 3000
X-Height: 2000
X-Image-Id: 1f3a…
X-Type: hd

باستخدام response=json تحصل على:

{
  "ok": true,
  "image": { "id": "1f3a…", "width": 3000, "height": 2000, "format": "png", "type": "hd", "bytes": 812345, "bbox": [120, 40, 2810, 1990], "data": "iVBORw0KGgo…" },
  "credits_charged": 1,
  "credits_remaining": 149,
  "free_remaining": 5
}

GET /account

curl https://bgcut.net/api/v1/account -H "X-Api-Key: bgc_…"

{ "ok": true, "email": "[email protected]", "credits": 149, "free_remaining": 5, "free_per_month": 5, "free_max_width": 640, "rate_limit_per_minute": 60 }

GET /images

يعيد آخر 100 صورة تمت معالجتها بمفاتيح API الخاصة بك، مع رابط للمحرر لتحسينها في المتصفح.

الأخطاء

تُعاد الأخطاء بتنسيق JSON مع رمز الخطأ ورسالة مفهومة:

{ "ok": false, "error": "insufficient_credits", "message": "No credits left. Buy credits at https://bgcut.net/pricing or request size=preview." }
HTTPerrorالوصف
400bad_request / missing_imageمعلمات مفقودة أو غير صالحة.
401auth_required / invalid_keyمفتاح API مفقود أو غير صالح أو ملغى.
402insufficient_credits / free_quota_exceededلا توجد أرصدة (للحجم الكامل) أو نفدت الحصة المجانية (للمعاينة).
422too_large / bad_type / fetch_failedتعذّرت قراءة الصورة أو تنزيلها.
429rate_limitedطلبات كثيرة جدًا – يُرجى الإبطاء أو التواصل معنا للحصول على حدود أعلى.
500processing_failedفشلت المعالجة من جانبنا – لن يتم خصم أي رسوم.

أمثلة برمجية

تستخدم جميع الأمثلة نقطة النهاية نفسها. نزّل مجموعة الأمثلة الكاملة: bgcut-api-examples.zip

الحدود

  • 60 طلب في الدقيقة لكل مفتاح API (حدود أعلى عند الطلب).
  • الحد الأقصى 25 ميغابايت و30 ميغابكسل لكل صورة؛ تُصغَّر الصور الأكبر حجمًا.
  • تُحفظ الصور المعالجة لمدة 30 يومًا ويمكن تحسينها في محرر الويب.
  • لا تُحتسب رسوم على الطلبات الفاشلة أبدًا؛ ويُسترد المبلغ تلقائيًا إذا فشل إنشاء الناتج.

ابدأ التكامل

أنشئ حسابًا مجانيًا، وولّد مفتاحًا، ونفّذ أول طلب لك في أقل من دقيقة.

احصل على مفتاح API الأسعار