API hapus background: satu request masuk, PNG jadi keluar.

Kirim gambar Anda

POST /v1/remove menerima gambar dengan salah satu dari empat cara. Kirim salah satunya; jika sebuah request membawa beberapa sekaligus, image_file yang dipakai, lalu image_file_b64, lalu image_url, lalu raw body. Contoh-contoh ini membaca key Anda dari environment variable REMOVEBG_API_KEY (atur dengan export REMOVEBG_API_KEY=…); perhatikan tanda kutip ganda, yang membuat shell mengisinya.

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

Setiap contoh menyimpan body ke file. File itu hanya berupa gambar jika statusnya 200; lihat Tangani respons.

Tangani respons

Sebagian besar gambar tunggal kembali dalam keadaan jadi di respons yang sama. Saat antrean sedang sangat sibuk dan sebuah gambar butuh lebih dari sekitar 55 detik, Anda menerima 202 Accepted dengan job id sebagai gantinya. Job tetap berjalan: ambil hasilnya dengan id tersebut. Mengirim ulang gambar akan memulai job kedua dan bisa memakai kredit kedua.

Contoh lengkap

Menangani gambar yang sudah jadi, 202, job yang gagal, dan batas waktu lokal. Contoh ini mengirim gambar sekali dan hanya mengulang pengecekan status yang aman.

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

• Menghentikan skrip Anda tidak menghentikan job; job masih bisa selesai dan dikenai biaya. Hasilnya muncul di Studio Anda.
• Batas waktu itu pilihan Anda, bukan janji dari kami; sebagian besar gambar selesai dalam beberapa detik.
• Endpoint yang kompatibel dengan remove.bg berperilaku berbeda: endpoint itu tidak pernah membalas 202 (lihat di bawah).

Batch, dari awal sampai akhir

1. Kirim

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

Hingga 100 URL gambar publik ditambah opsi apa pun dari /v1/remove. Dua URL placeholder di atas akan memakai hingga 2 kredit jika keduanya gambar sungguhan. Jawabannya langsung datang:

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 menghitung entri yang bukan URL http(s) dan duplicates menghitung entri berulang; keduanya dibuang dan tidak pernah dikenai biaya. Simpan id: itulah cara Anda melanjutkan job setelah restart.

2. Poll job

GET /v1/jobs/:id setiap beberapa detik sampai done bernilai true. status berpindah dari queued ke processing, lalu berakhir sebagai succeeded, partial (sebagian gambar gagal), atau failed. Item yang sedang dicoba ulang menampilkan 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. Unduh setiap hasil

GET /v1/jobs/:id/result?item=N untuk setiap item yang berhasil (atau gunakan result_url-nya). item adalah position yang dimulai dari nol. Posisi mengikuti daftar Anda setelah URL yang tidak valid dan berulang dibuang, jadi jika salah satu hitungan itu di atas 0, cocokkan hasil berdasarkan input, bukan berdasarkan indeks.

• Sebuah batch tidak lagi dihitung ke batas 3 batch terbuka setelah done bernilai true.
• API tidak punya endpoint pembatalan, webhook, atau unduhan ZIP. Batch yang dimulai di halaman Bulk bisa dibatalkan atau diunduh sebagai ZIP di sana.

Percobaan ulang, duplikat, dan tagihan

Kirim Idempotency-Key agar percobaan ulang tidak bisa menagih dua kali. Tambahkan header Idempotency-Key (string unik apa pun hingga 255 karakter, misalnya UUID) ke POST /v1/remove atau POST /v1/batch, satu key per gambar atau batch. Jika Anda mengirim request yang sama lagi dengan key yang sama, Anda mendapat job yang dibuat oleh request pertama, dengan Idempotent-Replayed: true: tanpa job baru dan tanpa tagihan baru, bahkan jika request pertama masih berjalan. Key yang sama dengan gambar atau opsi berbeda akan dibalas 409 idempotency_key_reused. Key terikat ke akun Anda dan tidak kedaluwarsa.

Tanpa key, setiap POST membuat job baru, dan setiap job yang berhasil memakai 1 kredit (POST /v1.0/removebg yang kompatibel dengan remove.bg tidak mendukung key ini). Membaca job (GET /v1/jobs/…) selalu gratis dan aman diulang.

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

Apa yang memakai kredit

Kapan harus mencoba ulang

Batasan dan penyimpanan

Berapa lama hasil disimpan

Setiap hasil disimpan secara privat di akun Anda selama 48 jam setelah dibuat, lalu dihapus. Sampai saat itu Anda bisa mengunduhnya lagi secara gratis dengan GET /v1/jobs/:id/result atau dari Studio Anda. Setelah itu, link hasil membalas 410 result_unavailable; memproses gambar lagi berarti job baru. Catatan status job tetap bisa dibaca setelah gambarnya hilang. Lihat kebijakan privasi untuk cara unggahan ditangani; kami tidak menggunakan gambar Anda untuk melatih model.

Keamanan

Simpan API key Anda di server yang Anda kendalikan. Jangan menaruhnya di kode browser, aplikasi seluler, repositori publik, atau URL. Agar pengguna Anda sendiri bisa menghapus background, kirim gambar mereka melalui backend Anda, dan tambahkan login serta batas pengeluaran Anda sendiri di sana.

• API mengizinkan CORS agar bisa dipakai dari tool dan kode di sisi server. Itu tidak membuat key aman ditaruh di halaman web: siapa pun bisa membacanya di sana.
• Semua key di satu akun memakai saldo kredit yang sama. Buat key terpisah untuk setiap aplikasi atau environment di halaman akun Anda, agar Anda bisa mencabut satu key tanpa mengganggu yang lain.
• Jika sebuah key bocor, segera cabut di halaman akun (key langsung berhenti berfungsi) dan buat key baru. Kami hanya menyimpan hash setiap key, jadi kami tidak bisa menampilkannya lagi kepada Anda.

Pemecahan masalah