बैकग्राउंड रिमूवल 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 तक पब्लिक इमेज URL, साथ में /v1/remove के कोई भी विकल्प। ऊपर दिए दो प्लेसहोल्डर URL अगर असली इमेज होते, तो 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) URL नहीं हैं और 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 है। अमान्य और दोहराए गए URL हटाने के बाद पोज़िशन आपकी सूची के क्रम में होती हैं, इसलिए जब इनमें से कोई भी गिनती 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 कुंजी अपने नियंत्रण वाले सर्वर पर रखें। इसे ब्राउज़र कोड, मोबाइल ऐप, पब्लिक रिपॉज़िटरी या URL में न डालें। अपने यूज़र्स को बैकग्राउंड हटाने देने के लिए, उनकी इमेज अपने बैकएंड से भेजें, और वहीं अपना साइन-इन और ख़र्च की सीमाएँ जोड़ें।

• API, CORS की अनुमति देता है ताकि यह टूल और सर्वर-साइड कोड से काम करे। इसका मतलब यह नहीं कि कुंजी को वेब पेज में डालना सुरक्षित है: वहाँ कोई भी उसे पढ़ सकता है।
• एक अकाउंट की सभी कुंजियाँ एक ही क्रेडिट बैलेंस ख़र्च करती हैं। अपने अकाउंट पेज पर हर ऐप या एनवायरनमेंट के लिए अलग कुंजी बनाएँ, ताकि आप दूसरों को प्रभावित किए बिना एक को रद्द कर सकें।
• अगर कोई कुंजी लीक हो जाए, तो उसे तुरंत अकाउंट पेज पर रद्द करें (वह उसी समय काम करना बंद कर देती है) और नई बनाएँ। हम हर कुंजी का सिर्फ़ हैश स्टोर करते हैं, इसलिए उसे आपको दोबारा नहीं दिखा सकते।

समस्या निवारण