كيفية إزالة خلفية الصور باستخدام API

إزالة خلفية صورة يدويًا تستغرق بضع دقائق لكل صورة. أما فعل ذلك لكل صورة منتج أو صورة ملف شخصي أو صورة مصغّرة تُرفع في تطبيقك فيحتاج إلى واجهة API لإزالة الخلفية: طلب HTTP واحد يدخل، وصورة مقصوصة جاهزة تخرج.

يشرح هذا الدليل كيفية دمج هذه الواجهة بالشكل الصحيح. ستحصل على أكواد cURL وPython وJavaScript جاهزة للتشغيل، وخيارات الإخراج التي تستحق المعرفة، وطريقة التعامل مع الصور البطيئة والمهام الجماعية، وكيفية إعادة المحاولة دون أن تدفع مرتين. تستخدم الأمثلة removebackground.dev، وهو منتج شقيق لنا، لكن الأنماط نفسها تنطبق على أي مزود.

كيف تعمل واجهة API لإزالة الخلفية

ترسل صورة، فيشغّل المزود نموذج تجزئة يفصل العنصر الرئيسي عن الخلفية، وتحصل على صورة جديدة. جوهر النتيجة هو قناة ألفا: قيمة لكل بكسل تحدد مقدار انتماء البكسل إلى العنصر الرئيسي. البكسلات المعتمة تمامًا هي العنصر، والبكسلات الشفافة تمامًا هي الخلفية، والقيم بينهما تتعامل مع الحواف الناعمة مثل الشعر والفرو والزجاج.

من هذا القناع يمكن للواجهة أن تعيد عدة أشياء:

• صورة مقصوصة شفافة، وعادةً PNG أو WebP بعد إزالة الخلفية
• العنصر على لون خالص، مدمجًا في JPG للمتاجر الإلكترونية التي تشترط خلفية بيضاء
• القناع نفسه، صورة بتدرج الرمادي يمكنك استخدامها في خط التركيب الخاص بك
• نسخة مقصوصة أو معاد تحجيمها، مقطوعة حول العنصر ومضبوطة على حجم محدد

الطلب هو الجزء السهل. التكامل في بيئة الإنتاج عليه أيضًا التعامل مع الصور التي تستغرق وقتًا أطول من المعتاد، والدفعات الكبيرة، وحدود المعدل، وإعادة المحاولة، وإبقاء مفتاح API بعيدًا عن المستخدمين.

ما الذي تبحث عنه في واجهة API لإزالة الخلفية

قبل أن تكتب الكود، تحقق من هذه النقاط مقابل صورك وحجم استخدامك.

الخطوة 1: أنشئ مفتاح API

سجّل في removebackground.dev وأنشئ مفتاحًا من صفحة حسابك. تحصل الحسابات الجديدة على 50 رصيدًا مجانيًا، وهذا يكفي لتشغيل الأمثلة أدناه والاختبار على صورك.

احفظ المفتاح في متغير بيئة على خادمك:

export REMOVEBG_API_KEY="your_api_key"

كل استدعاء يرسل المفتاح في الترويسة x-api-key، وكل استدعاء يستهلك رصيد ذلك الحساب. أنشئ مفتاحًا منفصلًا لكل تطبيق أو بيئة حتى تتمكن من إلغاء أحدها دون تعطيل البقية.

الخطوة 2: أزل الخلفية باستخدام cURL

نقطة النهاية الفورية هي POST https://removebackground.dev/v1/remove. أسرع اختبار هو رفع ملف:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

معظم الصور المفردة تعود جاهزة في الاستجابة نفسها، عادةً خلال ثوانٍ قليلة، كصورة PNG شفافة بالدقة الكاملة.

تقبل نقطة النهاية الصورة بأربع طرق. أرسل واحدة منها:

إذا حمل الطلب أكثر من طريقة، تكون الأولوية لـ image_file، ثم image_file_b64، ثم image_url، ثم الجسم الخام. يمكن إرسال الخيارات كحقول نموذج أو مفاتيح JSON أو قيم في سلسلة الاستعلام.

أمر واحد يجب الانتباه إليه: الخيار -o يحفظ جسم الاستجابة مهما كانت الحالة. إذا كان المفتاح خاطئًا أو الصورة غير صالحة، فإن ملف "PNG" لديك هو في الحقيقة خطأ بصيغة JSON. تحقق من رمز الحالة قبل أن تثق بالملف.

الخطوة 3: تعامل مع 200 و202 والأخطاء في Python

لا تستطيع واجهة إزالة الخلفية أن تضمن انتهاء كل صورة خلال طلب HTTP واحد. عندما يكون الطابور مزدحمًا على غير العادة وتستغرق صورة أكثر من نحو 55 ثانية، تجيب removebackground.dev بـ 202 Accepted مع معرّف مهمة بدلًا من الصورة. تستمر المهمة في العمل، وتجلب النتيجة باستخدام المعرّف.

القاعدة الأساسية: لا تُعد إرسال الصورة أبدًا بعد 202. فذلك يبدأ مهمة ثانية وقد يكلّف رصيدًا ثانيًا. إليك نسخة Python كاملة ترسل الصورة مرة واحدة ولا تعيد إلا الاستدعاءات الآمنة:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY
    # One key per image: a retry with the same key returns the same job, never a second charge.
    idem = {"Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url},
                         headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)

    if res.status_code != 202:
        return save(res, stem)  # 200 is the image; anything else raises

    # 202: still processing. Wait for the same job.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check /v1/jobs/{job_id} later.")


print(remove_background("https://example.com/photo.jpg"))

يحتاج الكود إلى Python 3 ومكتبة requests (pip install requests). هناك تفصيلان يسهل إغفالهما. أولًا، إيقاف السكربت لا يوقف المهمة: قد تنتهي ويُحتسب رصيدها، وتظهر النتيجة في Studio الخاص بحسابك. ثانيًا، تجيب GET /v1/jobs/:id/result بـ 409 not_ready أثناء تشغيل المهمة، فتعامل معها على أنها "انتظر" وليست فشلًا.

الخطوات نفسها في JavaScript (Node.js)

الخطوات نفسها في Node.js 18 أو أحدث، باستخدام fetch وFormData وBlob المدمجة، مع رفع ملف محلي:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

تقبل الواجهة طلبات CORS، وهذا مفيد للأدوات والاختبار. لكن ذلك لا يجعل استدعاءها من صفحة ويب تحتوي على مفتاحك آمنًا. المزيد عن ذلك في قسم الأمان أدناه.

الخطوة 4: تحكّم في الإخراج

معظم التطبيقات لا تريد صورة مقصوصة خامًا بالدقة الكاملة. تريد صورة منتج مربعة على خلفية بيضاء، أو معاينة صغيرة، أو قناعًا. طلب الملف النهائي من الواجهة مباشرة يوفر عليك خطوة معالجة ثانية. هذه هي خيارات /v1/remove:

كل خيار يكلّف الرصيد الواحد نفسه، والمعاملات غير المعروفة تُتجاهل بصمت، لذلك لن يسبب خطأ إملائي أي رسالة خطأ. هكذا تبدو صورة مربعة لمتجر إلكتروني مع المنتج في المنتصف وهامش 10%:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

تحمل الاستجابة الناجحة أيضًا ترويسات مفيدة. تعرض X-Credits-Remaining رصيدك بعد معالجة الصورة. وتوضح X-Matte-Confidence (من 0 إلى 1) مدى حسم القناع، وتعطي X-Matte-Ambiguous-Ratio نسبة البكسلات الناعمة مثل الشعر أو الزجاج أو ضبابية الحركة. تسجيل هاتين القيمتين يتيح لك تمييز الصور المقصوصة منخفضة الثقة لمراجعتها بشريًا بدلًا من فحص كل صورة.

الخطوة 5: عالج الصور بالجملة

لاستيراد الكتالوجات ومعالجة البيانات القديمة، لا ترسل مئات الطلبات المفردة. تضع POST /v1/batch حتى 100 رابط صورة عام في الطابور كمهمة واحدة، بالخيارات نفسها الموجودة في /v1/remove، وتجيب بـ 202 فورًا:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

بعض القواعد من الوثائق التي يجب أن تبني حولها:

• تنتهي حالة المهمة بأحد الأوضاع succeeded أو partial (فشلت بعض الصور) أو failed. لكل عنصر في items حالته الخاصة، ورمز خطأ عند الفشل.
• الإدخالات التي ليست روابط http(s) والروابط المكررة تُحذف ولا تُحتسب أبدًا. إذا كان أي من العددين أكبر من 0، فطابق النتائج عبر input بدلًا من الموضع.
• يمكن أن تكون لديك 3 مهام batch مفتوحة كحد أقصى لكل حساب. تتوقف الدفعة عن الاحتساب بمجرد أن تصبح done قيمتها true.
• إذا نفد الرصيد في منتصف الدفعة، تبقى الصور المنتهية مدفوعة، ويُعلَّم الباقي بأنه skipped مع out_of_credits دون أي تكلفة.
• لا تحتوي الواجهة على نقطة نهاية للإلغاء أو webhooks أو تنزيل ZIP، لذا فالاستعلام الدوري هو النمط المعتمد. قراءة المهمة مجانية ولا تخضع لحد المعدل.

تفضّل سكربتًا جاهزًا للتشغيل كما هو؟ يشرح دليل المعالجة الجماعية بـ Python سير عمل كاملًا من مجلد إلى مجلد.

الخطوة 6: أعد المحاولة بأمان وحافظ على فوترة متوقعة

مهلات الشبكة هي مصدر الخصم المزدوج. يستسلم العميل، ثم يعيد المحاولة، فتوجد الآن مهمتان لصورة واحدة. الحل هو الترويسة Idempotency-Key: أي سلسلة فريدة حتى 255 حرفًا، مثل UUID، واحدة لكل صورة أو دفعة. إذا أرسلت الطلب نفسه مرة أخرى بالمفتاح نفسه، تحصل على المهمة التي أنشأها الطلب الأول، مع الترويسة Idempotent-Replayed: true، ودون خصم جديد. إعادة استخدام مفتاح لصورة مختلفة تعيد 409 idempotency_key_reused.

تتبع الفوترة قاعدة بسيطة: رصيد واحد عند نجاح الصورة، ولا شيء عند فشلها. الطلبات المرفوضة قبل المعالجة، والصور غير القابلة للقراءة، والإخفاقات بعد محاولات المزود نفسه مجانية، وتنزيل نتيجة جاهزة مرة أخرى مجاني ما دامت مخزنة.

الحدود التي يجب مراعاتها في التصميم

إذا احتجت إلى أكثر من 60 صورة في الدقيقة، فنقطة النهاية batch هي الحل: طلب واحد يغطي حتى 100 صورة. خزّن النتائج في حاوية التخزين الخاصة بك فور تنزيلها، لأن روابط النتائج تجيب بـ 410 بعد 48 ساعة. ووفقًا لوثائق المزود، لا تُستخدم الصور المرفوعة لتدريب النماذج.

الانتقال من واجهة remove.bg

ينتهي موقع remove.bg المستقل وواجهة الخدمة الذاتية في 1 ديسمبر 2026 الساعة 09:00 بتوقيت CET. تنتقل واجهته إلى Leonardo.Ai، وهذا يتطلب تغيير التكامل لديك. إذا كنت تفضّل ألا تعيد كتابة أي شيء، فإن removebackground.dev توفر نقطة نهاية متوافقة مع remove.bg، والانتقال سطر واحد:

تحتفظ بالترويسة X-Api-Key نفسها (مع مفتاح removebackground.dev)، وأسماء المعاملات نفسها، وترويسات الاستجابة نفسها، وصيغة الأخطاء نفسها:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

اعرف الفروق قبل أن تنتقل:

• لا يوجد 202. تنتظر نقطة النهاية المتوافقة حتى 110 ثوانٍ، ثم تعيد مهلة 503. تستمر المهمة وتُحتسب إذا نجحت، لذا فإن إعادة ذلك الطلب دون تفكير تبدأ مهمة ثانية.
• لا توجد مفاتيح idempotency في نقطة النهاية هذه. إذا احتجت إلى إعادة محاولة آمنة، فانتقل إلى /v1/remove تدريجيًا.
• بعض الخيارات مقبولة لكنها تُتجاهل: type وtype_level (يُكتشف العنصر تلقائيًا)، وsemitransparency، وخيارات الظل (لا تُضاف ظلال).
• الحجم دائمًا برصيد واحد، بما في ذلك الدقة الكاملة.

يتضمن دليل الانتقال كودًا قبل التغيير وبعده لـ cURL وPython وNode وPHP، إضافة إلى خطوات لـ Zapier وMake وn8n.

أبقِ مفتاح API بعيدًا عن جهة العميل

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

• لتمكين مستخدميك من إزالة الخلفيات، أرسل صورهم عبر الخادم الخلفي واستدعِ الواجهة من هناك.
• أضف تسجيل دخول خاصًا بك وحدودًا للإنفاق لكل مستخدم في ذلك الخادم.
• استخدم مفتاحًا واحدًا لكل تطبيق أو بيئة.
• إذا تسرّب مفتاح، فألغه من صفحة الحساب. يتوقف عن العمل فورًا. يخزّن المزود تجزئة كل مفتاح فقط، لذا أنشئ مفتاحًا جديدًا بدلًا من محاولة استعادة القديم.

مثال: صور مقصوصة للصور المصغّرة في YouTube

إذا كنت تبني أدوات لصنّاع المحتوى، فالصور المصغّرة استخدام واضح. تُشاهَد الصورة المصغّرة غالبًا بحجم صغير، لذا يجب أن تحملها الصورة المقصوصة: وجه واحد أو منتج واحد، كبير، بحافة واضحة على خلفية بسيطة. يوصي YouTube بمقاس 3840 x 2160 px بنسبة 16:9 وعرض أدنى 640 px، ويقبل JPG أو PNG حتى 50 MB من الكمبيوتر، لكن 2 MB فقط من تطبيق الجوال.

من جهة الواجهة، يكفي استدعاء واحد يعيد PNG شفافة مقصوصة حول العنصر، جاهزة لوضعها على لوحة بنسبة 16:9:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

التقط صورة ثابتة للقص بدلًا من أخذ لقطة من الفيديو، لأن اللقطات غالبًا ما تكون مشوشة بسبب الحركة، واترك الزاوية السفلية اليمنى فارغة لأن YouTube يعرض مدة الفيديو هناك. تغطي صفحة الصور المصغّرة في YouTube جانب التصميم، ويشرح دليلنا للحصول على أول 1,000 مشترك لماذا تهم الصور المصغّرة إلى هذا الحد.

إزالة الخلفيات من ChatGPT أو Claude أو Cursor

ليست كل مهمة بحاجة إلى كود. تشغّل removebackground.dev أيضًا خادم MCP على https://removebackground.dev/mcp، فيمكنك رفع صورة في ChatGPT أو Claude أو Cursor أو VS Code أو n8n وطلب إزالة خلفيتها. في Claude Code يكفي أمر واحد:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

ثم اكتب /mcp في Claude Code لتسجيل الدخول. يوفر الخادم ثلاث أدوات: remove_background، وget_job لعمليات الإزالة التي تستغرق أكثر من بضع ثوانٍ، وcheck_credits. تكلّف كل صورة رصيدًا واحدًا، كما في الواجهة.

كم التكلفة

تعمل removebackground.dev بنظام الدفع حسب الاستخدام دون اشتراك. لا تنتهي صلاحية الرصيد، والصور الفاشلة مجانية، وتحصل الحسابات الجديدة على 50 رصيدًا مجانيًا. عبر الواجهة، يعادل الرصيد الواحد عملية إزالة خلفية ناجحة واحدة بالدقة الكاملة.

الأسعار بالدولار الأمريكي، ويمكن استرداد الرصيد غير المستخدم خلال 30 يومًا. تتوفر أسعار للكميات الأكبر من Scale عند الطلب. راجع صفحة الأسعار للتفاصيل الحالية.

الخلاصة

يتلخص التكامل المتين لإزالة الخلفية في بضع عادات: أبقِ المفتاح على خادمك، وتحقق من الحالة قبل حفظ الجسم، وانتظر المهمة بدلًا من إعادة الإرسال بعد 202، وأرسل Idempotency-Key مع كل طلب POST، واستخدم نقطة النهاية batch للعمل الجماعي.

المرجع الكامل، بما في ذلك مواصفة OpenAPI 3.1، موجود في وثائق API. وإذا كنت تعمل مع الفيديو إلى جانب الصور، فإن مقارنتنا لواجهات API لنصوص YouTube ودليل دمج تحويل الكلام إلى نص يستخدمان أنماط الإنتاج نفسها مع النصوص.