背景削除 API：リクエスト 1 回で、完成した PNG を返却。

画像を送信する

POST /v1/remove は 4 つの方法で画像を受け付けます。いずれか 1 つを送信してください。1 つのリクエストに複数含まれている場合は、image_file、image_file_b64、image_url、生のボディの順に優先されます。これらの例では、キーを環境変数 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

どの例もボディをファイルに保存します。そのファイルが画像になるのはステータスが 200 の場合だけです。レスポンスを処理するをご覧ください。

レスポンスを処理する

ほとんどの単一画像は、同じレスポンスで完成した状態で返ってきます。キューが特に混雑していて、画像の処理に約 55 秒以上かかる場合は、代わりにジョブ ID 付きの 202 Accepted が返されます。ジョブは引き続き実行されるので、ID を使って結果を取得してください。画像を再送信すると 2 つ目のジョブが開始され、2 クレジット目が消費される可能性があります。

完全な例

完成した画像、202、失敗したジョブ、ローカルの時間制限をすべて処理します。画像の送信は 1 回だけで、再試行するのは安全なステータス確認のみです。

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 を返すことはありません（下記参照）。

バッチの最初から最後まで

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

最大 100 件の公開画像 URL と、/v1/remove の任意のオプションを送信します。上記の 2 つのプレースホルダー 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 は http(s) URL ではない項目の数、duplicates は重複の数です。どちらも除外され、課金されません。id は保存しておいてください。再起動後にジョブを再開する際に必要です。

2. ジョブをポーリング

done が true になるまで、数秒ごとに GET /v1/jobs/:id を呼び出します。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 は 0 から始まる position です。位置は無効な URL と重複した URL を除いた後のリストの順序に従うため、どちらかの数が 0 より大きい場合は、インデックスではなく input で結果を照合してください。

• done が true になると、そのバッチは未完了バッチの上限 3 件にカウントされなくなります。
• API にはキャンセル用のエンドポイント、Webhook、ZIP ダウンロードはありません。一括処理ページで開始したバッチは、そのページでキャンセルや ZIP でのダウンロードができます。

再試行、重複、課金

Idempotency-Key を送信すれば、再試行で二重に課金されることはありません。POST /v1/remove または POST /v1/batch に Idempotency-Key ヘッダー（UUID など、255 文字以内の一意の文字列）を追加してください。キーは画像またはバッチごとに 1 つです。同じキーで同じリクエストを再送信すると、最初のリクエストで作成されたジョブが Idempotent-Replayed: true 付きで返されます。最初のリクエストがまだ実行中でも、新しいジョブは作成されず、新たな課金も発生しません。同じキーで異なる画像やオプションを送信すると、409 idempotency_key_reused が返されます。キーはアカウントに紐づき、有効期限はありません。

キーがない場合、POST のたびに新しいジョブが作成され、成功したジョブごとに 1 クレジットが消費されます（remove.bg 互換の POST /v1.0/removebg はキーに対応していません）。ジョブの読み取り（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 を許可しています。ただし、ウェブページにキーを埋め込んでも安全になるわけではありません。誰でもそこからキーを読み取れます。
• アカウント内のすべてのキーは同じクレジット残高を消費します。アカウントページでアプリや環境ごとに別々のキーを作成すれば、他のキーに影響を与えずに 1 つだけ無効化できます。
• キーが漏えいした場合は、すぐにアカウントページで無効化し（即座に使用できなくなります）、新しいキーを作成してください。当社は各キーのハッシュ値のみを保存しているため、キーを再表示することはできません。

トラブルシューティング