API tách nền: gửi một yêu cầu, nhận PNG hoàn chỉnh.

Gửi ảnh

POST /v1/remove nhận ảnh theo bốn cách. Hãy gửi một trong số đó; nếu một yêu cầu chứa nhiều cách, image_file được ưu tiên, rồi đến image_file_b64, rồi image_url, rồi body thô. Các ví dụ này đọc khóa từ biến môi trường REMOVEBG_API_KEY (đặt bằng export REMOVEBG_API_KEY=…); lưu ý dấu nháy kép, giúp shell điền giá trị vào.

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

Mọi ví dụ đều lưu body vào tệp. Tệp đó chỉ là ảnh khi mã trạng thái là 200; xem Xử lý phản hồi.

Xử lý phản hồi

Hầu hết ảnh đơn được trả về hoàn chỉnh trong cùng phản hồi. Khi hàng đợi bận bất thường và một ảnh mất hơn khoảng 55 giây, bạn sẽ nhận 202 Accepted kèm job id. Job vẫn tiếp tục chạy: lấy kết quả bằng id đó. Gửi lại ảnh sẽ tạo job thứ hai và có thể tốn thêm một credit.

Ví dụ đầy đủ

Xử lý ảnh hoàn chỉnh, mã 202, job thất bại và giới hạn thời gian phía bạn. Ví dụ chỉ gửi ảnh một lần và chỉ thử lại các lần kiểm tra trạng thái an toàn.

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"))

• Dừng script không dừng job; job vẫn có thể hoàn tất và bị tính phí. Kết quả sẽ xuất hiện trong Studio của bạn.
• Giới hạn thời gian do bạn chọn, không phải cam kết từ chúng tôi; hầu hết ảnh xong trong vài giây.
• Endpoint tương thích remove.bg hoạt động khác: nó không bao giờ trả về 202 (xem bên dưới).

Batch, từ đầu đến cuối

1. Gửi

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

Tối đa 100 URL ảnh công khai cùng bất kỳ tùy chọn nào của /v1/remove. Hai URL giữ chỗ ở trên sẽ tốn tối đa 2 credit nếu là ảnh thật. Phản hồi trả về ngay lập tức:

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 đếm các mục không phải URL http(s) và duplicates đếm các mục lặp lại; cả hai đều bị loại bỏ và không bao giờ bị tính phí. Hãy lưu id: đó là cách bạn tiếp tục theo dõi job sau khi khởi động lại.

2. Kiểm tra job định kỳ

GET /v1/jobs/:id vài giây một lần cho đến khi done là true. status chuyển từ queued sang processing, rồi kết thúc ở succeeded, partial (một số ảnh lỗi) hoặc failed. Mục đang được thử lại hiển thị 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. Tải từng kết quả

GET /v1/jobs/:id/result?item=N cho mỗi mục thành công (hoặc dùng result_url của nó). item là position bắt đầu từ 0. Thứ tự vị trí theo danh sách của bạn sau khi loại bỏ URL không hợp lệ và trùng lặp, nên khi một trong hai số đếm lớn hơn 0, hãy khớp kết quả theo input thay vì theo chỉ số.

• Một batch không còn tính vào giới hạn 3 batch đang mở khi done là true.
• API không có endpoint hủy, webhook hay tải ZIP. Các batch bắt đầu từ trang Hàng loạt có thể được hủy hoặc tải về dạng ZIP tại đó.

Thử lại, trùng lặp và tính phí

Gửi Idempotency-Key để các lần thử lại không bị tính phí hai lần. Thêm header Idempotency-Key (bất kỳ chuỗi duy nhất nào dài tối đa 255 ký tự, như UUID) vào POST /v1/remove hoặc POST /v1/batch, mỗi ảnh hoặc batch một khóa. Nếu bạn gửi lại cùng yêu cầu với cùng khóa, bạn nhận được job mà yêu cầu đầu tiên đã tạo, kèm Idempotent-Replayed: true: không có job mới và không tính phí mới, kể cả khi yêu cầu đầu tiên vẫn đang chạy. Cùng khóa với ảnh hoặc tùy chọn khác sẽ trả về 409 idempotency_key_reused. Khóa thuộc về tài khoản của bạn và không hết hạn.

Không có khóa, mỗi POST tạo một job mới, và mỗi job thành công tốn 1 credit (endpoint tương thích remove.bg POST /v1.0/removebg không hỗ trợ khóa này). Đọc job (GET /v1/jobs/…) luôn miễn phí và an toàn để lặp lại.

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

Điều gì tốn credit

Khi nào nên thử lại

Giới hạn và lưu trữ

Kết quả được lưu trong bao lâu

Mọi kết quả được lưu riêng tư trong tài khoản của bạn trong 48 giờ sau khi tạo, sau đó bị xóa. Trong thời gian đó, bạn có thể tải lại miễn phí bằng GET /v1/jobs/:id/result hoặc từ Studio. Sau đó, liên kết kết quả trả về 410 result_unavailable; xử lý lại ảnh là một job mới. Bản ghi trạng thái job vẫn đọc được sau khi ảnh đã bị xóa. Xem chính sách quyền riêng tư để biết cách xử lý tệp tải lên; chúng tôi không dùng ảnh của bạn để huấn luyện mô hình.

Bảo mật

Giữ khóa API trên máy chủ do bạn kiểm soát. Đừng đặt khóa trong code trình duyệt, ứng dụng di động, kho mã công khai hay URL. Để người dùng của bạn tách nền, hãy gửi ảnh của họ qua backend của bạn, và thêm cơ chế đăng nhập cùng giới hạn chi tiêu riêng tại đó.

• API cho phép CORS để hoạt động từ các công cụ và code phía máy chủ. Điều đó không có nghĩa là an toàn khi đặt khóa trong trang web: bất kỳ ai cũng có thể đọc được.
• Mọi khóa trong một tài khoản đều dùng chung số dư credit. Hãy tạo một khóa riêng cho mỗi ứng dụng hoặc môi trường ở trang tài khoản, để có thể thu hồi một khóa mà không ảnh hưởng các khóa khác.
• Nếu khóa bị lộ, hãy thu hồi ngay ở trang tài khoản (khóa ngừng hoạt động lập tức) và tạo khóa mới. Chúng tôi chỉ lưu giá trị băm của mỗi khóa, nên không thể hiển thị lại khóa cho bạn.

Khắc phục sự cố