{"openapi":"3.1.0","info":{"title":"bgclear.ai Background Removal API","description":"Auth: `Authorization: Bearer <api key>`. Full docs: https://www.bgclear.ai/api-docs/","version":"1.0.0"},"servers":[{"url":"https://www.bgclear.ai"}],"paths":{"/api/v1/remove":{"post":{"tags":["remove"],"summary":"Remove background (sync)","description":"Send one image (`image_file` multipart, or `image_url` / `image_file_b64` in JSON) and get the cutout back. Returns image bytes by default; send `Accept: application/json` for metadata + a result URL. `size=preview` (≤800 px) is free; `size=full` is native resolution. Supports `format` (png|webp|jpg), `bg_color` (hex or transparent), `crop`, and an `Idempotency-Key` header for safe retries.","operationId":"removeBackground","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string","default":"image/png","title":"Accept"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/results/{job_id}":{"get":{"tags":["remove"],"summary":"Download a result","description":"Fetch a stored result (sync JSON mode and async jobs return this URL).\n\nUnauthenticated on purpose: the id is an unguessable UUID4 capability, same\nmodel as the consumer download route, so callback consumers can fetch it\nwith just the URL. Files are purged by the 24 h results cleanup.","operationId":"getResult","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs":{"post":{"tags":["jobs"],"summary":"Create async job","description":"Queue one image for background removal (same inputs and parameters as `/remove`). Use for images over 4 MP or when you want a callback: add an `X-Callback-Url` header and we POST the result there when done. Returns 202 with a `job_id` to poll.","operationId":"createJob","parameters":[{"name":"X-Callback-Url","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Callback-Url"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get job status","description":"Status is `queued`, `processing`, `done` (includes the result `url`) or `failed` (includes `error`).","operationId":"getJob","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/batch":{"post":{"tags":["jobs"],"summary":"Create a batch of jobs (up to 50)","description":"JSON only: `images` is a list of up to 50 objects each with `image_url` or `image_file_b64`; top-level parameters apply to every image. One job is created per image. Available with direct bgclear API keys (per-image billing); not offered through RapidAPI.","operationId":"createBatch","parameters":[{"name":"X-Callback-Url","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Callback-Url"}},{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/account":{"get":{"tags":["account"],"summary":"Account balance and plan","description":"Current credit balance, plan, and credits used this calendar month.","operationId":"getAccount","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/usage":{"get":{"tags":["account"],"summary":"Daily usage (last 30 days)","description":"Credits used per day for the last 30 days, newest first.","operationId":"getUsage","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"type":"string","title":"Authorization"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/health":{"get":{"tags":["health"],"summary":"Health check","description":"Unauthenticated liveness/readiness probe (RapidAPI health check, uptime monitors).\n\nAlways 200 while the process is up. `inference` is \"upstream\" when images\nare forwarded to the GPU shard (GPU_UPSTREAM_URL set) — then readiness does\nnot depend on a local model; \"local\" otherwise, where a cold model still\nserves because it lazy-loads on the first request.","operationId":"health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}