איך להסיר רקע מתמונות עם API

הסרת רקע ידנית לוקחת כמה דקות לכל תמונה. כדי לעשות את זה לכל העלאת מוצר, תמונת פרופיל או תמונה ממוזערת באפליקציה שלכם צריך API להסרת רקע: בקשת HTTP אחת נכנסת, תמונה גזורה ומוכנה יוצאת.

המדריך הזה מראה איך לשלב API כזה כמו שצריך. תקבלו קוד עובד ב־cURL, Python ו־JavaScript, את אפשרויות הפלט שכדאי להכיר, איך לטפל בתמונות איטיות ובמשימות בכמויות, ואיך לנסות שוב בלי לשלם פעמיים. הדוגמאות משתמשות ב־removebackground.dev, מוצר אחות שלנו, אבל הדפוסים מתאימים לכל ספק.

איך עובד API להסרת רקע

אתם שולחים תמונה, הספק מריץ מודל סגמנטציה שמפריד את האובייקט מהרקע, ומקבלים בחזרה תמונה חדשה. הליבה של התוצאה היא ערוץ אלפא: ערך לכל פיקסל שאומר כמה מהפיקסל שייך לאובייקט. פיקסלים אטומים לגמרי הם האובייקט, פיקסלים שקופים לגמרי הם רקע, והערכים שביניהם מטפלים בקצוות רכים כמו שיער, פרווה וזכוכית.

מתוך המסכה הזו, ה־API יכול להחזיר כמה דברים:

• גזירה שקופה, בדרך כלל PNG או WebP בלי רקע
• האובייקט על צבע אחיד, משוטח ל־JPG עבור מרקטפלייסים שדורשים רקע לבן
• המסכה עצמה, תמונה בגווני אפור שאפשר להשתמש בה בתהליך הקומפוזיציה שלכם
• גרסה חתוכה או מוקטנת, מותאמת לאובייקט ולגודל מדויק

הבקשה היא החלק הקל. שילוב בסביבת פרודקשן צריך גם להתמודד עם תמונות שלוקחות יותר זמן מהרגיל, אצוות גדולות, מגבלות קצב, ניסיונות חוזרים ושמירה על מפתח ה־API הרחק מהמשתמשים.

מה לבדוק ב־API להסרת רקע

לפני שכותבים קוד, בדקו את הנקודות האלה מול התמונות והתעבורה שלכם.

שלב 1: צרו מפתח API

הירשמו ב־removebackground.dev וצרו מפתח בדף החשבון. חשבונות חדשים מקבלים 50 קרדיטים בחינם, מספיק כדי להריץ את הדוגמאות שלמטה ולבדוק על התמונות שלכם.

שמרו את המפתח במשתנה סביבה בשרת:

export REMOVEBG_API_KEY="your_api_key"

כל קריאה שולחת את המפתח בכותרת x-api-key, וכל קריאה צורכת את הקרדיטים של אותו חשבון. צרו מפתח נפרד לכל אפליקציה או סביבה, כדי שתוכלו לבטל אחד בלי לשבור את האחרים.

שלב 2: הסרת רקע עם cURL

ה־endpoint בזמן אמת הוא 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 שקוף ברזולוציה מלאה.

ה־endpoint מקבל את התמונה בארבע דרכים. שלחו אחת מהן:

אם בקשה כוללת כמה מהם, image_file גובר, אחריו image_file_b64, אחריו image_url, ואחריו הגוף הגולמי. אפשר לשלוח אפשרויות כשדות טופס, מפתחות JSON או ערכי query string.

דבר אחד לשים לב אליו: -o שומר את הגוף בלי קשר לסטטוס. אם המפתח שגוי או שהתמונה לא תקינה, ה"PNG" שלכם הוא בעצם שגיאת JSON. בדקו את קוד הסטטוס לפני שסומכים על הקובץ.

שלב 3: טיפול ב־200, 202 ושגיאות ב־Python

API להסרת רקע לא יכול להבטיח שכל תמונה תסתיים בתוך בקשת 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"))

ה־API מקבל בקשות CORS, וזה שימושי לכלים ולבדיקות. זה לא הופך את הקריאה מדף אינטרנט שהמפתח שלכם נמצא בו לבטוחה. עוד על כך בפרק האבטחה שלמטה.

שלב 4: שליטה בפלט

רוב האפליקציות לא רוצות גזירה גולמית ברזולוציה מלאה. הן רוצות תמונת מוצר ריבועית על רקע לבן, תצוגה מקדימה קטנה או מסכה. כשמבקשים מה־API את הקובץ הסופי, נחסך שלב עיבוד נוסף. אלה האפשרויות של /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 כתובות URL ציבוריות של תמונות כמשימה אחת, עם אותן אפשרויות כמו /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 משימות אצווה פתוחות לחשבון. אצווה מפסיקה להיספר כש־done הוא true.
• אם הקרדיטים נגמרים באמצע אצווה, התמונות שהסתיימו נשארות משולמות והשאר מסומנות כמדולגות עם out_of_credits, בלי חיוב.
• ל־API אין endpoint לביטול, אין webhooks ואין הורדת ZIP, ולכן הדפוס הוא בדיקה חוזרת (polling). קריאת משימה היא בחינם ולא כפופה למגבלת קצב.

מעדיפים סקריפט שאפשר להריץ כמו שהוא? המדריך לעיבוד באצוות עם Python עובר על תהליך מלא מתיקייה לתיקייה.

שלב 6: ניסיונות חוזרים בטוחים וחיוב צפוי

timeouts ברשת הם המקור לחיובים כפולים. הלקוח שלכם מוותר, מנסה שוב, ועכשיו יש שתי משימות לתמונה אחת. הפתרון הוא כותרת Idempotency-Key: כל מחרוזת ייחודית באורך של עד 255 תווים, למשל UUID, אחת לכל תמונה או אצווה. אם שולחים שוב את אותה בקשה עם אותו מפתח, מקבלים את המשימה שהבקשה הראשונה יצרה, עם הכותרת Idempotent-Replayed: true, ובלי חיוב חדש. שימוש חוזר במפתח עבור תמונה אחרת מחזיר 409 idempotency_key_reused.

החיוב פועל לפי כלל פשוט: קרדיט אחד כשתמונה מצליחה, כלום כשהיא נכשלת. בקשות שנדחו לפני העיבוד, תמונות שלא ניתן לקרוא וכשלים אחרי הניסיונות החוזרים של הספק עצמו הם בחינם, והורדה חוזרת של תוצאה מוכנה היא בחינם כל עוד היא שמורה.

מגבלות שצריך לתכנן סביבן

אם אתם צריכים יותר מ־60 תמונות בדקה, ה־endpoint של האצוות הוא הפתרון: בקשה אחת מכסה עד 100 תמונות. שמרו את התוצאות ב־bucket משלכם מיד כשאתם מורידים אותן, כי אחרי 48 שעות קישורי התוצאות מחזירים 410. לפי התיעוד של הספק, תמונות שהועלו לא משמשות לאימון מודלים.

מעבר מה־API של remove.bg

האתר העצמאי וה־API בשירות עצמי של remove.bg מסתיימים ב־1 בדצמבר 2026, בשעה 09:00 CET. ה־API שלו עובר ל־Leonardo.Ai, וזה מחייב לשנות את השילוב שלכם. אם אתם מעדיפים לא לכתוב שום דבר מחדש, ל־removebackground.dev יש endpoint תואם 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. ה־endpoint התואם מחכה עד 110 שניות ואז מחזיר timeout מסוג 503. המשימה ממשיכה לרוץ ומחויבת אם היא מצליחה, כך שניסיון חוזר עיוור של הבקשה הזו מתחיל משימה שנייה.
• אין מפתחות idempotency ב־endpoint הזה. אם אתם צריכים ניסיונות חוזרים בטוחים, עברו עם הזמן ל־/v1/remove.
• חלק מהאפשרויות מתקבלות אבל לא משפיעות: type ו־type_level (האובייקט מזוהה אוטומטית), semitransparency ואפשרויות הצל (לא מתווספים צללים).
• כל גודל עולה קרדיט אחד, כולל רזולוציה מלאה.

מדריך המעבר כולל קוד לפני ואחרי עבור cURL, Python, Node ו־PHP, וגם שלבים עבור Zapier, Make ו־n8n.

שמרו את מפתח ה־API מחוץ לצד הלקוח

זו הטעות שעולה כסף אמיתי. אם המפתח שלכם נמצא בדף אינטרנט, באפליקציה, במאגר קוד ציבורי או בכתובת URL, כל אחד יכול לקרוא אותו ולבזבז את הקרדיטים שלכם.

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

דוגמה: גזירות לתמונות ממוזערות ביוטיוב

אם אתם בונים כלים ליוצרים, תמונות ממוזערות הן שימוש מתבקש. תמונה ממוזערת נראית בעיקר בגודל קטן, ולכן הגזירה צריכה לשאת אותה: פנים או מוצר אחד, גדולים, עם קצה ברור מול רקע פשוט. YouTube ממליץ על 3840 x 2160 px ביחס 16:9 עם רוחב מינימלי של 640 px, ומקבל JPG או PNG עד 50 MB מהמחשב, אבל רק 2 MB מהאפליקציה.

בצד ה־API זו קריאה אחת שמחזירה 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 מציג את אורך הסרטון. הדף על תמונות ממוזערות ליוטיוב מכסה את צד העיצוב, והמדריך שלנו להשגת 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. כל תמונה עולה קרדיט אחד, כמו ב־API.

כמה זה עולה

removebackground.dev עובד בתשלום לפי שימוש, בלי מנוי. הקרדיטים לא פגים, תמונות שנכשלו לא מחויבות, וחשבונות חדשים מקבלים 50 קרדיטים בחינם. דרך ה־API, קרדיט אחד הוא הסרת רקע מוצלחת אחת ברזולוציה מלאה.

המחירים בדולר אמריקאי (USD), וקרדיטים שלא נוצלו ניתנים להחזר תוך 30 יום. תמחור לכמויות מעל Scale זמין לפי בקשה. ראו את דף המחירים לפרטים העדכניים.

לסיכום

שילוב טוב של API להסרת רקע מסתכם בכמה הרגלים: שמרו את המפתח בשרת, בדקו את הסטטוס לפני ששומרים את הגוף, חכו למשימה במקום לשלוח שוב אחרי 202, שלחו Idempotency-Key עם כל POST, והשתמשו ב־endpoint של האצוות לעבודה בכמויות.

התיעוד המלא, כולל מפרט OpenAPI 3.1, נמצא בתיעוד ה־API. אם אתם עובדים גם עם וידאו ולא רק עם תמונות, ההשוואה שלנו בין APIs לתמלול YouTube ומדריך השילוב של המרת דיבור לטקסט משתמשים באותם דפוסי פרודקשן עבור טקסט.