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 עם job 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 מתנהגת אחרת: היא אף פעם לא עונה 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. שתי כתובות הדוגמה שלמעלה היו עולות עד 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), ו-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 יוצר משימה חדשה, וכל משימה שמצליחה עולה קרדיט אחד (ל-POST /v1.0/removebg התואם ל-remove.bg אין מפתחות). קריאת משימה (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. כדי לאפשר למשתמשים שלכם להסיר רקעים, העבירו את התמונות שלהם דרך ה-backend שלכם, והוסיפו שם התחברות ומגבלות הוצאה משלכם.

• ה-API מאפשר CORS כדי שיעבוד מכלים ומקוד בצד השרת. זה לא הופך את הכנסת המפתח לדף אינטרנט לבטוחה: כל אחד יכול לקרוא אותו שם.
• כל המפתחות בחשבון מנצלים את אותה יתרת קרדיטים. צרו מפתח נפרד לכל אפליקציה או סביבה בדף החשבון, כדי שתוכלו לבטל אחד בלי לשבור את האחרים.
• אם מפתח דלף, בטלו אותו מיד בדף החשבון (הוא מפסיק לעבוד מייד) וצרו חדש. אנחנו שומרים רק גיבוב (hash) של כל מפתח, ולכן לא נוכל להציג לכם אותו שוב.

פתרון בעיות