# Car Background (Binary)

Put the car on a new background and return the result as a JPEG.

**Cost:** 1 credit on HTTP 200.

The biggest car in the photo is cut out and placed on `background_preset`, in the photo's own perspective. With `match_photo_light` (default) the new shadow follows the car's existing shadow; with `frame` (default) the output is recomposed around the car at `frame_aspect`.

For the matching transparent cutout, separate layers, and frame/light metadata, use the Base64 JSON sibling `/v1.0/car-layers-base64`. Response metadata is returned in `X-Input-Dimensions`, `X-Processed-Dimensions`, `X-Was-Downscaled`, `X-Output-Dimensions`, `X-Background-Preset`, `X-Light-Azimuth`, `X-Light-Elevation`, and `X-Light-Softness`.

---

## Endpoint

**POST** `/v1.0/car-background`

Base URL: `https://api.withoutbg.com`

## Authentication

Provide your API key in the request header:

```
X-API-Key: <your_api_key>
```

## Request

**Content-Type:** `multipart/form-data`

### Fields

- `file` *(string, required)* — Car image file (JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF). Maximum size: 20.0 MB.
- `background_preset` *(string, optional, default `"white-seamless"`)* — Backdrop the car is composited onto. Rendered procedurally in the photo's recovered camera, so perspective matches. Fine-tune it with `scene_overrides`. Previews: https://withoutbg.com/docs/pro-model/car-layers-base64#background_preset
  - `white-seamless` — Infinite white sweep, almost no direction.
  - `grey-sweep` — Neutral grey cyc with a shaped pool, the catalogue look.
  - `graphite` — Dark grey room, pool carries the separation.
  - `graphite-floor` — White wall over a graphite grey floor.
  - `warm-showroom` — Warm walls over a darker floor.
  - `dark-hero` — Near-black room with a tight pool under the car.
- `frame` *(boolean, optional, default `true`)* — When true (default), reframe the output: the car fills about 60% of the frame width with headroom above and floor below, its shadow kept in frame. When false, the output keeps the photo's framing and size.
- `frame_aspect` *(string, optional, default `"4:3"`)* — Output aspect ratio (width:height) when `frame` is true. `original` keeps the photo's own ratio. Ignored when `frame` is false. Shapes: https://withoutbg.com/docs/pro-model/car-layers-base64#frame_aspect
  - `4:3` — Landscape, the marketplace listing default.
  - `3:2` — Landscape, matches most DSLR photos.
  - `16:9` — Wide banner or website hero.
  - `1:1` — Square, for social posts and thumbnails.
  - `original` — Keep the photo's own width:height ratio.
- `frame_grow` *(boolean, optional, default `true`)* — When true (default) and the ideal frame reaches past the photo's edge, extend the rendered backdrop instead of cropping tighter. When false, the frame stays inside the photo: it keeps `frame_aspect` and may trim the car's front and rear when the car fills the photo.
- `match_photo_light` *(boolean, optional, default `true`)* — When true (default), detect the car's existing shadow in the photo and fit the light direction to it, so the new shadow falls the same way. Falls back to the default light when no usable shadow is found.
- `reconstruct_windows` *(boolean, optional, default `true`)* — When true (default), run car window reconstruction: opens glass interiors while keeping the car outline. Set false to skip and use the base silhouette alpha only.

## Response

**Success Content-Type:** `image/jpeg`

### Response headers

- `X-Input-Dimensions` — Decoded input size as `width,height` (pixels).
- `X-Processed-Dimensions` — Size after server prep downscale (longest side / megapixel caps) as `width,height`. Not the model inference resolution (~1024 long side).
- `X-Was-Downscaled` — Whether the input was downscaled during server prep (`true`/`false`).
- `X-Output-Dimensions` — Size of the returned image as `width,height`: the frame box when `frame` is true, else the processed size.
- `X-Background-Preset` — Background preset that was rendered. Today the requested `background_preset`; read it from here, not from the request.
- `X-Light-Azimuth` — Light azimuth around the car, in degrees (as `light.azimuth_deg`).
- `X-Light-Elevation` — Light elevation above the ground, in degrees (as `light.elevation_deg`).
- `X-Light-Softness` — Light softness, 0 = hard to 1 = very soft (as `light.softness`).

## Errors

| Status | Description |
|--------|-------------|
| 401 | Invalid API Key |
| 402 | Insufficient credit. Please top up API credits. |
| 403 | Credits Expired. Please top up API credits. If you have existing credits, they will be reactivated. |
| 413 | File size too large. Maximum file size is 20.0 MB |
| 415 | Unsupported Media Type. Supported formats are: JPEG, PNG, WebP, AVIF, HEIC, TIFF, BMP, GIF. |
| 422 | Validation Error |
| 429 | {"error":"Too Many Requests","status":429,"message":"Rate limit exceeded. Please try again later"} |
| 500 | Internal Server Error. Please contact support: contact@withoutbg.com |

## Example (cURL)

```bash
curl -X POST \
  -H "X-API-Key: $WITHOUTBG_API_KEY" \
  -F "file=@/path/to/input.jpg" \
  --output result.png \
  "https://api.withoutbg.com/v1.0/car-background"
```

---

Source of truth: [OpenAPI](https://api.withoutbg.com/openapi.json) · Docs: [/docs/pro-model/car-background-binary](/docs/pro-model/car-background-binary)