بیک گراؤنڈ ریموول API: ایک ریکویسٹ بھیجیں، تیار PNG پائیں۔

اپنی تصویر بھیجیں

POST /v1/remove تصویر کو چار میں سے کسی بھی طریقے سے لیتا ہے۔ ان میں سے ایک بھیجیں؛ اگر کسی ریکویسٹ میں کئی ہوں تو پہلے image_file، پھر image_file_b64، پھر image_url، پھر raw باڈی کو ترجیح ملتی ہے۔ یہ مثالیں آپ کی کی REMOVEBG_API_KEY انوائرنمنٹ ویری ایبل سے پڑھتی ہیں (اسے export REMOVEBG_API_KEY=… سے سیٹ کریں)؛ ڈبل کوٹس پر دھیان دیں، ان سے شیل ویلیو بھر پاتا ہے۔

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 سیکنڈ سے زیادہ لگیں، تو آپ کو اس کے بجائے job id کے ساتھ 202 Accepted ملتا ہے۔ جاب چلتی رہتی ہے: id سے اس کا نتیجہ حاصل کریں۔ تصویر دوبارہ بھیجنے سے دوسری جاب شروع ہوگی اور دوسرا کریڈٹ لگ سکتا ہے۔

ایک مکمل مثال

تیار تصویر، 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-compatible اینڈ پوائنٹ مختلف طریقے سے کام کرتا ہے: وہ کبھی 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 تک پبلک تصویری URLs، ساتھ میں /v1/remove کے کوئی بھی آپشنز۔ اوپر دیے گئے دو پلیس ہولڈر URLs اگر حقیقی تصاویر ہوتے تو 2 کریڈٹس تک لگتے۔ جواب فوراً آتا ہے:

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) URLs نہیں ہیں اور 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 ہے۔ غلط اور دہرائے گئے URLs ہٹانے کے بعد پوزیشنز آپ کی فہرست کی ترتیب میں ہوتی ہیں، اس لیے جب ان میں سے کوئی بھی گنتی 0 سے زیادہ ہو تو نتائج کو انڈیکس کے بجائے input سے ملائیں۔

• done true ہوتے ہی بیچ 3 کھلے بیچز کی حد میں شمار ہونا بند ہو جاتا ہے۔
• API میں کوئی cancel اینڈ پوائنٹ، webhooks یا ZIP ڈاؤن لوڈ نہیں ہے۔ بلک صفحے سے شروع کیے گئے بیچز وہیں منسوخ کیے جا سکتے ہیں یا ZIP میں ڈاؤن لوڈ کیے جا سکتے ہیں۔

دوبارہ کوشش، ڈپلیکیٹس اور بلنگ

Idempotency-Key بھیجیں، تاکہ دوبارہ کوشش پر دو بار چارج نہ لگے۔ POST /v1/remove یا POST /v1/batch میں ایک Idempotency-Key ہیڈر شامل کریں (255 حروف تک کی کوئی بھی منفرد اسٹرنگ، جیسے UUID)، ہر تصویر یا بیچ کے لیے ایک کی۔ اگر آپ وہی ریکویسٹ اسی کی کے ساتھ دوبارہ بھیجتے ہیں تو آپ کو پہلی ریکویسٹ سے بنی جاب ہی ملتی ہے، Idempotent-Replayed: true کے ساتھ: نہ نئی جاب، نہ نیا چارج، چاہے پہلی ریکویسٹ ابھی چل رہی ہو۔ اسی کی کے ساتھ مختلف تصویر یا آپشنز بھیجنے پر جواب 409 idempotency_key_reused ہوتا ہے۔ کیز آپ کے اکاؤنٹ کی ہوتی ہیں اور ختم نہیں ہوتیں۔

کی کے بغیر ہر POST ایک نئی جاب بناتا ہے، اور ہر کامیاب جاب پر 1 کریڈٹ لگتا ہے (remove.bg-compatible 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 کی اپنے کنٹرول والے سرور پر رکھیں۔ اسے براؤزر کوڈ، موبائل ایپس، پبلک ریپوزٹریز یا URLs میں نہ ڈالیں۔ اپنے صارفین کو بیک گراؤنڈ ہٹانے دینے کے لیے ان کی تصاویر اپنے بیک اینڈ کے ذریعے بھیجیں، اور وہیں اپنا سائن اِن اور خرچ کی حدود شامل کریں۔

• API، CORS کی اجازت دیتا ہے تاکہ یہ ٹولز اور سرور سائیڈ کوڈ سے کام کرے۔ اس کا مطلب یہ نہیں کہ کی کو ویب صفحے میں ڈالنا محفوظ ہے: وہاں کوئی بھی اسے پڑھ سکتا ہے۔
• ایک اکاؤنٹ کی تمام کیز ایک ہی کریڈٹ بیلنس خرچ کرتی ہیں۔ اپنے اکاؤنٹ کے صفحے پر ہر ایپ یا انوائرنمنٹ کے لیے الگ کی بنائیں، تاکہ آپ دوسروں کو متاثر کیے بغیر ایک کو منسوخ کر سکیں۔
• اگر کوئی کی افشا ہو جائے تو اسے فوراً اکاؤنٹ کے صفحے پر منسوخ کریں (وہ اسی وقت کام کرنا بند کر دیتی ہے) اور نئی بنائیں۔ ہم ہر کی کا صرف ہیش محفوظ کرتے ہیں، اس لیے اسے آپ کو دوبارہ نہیں دکھا سکتے۔

مسائل کا حل