API ลบพื้นหลัง: ส่งคำขอเดียว ได้ PNG ที่เสร็จแล้วกลับมา

ส่งรูปของคุณ

POST /v1/remove รับรูปได้สี่วิธี ส่งวิธีใดวิธีหนึ่ง หากคำขอมีหลายแบบ image_file จะได้ก่อน ตามด้วย image_file_b64, image_url และ raw body ตัวอย่างเหล่านี้อ่านคีย์จากตัวแปรสภาพแวดล้อม 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

ทุกตัวอย่างบันทึก body ลงไฟล์ ไฟล์นั้นจะเป็นรูปภาพก็ต่อเมื่อสถานะเป็น 200 เท่านั้น ดูจัดการการตอบกลับ

จัดการการตอบกลับ

รูปเดี่ยวส่วนใหญ่จะเสร็จและส่งกลับมาในการตอบกลับเดียวกัน เมื่อคิวยุ่งผิดปกติและรูปใช้เวลานานกว่าประมาณ 55 วินาที คุณจะได้ 202 Accepted พร้อม job id แทน งานยังคงทำงานต่อ: ดึงผลลัพธ์ด้วย 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 (ดูด้านล่าง)

Batch ตั้งแต่ต้นจนจบ

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" }'

URL ของรูปสาธารณะสูงสุด 100 รายการ พร้อมตัวเลือกใดก็ได้ของ /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 นับรายการที่ไม่ใช่ URL แบบ 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 ที่เริ่มจากศูนย์ ตำแหน่งเรียงตามรายการของคุณหลังตัด URL ที่ไม่ถูกต้องและซ้ำออก ดังนั้นเมื่อจำนวนใดจำนวนหนึ่งมากกว่า 0 ให้จับคู่ผลลัพธ์ด้วย input แทนลำดับ

• Batch จะไม่นับรวมในขีดจำกัด 3 batch ที่เปิดอยู่อีกต่อไปเมื่อ done เป็น true
• API ไม่มีเอนด์พอยต์ยกเลิก webhook หรือการดาวน์โหลด ZIP ส่วน batch ที่เริ่มในหน้าทีละหลายรูปสามารถยกเลิกหรือดาวน์โหลดเป็น ZIP ได้ที่หน้านั้น

การลองใหม่ รายการซ้ำ และการคิดเครดิต

ส่ง Idempotency-Key แล้วการลองใหม่จะไม่คิดเครดิตซ้ำ เพิ่มเฮดเดอร์ Idempotency-Key (สตริงที่ไม่ซ้ำกันยาวไม่เกิน 255 ตัวอักษร เช่น UUID) ใน POST /v1/remove หรือ POST /v1/batch หนึ่งคีย์ต่อหนึ่งรูปหรือหนึ่ง batch หากคุณส่งคำขอเดิมอีกครั้งด้วยคีย์เดิม คุณจะได้งานที่คำขอแรกสร้างไว้ พร้อม Idempotent-Replayed: true: ไม่มีงานใหม่และไม่คิดเครดิตใหม่ แม้คำขอแรกยังทำงานอยู่ คีย์เดิมกับรูปหรือตัวเลือกที่ต่างกันจะตอบกลับ 409 idempotency_key_reused คีย์เป็นของบัญชีคุณและไม่หมดอายุ

หากไม่มีคีย์ ทุก POST จะสร้างงานใหม่ และแต่ละงานที่สำเร็จใช้ 1 เครดิต (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 หากต้องการให้ผู้ใช้ของคุณลบพื้นหลังได้ ให้ส่งรูปผ่านแบ็กเอนด์ของคุณ และเพิ่มระบบเข้าสู่ระบบและการจำกัดการใช้จ่ายของคุณเองที่นั่น

• API อนุญาต CORS เพื่อให้ใช้งานได้จากเครื่องมือและโค้ดฝั่งเซิร์ฟเวอร์ แต่ไม่ได้ทำให้การใส่คีย์ในหน้าเว็บปลอดภัย: ใครก็อ่านคีย์ได้จากที่นั่น
• ทุกคีย์ในบัญชีใช้ยอดเครดิตเดียวกัน สร้างคีย์แยกสำหรับแต่ละแอปหรือสภาพแวดล้อมในหน้าบัญชีของคุณ เพื่อให้เพิกถอนคีย์หนึ่งได้โดยไม่กระทบคีย์อื่น
• หากคีย์รั่วไหล ให้เพิกถอนในหน้าบัญชีทันที (คีย์จะหยุดทำงานทันที) แล้วสร้างคีย์ใหม่ เราเก็บเพียงค่าแฮชของแต่ละคีย์ จึงแสดงคีย์ให้คุณอีกไม่ได้

การแก้ปัญหา