واجهة bgCut.net API
أزِل الخلفيات من تطبيقاتك أو متاجرك أو مسارات المعالجة لديك بطلب HTTPS واحد.
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_file | file | ملف الصورة (multipart/form-data). JPG وPNG وWebP وGIF وBMP وTIFF؛ بحد أقصى 25 MB / 30 MP. |
image_url | string | رابط URL عام للصورة لجلبها بدلًا من رفعها. |
image_file_b64 | string | صورة بترميز base64 (مع البادئة data: اختياريًا). |
size | auto | preview | full | preview = حتى 640 px (يستخدم حصتك الشهرية المجانية دون رصيد)؛ full = الدقة الأصلية (رصيد واحد)؛ auto (افتراضي) = full عند توفر رصيد، وإلا preview. |
format | png | jpg | webp | تنسيق الإخراج. png يحافظ على الشفافية؛ وjpg يُدمج على bg_color (الافتراضي أبيض). |
model | fast | hq | portrait | fast (افتراضي، ~1 ث)، hq (جودة أعلى، أبطأ)، portrait (محسَّن لصور الأشخاص). |
bg_color | string | لون الخلفية بصيغة Hex، مثل #ffffff. اتركه فارغًا لخلفية شفافة. |
bg_blur | number | الاحتفاظ بالخلفية الأصلية مع تمويهها بهذا النصف قطر بالبكسل (1–200)، مثل 25 للحصول على مظهر الوضع البورتريه. يتجاوز bg_color. |
crop | boolean | قص الناتج وفق الإطار المحيط بالعنصر. |
crop_margin | integer | هامش إضافي بالبكسل حول العنصر عند القص (0–200). |
roi | string | منطقة الاهتمام ككسور x,y,w,h (0–1). يفحص الذكاء الاصطناعي داخل هذا المستطيل فقط، ويصبح كل ما خارجه شفافًا. |
feather | number | تنعيم الحواف بهذا النصف قطر بالبكسل (0–5). |
quality | integer | جودة JPG/WebP من 50 إلى 100 (الافتراضي 92). |
response | binary | json | binary (افتراضي) يُرجع الصورة؛ و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." }
| HTTP | error | الوصف |
|---|---|---|
| 400 | bad_request / missing_image | معلمات مفقودة أو غير صالحة. |
| 401 | auth_required / invalid_key | مفتاح API مفقود أو غير صالح أو ملغى. |
| 402 | insufficient_credits / free_quota_exceeded | لا توجد أرصدة (للحجم الكامل) أو نفدت الحصة المجانية (للمعاينة). |
| 422 | too_large / bad_type / fetch_failed | تعذّرت قراءة الصورة أو تنزيلها. |
| 429 | rate_limited | طلبات كثيرة جدًا – يُرجى الإبطاء أو التواصل معنا للحصول على حدود أعلى. |
| 500 | processing_failed | فشلت المعالجة من جانبنا – لن يتم خصم أي رسوم. |
أمثلة برمجية
تستخدم جميع الأمثلة نقطة النهاية نفسها. نزّل مجموعة الأمثلة الكاملة: bgcut-api-examples.zip
الحدود
- 60 طلب في الدقيقة لكل مفتاح API (حدود أعلى عند الطلب).
- الحد الأقصى 25 ميغابايت و30 ميغابكسل لكل صورة؛ تُصغَّر الصور الأكبر حجمًا.
- تُحفظ الصور المعالجة لمدة 30 يومًا ويمكن تحسينها في محرر الويب.
- لا تُحتسب رسوم على الطلبات الفاشلة أبدًا؛ ويُسترد المبلغ تلقائيًا إذا فشل إنشاء الناتج.
ابدأ التكامل
أنشئ حسابًا مجانيًا، وولّد مفتاحًا، ونفّذ أول طلب لك في أقل من دقيقة.
احصل على مفتاح API الأسعار