Arka plan kaldırma API: tek istek gönderin, hazır PNG alın.

Görselinizi gönderin

POST /v1/remove görseli dört yoldan biriyle alır. Bunlardan birini gönderin; bir istekte birden fazlası varsa önce image_file, sonra image_file_b64, sonra image_url, en son ham gövde kullanılır. Bu örnekler anahtarınızı REMOVEBG_API_KEY ortam değişkeninden okur (export REMOVEBG_API_KEY=… ile ayarlayın); kabuğun değeri doldurabilmesi için çift tırnaklara dikkat edin.

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

Her örnek gövdeyi bir dosyaya kaydeder. Bu dosya yalnızca durum 200 olduğunda bir görseldir; Yanıtı işleyin bölümüne bakın.

Yanıtı işleyin

Tek görsellerin çoğu aynı yanıtta hazır olarak döner. Kuyruk alışılmadık derecede yoğun olduğunda ve bir görsel yaklaşık 55 saniyeden uzun sürdüğünde, bunun yerine bir iş kimliğiyle 202 Accepted alırsınız. İş çalışmaya devam eder: sonucunu kimlikle alın. Görseli yeniden göndermek ikinci bir iş başlatır ve ikinci bir krediye mal olabilir.

Eksiksiz bir örnek

Hazır görseli, 202 yanıtını, başarısız olan bir işi ve yerel bir zaman sınırını ele alır. Görseli bir kez gönderir ve yalnızca güvenli durum kontrollerini yeniden dener.

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

• Betiğinizi durdurmak işi durdurmaz; iş yine de tamamlanıp ücretlendirilebilir. Sonucu Stüdyo'nuzda görünür.
• Zaman sınırlarını siz belirlersiniz, bunlar bizim verdiğimiz bir söz değildir; çoğu görsel birkaç saniyede tamamlanır.
• remove.bg uyumlu uç nokta farklı davranır: hiçbir zaman 202 yanıtı vermez (aşağıya bakın).

Baştan sona batch işleri

1. Gönderin

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 adede kadar herkese açık görsel URL'si ve istediğiniz /v1/remove seçenekleri. Yukarıdaki iki yer tutucu URL gerçek görseller olsaydı en fazla 2 krediye mal olurdu. Yanıt hemen gelir:

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) URL'si olmayan girişleri, duplicates ise tekrarları sayar; ikisi de çıkarılır ve hiç ücretlendirilmez. id değerini kaydedin: yeniden başlatmadan sonra işe bununla geri dönersiniz.

2. İşi yoklayın

done değeri true olana kadar birkaç saniyede bir GET /v1/jobs/:id gönderin. status önce queued, sonra processing olur ve succeeded, partial (bazı görseller başarısız) veya failed ile biter. Yeniden denenen bir öğe retrying gösterir.

{
  "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. Her sonucu indirin

Başarılı her öğe için GET /v1/jobs/:id/result?item=N gönderin (veya öğenin result_url adresini kullanın). item, sıfırdan başlayan position değeridir. Konumlar, geçersiz ve tekrarlanan URL'ler çıkarıldıktan sonraki listenizi izler; bu sayılardan biri 0'dan büyükse sonuçları dizinle değil input ile eşleştirin.

• Bir batch, done true olduğunda 3 açık batch sınırına sayılmaz.
• API'de iptal uç noktası, webhook veya ZIP indirme yoktur. Toplu sayfasında başlatılan batch işleri orada iptal edilebilir veya ZIP olarak indirilebilir.

Yeniden denemeler, tekrarlar ve faturalandırma

Bir Idempotency-Key gönderin, yeniden denemeler iki kez ücretlendirilemez. POST /v1/remove veya POST /v1/batch isteğine bir Idempotency-Key başlığı ekleyin (UUID gibi, 255 karaktere kadar benzersiz herhangi bir dize), her görsel veya batch için bir anahtar. Aynı isteği aynı anahtarla yeniden gönderirseniz ilk isteğin oluşturduğu işi Idempotent-Replayed: true ile alırsınız: ilk istek hâlâ çalışıyor olsa bile yeni iş ve yeni ücret yoktur. Aynı anahtar farklı bir görsel veya seçeneklerle gönderilirse 409 idempotency_key_reused yanıtı verir. Anahtarlar hesabınıza aittir ve süreleri dolmaz.

Anahtar olmadan her POST yeni bir iş oluşturur ve başarılı olan her iş 1 kredi tutar (remove.bg uyumlu POST /v1.0/removebg anahtar desteklemez). Bir işi okumak (GET /v1/jobs/…) her zaman ücretsizdir ve güvenle tekrarlanabilir.

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

Ne kredi harcar

Ne zaman yeniden denemeli

Sınırlar ve depolama

Sonuçlar ne kadar saklanır

Her sonuç, oluşturulduktan sonra 48 saat boyunca hesabınızda gizli olarak saklanır, ardından silinir. O zamana kadar GET /v1/jobs/:id/result ile veya Stüdyo'nuzdan ücretsiz olarak yeniden indirebilirsiniz. Bundan sonra sonuç bağlantıları 410 result_unavailable yanıtı verir; görseli yeniden işlemek yeni bir iştir. Görsel silindikten sonra da iş durumu kayıtları okunabilir kalır. Yüklemelerin nasıl işlendiği için gizlilik politikasına bakın; görsellerinizi model eğitmek için kullanmayız.

Güvenlik

API anahtarınızı kontrol ettiğiniz bir sunucuda tutun. Tarayıcı koduna, mobil uygulamalara, herkese açık depolara veya URL'lere koymayın. Kendi kullanıcılarınızın arka plan kaldırmasını istiyorsanız görsellerini kendi arka uç sunucunuz üzerinden gönderin ve kendi giriş ve harcama sınırlarınızı orada ekleyin.

• API, araçlardan ve sunucu tarafı koddan çalışabilmesi için CORS'a izin verir. Bu, bir anahtarı web sayfasına koymayı güvenli hale getirmez: orada herkes okuyabilir.
• Bir hesaptaki tüm anahtarlar aynı kredi bakiyesini harcar. Hesap sayfanızda her uygulama veya ortam için ayrı bir anahtar oluşturun; böylece diğerlerini bozmadan birini iptal edebilirsiniz.
• Bir anahtar sızarsa hesap sayfasında hemen iptal edin (anında çalışmayı durdurur) ve yeni bir tane oluşturun. Her anahtarın yalnızca karmasını (hash) sakladığımız için size onu yeniden gösteremeyiz.

Sorun giderme