API لإزالة الخلفية: طلب واحد، وصورة PNG جاهزة.

أرسل صورتك

يقبل POST /v1/remove الصورة بأي من أربع طرق. أرسل واحدة منها؛ وإذا تضمّن الطلب أكثر من واحدة، تكون الأولوية لـ image_file، ثم image_file_b64، ثم image_url، ثم جسم الطلب الخام. تقرأ هذه الأمثلة مفتاحك من متغير البيئة REMOVEBG_API_KEY (عيّنه بـ export REMOVEBG_API_KEY=…)؛ لاحظ علامات الاقتباس المزدوجة، التي تتيح للصدفة (shell) تعويض قيمته.

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

يحفظ كل مثال جسم الاستجابة في ملف. ولا يكون هذا الملف صورة إلا عندما تكون الحالة 200؛ راجع التعامل مع الاستجابة.

التعامل مع الاستجابة

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

مثال كامل

يتعامل مع الصورة الجاهزة، والاستجابة 202، والمهمة الفاشلة، وحدّ زمني محلي. يرسل الصورة مرة واحدة ولا يعيد المحاولة إلا في فحوص الحالة الآمنة.

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: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    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 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    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 it later at /v1/jobs/{job_id}.")


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

• إيقاف السكربت لا يوقف المهمة؛ فقد تكتمل وتُحتسب. وتظهر نتيجتها في الاستوديو.
• الحدود الزمنية من اختيارك، وليست وعدًا منا؛ تكتمل معظم الصور خلال ثوانٍ قليلة.
• نقطة النهاية المتوافقة مع remove.bg تتصرف بشكل مختلف: فهي لا ترد بـ 202 أبدًا (انظر أدناه).

الدفعات من البداية إلى النهاية

1. الإرسال

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

حتى 100 رابط صورة عام، مع أي من خيارات /v1/remove. سيكلّف الرابطان النموذجيان أعلاه حتى رصيدين لو كانا صورتين حقيقيتين. وتصل الإجابة فورًا:

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

يعدّ invalid المدخلات التي ليست روابط http(s)، ويعدّ duplicates المدخلات المكررة؛ ويُستبعد كلاهما ولا يُحتسب أبدًا. احفظ id: فهو وسيلتك لاستئناف متابعة المهمة بعد إعادة التشغيل.

2. استعلم عن المهمة

نفّذ GET /v1/jobs/:id كل بضع ثوانٍ إلى أن تصبح قيمة done هي true. تنتقل status من queued إلى processing، ثم تنتهي بـ succeeded أو partial (فشلت بعض الصور) أو failed. ويظهر العنصر الجاري إعادة محاولته بالحالة retrying.

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. نزّل كل نتيجة

نفّذ GET /v1/jobs/:id/result?item=N لكل عنصر ناجح (أو استخدم result_url الخاص به). item هو position بدءًا من الصفر. تتبع المواضع قائمتك بعد استبعاد الروابط غير الصالحة والمكررة، لذا عندما يكون أي من العددين أكبر من 0، طابِق النتائج حسب input وليس حسب الترتيب.

• تتوقف الدفعة عن الاحتساب ضمن حد الدفعات المفتوحة البالغ 3 بمجرد أن تصبح done بقيمة true.
• لا يوفر API نقطة نهاية للإلغاء ولا webhooks ولا تنزيل ZIP. ويمكن إلغاء الدفعات التي بدأت من صفحة المعالجة المجمّعة أو تنزيلها كملف ZIP من هناك.

إعادة المحاولة والتكرار والفوترة

أرسل Idempotency-Key ولن تؤدي إعادة المحاولة إلى خصم مزدوج. أضف الترويسة Idempotency-Key (أي سلسلة فريدة حتى 255 حرفًا، مثل UUID) إلى POST /v1/remove أو POST /v1/batch، بمفتاح واحد لكل صورة أو دفعة. إذا أرسلت الطلب نفسه مرة أخرى بالمفتاح نفسه، تحصل على المهمة التي أنشأها الطلب الأول، مع Idempotent-Replayed: true: لا مهمة جديدة ولا خصم جديد، حتى لو كان الطلب الأول ما زال قيد التشغيل. أما المفتاح نفسه مع صورة أو خيارات مختلفة فيرد بـ 409 idempotency_key_reused. المفاتيح خاصة بحسابك ولا تنتهي صلاحيتها.

بدون مفتاح، ينشئ كل POST مهمة جديدة، وكل مهمة تنجح تكلّف رصيدًا واحدًا (نقطة النهاية المتوافقة مع remove.bg POST /v1.0/removebg لا تدعم المفاتيح). أما قراءة مهمة (GET /v1/jobs/…) فهي مجانية دائمًا وآمنة للتكرار.

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

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

ما الذي يستهلك رصيدًا

متى تعيد المحاولة

الحدود والتخزين

مدة الاحتفاظ بالنتائج

تُخزَّن كل نتيجة بشكل خاص في حسابك لمدة 48 ساعة بعد إنشائها، ثم تُحذف. وحتى ذلك الحين يمكنك تنزيلها مرة أخرى مجانًا عبر GET /v1/jobs/:id/result أو من الاستوديو. بعد ذلك، ترد روابط النتائج بـ 410 result_unavailable؛ ومعالجة الصورة مرة أخرى مهمة جديدة. وتبقى سجلات حالة المهام قابلة للقراءة بعد حذف الصورة. راجع سياسة الخصوصية لمعرفة كيفية التعامل مع الملفات المرفوعة؛ ونحن لا نستخدم صورك لتدريب النماذج.

الأمان

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

• يسمح API بـ CORS ليعمل من الأدوات والكود على جانب الخادم. لكن هذا لا يجعل وضع المفتاح في صفحة ويب آمنًا: إذ يمكن لأي شخص قراءته هناك.
• تستهلك كل مفاتيح الحساب الرصيد نفسه. أنشئ مفتاحًا منفصلًا لكل تطبيق أو بيئة من صفحة الحساب، لتتمكن من إلغاء أحدها دون تعطيل البقية.
• إذا تسرّب مفتاح، فألغِه فورًا من صفحة الحساب (يتوقف عن العمل في الحال) وأنشئ مفتاحًا جديدًا. لا نخزّن إلا قيمة مجزّأة (hash) لكل مفتاح، لذا لا يمكننا عرضه لك مرة أخرى.

حل المشكلات